X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fncurses.3x;h=14900d94efd73868e5e5cef17d5e0e6ea0d1ba10;hp=374eb5bce6f19e3b4dc5420eaad797b50525c337;hb=5e36f11feab6f790e0cc6f2c882a67b7b65e3b6b;hpb=d448186ac240901c6976dc74c260f052d3ed53e4 diff --git a/man/ncurses.3x b/man/ncurses.3x index 374eb5bc..14900d94 100644 --- a/man/ncurses.3x +++ b/man/ncurses.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2009,2010 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2010,2011 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * .\" copy of this software and associated documentation files (the * @@ -27,9 +27,12 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: ncurses.3x,v 1.97 2010/09/11 20:54:13 tom Exp $ +.\" $Id: ncurses.3x,v 1.106 2011/12/17 23:19:59 tom Exp $ .hy 0 .TH ncurses 3X "" +.de bP +.IP \(bu 4 +.. .ds n 5 .ds d @TERMINFO@ .SH NAME @@ -105,9 +108,9 @@ Most programs would additionally use the sequence: .sp Before a \fBcurses\fR program is run, the tab stops of the terminal should be set and its initialization strings, if defined, must be output. -This can be done by executing the \fBtput init\fR command +This can be done by executing the \fB@TPUT@ init\fR command after the shell environment variable \fBTERM\fR has been exported. -\fBtset(1)\fR is usually responsible for doing this. +\fB@TSET@(1)\fR is usually responsible for doing this. [See \fBterminfo\fR(\*n) for further details.] .PP The \fBncurses\fR library permits manipulation of data structures, @@ -731,6 +734,9 @@ Routines that return an integer return \fBERR\fR upon failure and an integer value other than \fBERR\fR upon successful completion, unless otherwise noted in the routine descriptions. .PP +As a general rule, routines check for null pointers passed as parameters, +and handle this as an error. +.PP All macros return the value of the \fBw\fR version, except \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and \fBgetmaxyx\fR. The return values of \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and @@ -927,6 +933,28 @@ and is likely to work for terminal emulators. When setting this variable, you should set it to a nonzero value. Setting it to zero (or to a nonnumber) disables the special check for "linux" and "screen". +.IP +As an alternative to the environment variable, +ncurses checks for an extended terminfo capability \fBU8\fP. +This is a numeric capability which can be compiled using \fB@TIC@\ \-x\fP. +For example +.RS 5 +.sp +.nf +# linux console, if patched to provide working +# VT100 shift-in/shift-out, with corresponding font. +linux-vt100|linux console with VT100 line-graphics, + U8#0, use=linux, +.sp +# uxterm with vt100Graphics resource set to false +xterm-utf8|xterm relying on UTF-8 line-graphics, + U8#1, use=xterm, +.fi +.RE +.IP +The name "U8" is chosen to be two characters, +to permit it to be used by applications that use ncurses' +termcap interface. .TP 5 NCURSES_TRACE During initialization, the \fBncurses\fR debugging library @@ -960,20 +988,15 @@ description. This is the simplest, but not the only way to change the list of directories. The complete list of directories in order follows: .RS -.TP 3 -\- +.bP the last directory to which \fBncurses\fR wrote, if any, is searched first -.TP 3 -\- +.bP the directory specified by the TERMINFO symbol -.TP 3 -\- +.bP $HOME/.terminfo -.TP 3 -\- +.bP directories listed in the TERMINFO_DIRS symbol -.TP 3 -\- +.bP one or more directories whose names are configured and compiled into the ncurses library, e.g., @TERMINFO@ @@ -984,6 +1007,13 @@ Specifies a list of directories to search for terminal descriptions. The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX. All of the terminal descriptions are in terminfo form, which makes a subdirectory named for the first letter of the terminal names therein. +.IP +If \fBncurses\fP is built with a hashed database, +then each entry in this list can also be the path of the corresponding +database file. +.IP +If \fBncurses\fP is built with a support for reading termcap files +directly, then an entry in this list may be the path of a termcap file. .TP 5 TERMPATH If TERMCAP does not hold a file name then \fBncurses\fR checks @@ -1075,6 +1105,8 @@ terminal capability database .SH SEE ALSO \fBterminfo\fR(\*n) and related pages whose names begin "curs_" for detailed routine descriptions. +.br +\fBcurs_variables\fR(3X) .SH EXTENSIONS The \fBncurses\fR library can be compiled with an option (\fB\-DUSE_GETCAP\fR) that falls back to the old-style /etc/termcap file if the terminal setup code @@ -1122,30 +1154,45 @@ A small number of local differences (that is, individual differences between the XSI Curses and \fBncurses\fR calls) are described in \fBPORTABILITY\fR sections of the library man pages. .PP -This implementation also contains several extensions: -.RS 5 +Unlike other implementations, this one checks parameters such as pointers +to WINDOW structures to ensure they are not null. +The main reason for providing this behavior is to guard against programmer +error. +The standard interface does not provide a way for the library +to tell an application which of several possible errors were detected. +Relying on this (or some other) extension will adversely affect the +portability of curses applications. .PP +This implementation also contains several extensions: +.bP The routine \fBhas_key\fR is not part of XPG4, nor is it present in SVr4. See the \fBcurs_getch\fR(3X) manual page for details. -.PP +.bP The routine \fBslk_attr\fR is not part of XPG4, nor is it present in SVr4. See the \fBcurs_slk\fR(3X) manual page for details. -.PP +.bP The routines \fBgetmouse\fR, \fBmousemask\fR, \fBungetmouse\fR, \fBmouseinterval\fR, and \fBwenclose\fR relating to mouse interfacing are not part of XPG4, nor are they present in SVr4. See the \fBcurs_mouse\fR(3X) manual page for details. -.PP +.bP The routine \fBmcprint\fR was not present in any previous curses implementation. See the \fBcurs_print\fR(3X) manual page for details. -.PP +.bP The routine \fBwresize\fR is not part of XPG4, nor is it present in SVr4. See the \fBwresize\fR(3X) manual page for details. -.PP +.bP The WINDOW structure's internal details can be hidden from application programs. See \fBcurs_opaque\fR(3X) for the discussion of \fBis_scrollok\fR, etc. -.RE +.bP +This implementation can be configured to provide rudimentary support +for multi-threaded applications. +See \fBcurs_threads\fR(3X) for details. +.bP +This implementation can also be configured to provide a set of functions which +improve the ability to manage multiple screens. +See \fBcurs_sp_funcs\fR(3X) for details. .PP In historic curses versions, delays embedded in the capabilities \fBcr\fR, \fBind\fR, \fBcub1\fR, \fBff\fR and \fBtab\fR activated corresponding delay @@ -1164,9 +1211,3 @@ This was an undocumented feature of AT&T System V Release 3 curses. .SH AUTHORS Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. Based on pcurses by Pavel Curtis. -.\"# -.\"# The following sets edit modes for GNU EMACS -.\"# Local Variables: -.\"# mode:nroff -.\"# fill-column:79 -.\"# End: