ncurses 5.9 - patch 20130720
[ncurses.git] / man / curs_terminfo.3x
index 12d4b0fe044d17ac80d8ab3ebc120e4c35a0b96c..7d440bf53ebca8388f5df312e241ac3dd93a232b 100644 (file)
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_terminfo.3x,v 1.38 2013/07/13 23:12:13 tom Exp $
+.\" $Id: curs_terminfo.3x,v 1.43 2013/07/20 19:29:59 tom Exp $
 .TH curs_terminfo 3X ""
+.ie \n(.g .ds `` \(lq
+.el       .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el       .ds '' ''
 .de bP
 .IP \(bu 4
 ..
@@ -101,40 +105,54 @@ directly with the \fBterminfo\fR database to handle certain terminal
 capabilities, such as programming function keys.  For all other
 functionality, \fBcurses\fR routines are more suitable and their use is
 recommended.
+.SS Initialization
 .PP
 Initially, \fBsetupterm\fR should be called.  Note that
 \fBsetupterm\fR is automatically called by \fBinitscr\fR and
 \fBnewterm\fR.  This defines the set of terminal-dependent variables
 [listed in \fBterminfo\fR(\*n)].
+.PP
+Each initialization routine provides applications with the
+terminal capabilities either directly (via header definitions),
+or by special functions.
+The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this
+order) to get the definitions for these strings, numbers, and flags.
+.PP
 The \fBterminfo\fR variables
 \fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR as
 follows:
-.RS
-.PP
+.bP
 If \fBuse_env(FALSE)\fR has been called, values for
 \fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used.
-.PP
+.bP
 Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR
 exist, their values are used.  If these environment variables do not
 exist and the program is running in a window, the current window size
 is used.  Otherwise, if the environment variables do not exist, the
 values for \fBlines\fR and \fBcolumns\fR specified in the
 \fBterminfo\fR database are used.
-.RE
 .PP
-The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this
-order) to get the definitions for these strings, numbers, and flags.
 Parameterized strings should be passed through \fBtparm\fR to instantiate them. 
 All \fBterminfo\fR strings [including the output of \fBtparm\fR] should be printed
-with \fBtputs\fR or \fBputp\fR.  Call the \fBreset_shell_mode\fR to restore the
-tty modes before exiting [see \fBcurs_kernel\fR(3X)].  Programs which use
-cursor addressing should output \fBenter_ca_mode\fR upon startup and should
-output \fBexit_ca_mode\fR before exiting.  Programs desiring shell escapes
-should call
+with \fBtputs\fR or \fBputp\fR.
+Call \fBreset_shell_mode\fR to restore the
+tty modes before exiting [see \fBcurs_kernel\fR(3X)].
 .PP
-\fBreset_shell_mode\fR and output \fBexit_ca_mode\fR before the shell
-is called and should output \fBenter_ca_mode\fR and call
-\fBreset_prog_mode\fR after returning from the shell.
+Programs which use
+cursor addressing should
+.bP
+output \fBenter_ca_mode\fR upon startup and
+.bP
+output \fBexit_ca_mode\fR before exiting.
+.PP
+Programs which execute shell subprocesses should
+.bP
+call \fBreset_shell_mode\fR and
+output \fBexit_ca_mode\fR before the shell
+is called and
+.bP
+output \fBenter_ca_mode\fR and
+call \fBreset_prog_mode\fR after returning from the shell.
 .PP
 The \fBsetupterm\fR routine reads in the \fBterminfo\fR database,
 initializing the \fBterminfo\fR structures, but does not set up the
@@ -149,7 +167,6 @@ then \fBsetupterm\fR returns \fBOK\fR or
 A return value of \fBOK\fR combined with status of \fB1\fR in \fIerrret\fR
 is normal.
 If \fBERR\fR is returned, examine \fIerrret\fR:
-.RS
 .TP 5
 .B 1
 means that the terminal is hardcopy, cannot be used for curses applications.
@@ -167,7 +184,6 @@ checking the \fIgn\fP (\fIgeneric\fP) capability.
 .TP 5
 .B \-1
 means that the \fBterminfo\fR database could not be found.
-.RE
 .PP
 If \fIerrret\fR is
 null, \fBsetupterm\fR prints an error message upon finding an error
@@ -177,18 +193,33 @@ and exits.  Thus, the simplest call is:
 .sp
 which uses all the defaults and sends the output to \fBstdout\fR.
 .PP
-The \fBsetterm\fR routine is being replaced by \fBsetupterm\fR.  The call:
+The \fBsetterm\fR routine was replaced by \fBsetupterm\fR.  The call:
 .sp
       \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR
 .sp
 provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR.
-The \fBsetterm\fR routine is included here for BSD compatibility, and
+The \fBsetterm\fR routine is provided for BSD compatibility, and
 is not recommended for new programs.
-.PP
-The \fBset_curterm\fR routine sets the variable \fBcur_term\fR to
+.\" ***************************************************************************
+.SS The Terminal State
+.PP
+The \fBsetupterm\fR routine stores its information about the terminal
+in a \fBTERMINAL\fP structure pointed to by the global variable \fBcur_term\fP.
+If it detects an error,
+or decides that the terminal is unsuitable (hardcopy or generic),
+it discards this information,
+making it not available to applications.
+.PP
+If \fBsetupterm\fP is called repeatedly for the same terminal type,
+it will reuse the information.
+It maintains only one copy of a given terminal's capabilities in memory.
+If it is called for different terminal types,
+\fBsetupterm\fP allocates new storage for each set of terminal capabilities.
+.PP
+The \fBset_curterm\fR routine sets \fBcur_term\fR to
 \fInterm\fR, and makes all of the \fBterminfo\fR boolean, numeric, and
-string variables use the values from \fInterm\fR.  It returns the old value
-of \fBcur_term\fR.
+string variables use the values from \fInterm\fR.
+It returns the old value of \fBcur_term\fR.
 .PP
 The \fBdel_curterm\fR routine frees the space pointed to by
 \fIoterm\fR and makes it available for further use.  If \fIoterm\fR is
@@ -198,11 +229,14 @@ memory locations until another \fBsetupterm\fR has been called.
 .PP
 The \fBrestartterm\fR routine is similar to \fBsetupterm\fR and \fBinitscr\fR,
 except that it is called after restoring memory to a previous state (for
-example, when reloading a game saved as a core image dump).  It assumes that
-the windows and the input and output options are the same as when memory was
-saved, but the terminal type and baud rate may be different.  Accordingly,
-it saves various tty state bits, calls \fBsetupterm\fP,
-and then restores the bits.
+example, when reloading a game saved as a core image dump).
+\fBrestartterm\fP assumes that the windows and the input and output options
+are the same as when memory was saved,
+but the terminal type and baud rate may be different.
+Accordingly, \fBrestartterm\fP saves various tty state bits,
+calls \fBsetupterm\fP, and then restores the bits.
+.\" ***************************************************************************
+.SS Formatting Output
 .PP
 The \fBtparm\fR routine instantiates the string \fIstr\fR with
 parameters \fIpi\fR.  A pointer is returned to the result of \fIstr\fR
@@ -211,6 +245,8 @@ with the parameters applied.
 \fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI<stdarg.h>\fP
 rather than a fixed-parameter list.
 Its numeric parameters are integers (int) rather than longs.
+.\" ***************************************************************************
+.SS Output Functions
 .PP
 The \fBtputs\fR routine applies padding information to the string
 \fIstr\fR and outputs it.  The \fIstr\fR must be a terminfo string
@@ -244,26 +280,48 @@ Currently, applications must provide a null pointer for that argument.
 .PP
 The \fBmvcur\fR routine provides low-level cursor motion.  It takes
 effect immediately (rather than at the next refresh).
+.\" ***************************************************************************
+.SS Terminal Capability Functions
 .PP
 The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return
 the value of the capability corresponding to the \fBterminfo\fR
 \fIcapname\fR passed to them, such as \fBxenl\fR.
-.PP
-The \fBtigetflag\fR routine returns the value \fB\-1\fR if
-\fIcapname\fR is not a boolean capability,
-or \fB0\fR if it is canceled or absent from the terminal description.
-.PP
-The \fBtigetnum\fR routine returns the value \fB\-2\fR if
-\fIcapname\fR is not a numeric capability,
-or \fB\-1\fR if it is canceled or absent from the terminal description.
-.PP
-The \fBtigetstr\fR routine returns the value \fB(char *)\-1\fR
-if \fIcapname\fR is not a string capability,
-or \fB0\fR if it is canceled or absent from the terminal description.
-.PP
 The \fIcapname\fR for each capability is given in the table column entitled
 \fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n).
-.sp
+.PP
+These routines return special values to denote errors.
+.PP
+The \fBtigetflag\fR routine returns
+.TP
+\fB\-1\fR
+if \fIcapname\fR is not a boolean capability,
+or
+.TP
+\fB0\fR
+if it is canceled or absent from the terminal description.
+.PP
+The \fBtigetnum\fR routine returns
+.TP
+\fB\-2\fR
+if \fIcapname\fR is not a numeric capability, or
+.TP
+\fB\-1\fR
+if it is canceled or absent from the terminal description.
+.PP
+The \fBtigetstr\fR routine returns
+.TP
+\fB(char *)\-1\fR
+if \fIcapname\fR is not a string capability,
+or
+.TP
+\fB0\fR
+if it is canceled or absent from the terminal description.
+.\" ***************************************************************************
+.SS Terminal Capability Names
+These null-terminated arrays contain
+the short terminfo names ("codes"),
+the \fBtermcap\fR names, and the long terminfo names ("fnames")
+for each of the predefined \fBterminfo\fR variables:
 .RS
 \fBchar *boolnames[]\fR, \fB*boolcodes[]\fR, \fB*boolfnames[]\fR
 .sp
@@ -271,10 +329,6 @@ The \fIcapname\fR for each capability is given in the table column entitled
 .sp
 \fBchar *strnames[]\fR, \fB*strcodes[]\fR, \fB*strfnames[]\fR
 .RE
-.PP
-These null-terminated arrays contain the \fIcapnames\fR, the
-\fBtermcap\fR codes, and the full C names, for each of the
-\fBterminfo\fR variables.
 .SH RETURN VALUE
 Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
 (SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
@@ -309,15 +363,12 @@ It does not detect I/O errors:
 X/Open states that \fBtputs\fP ignores the return value
 of the output function \fIputc\fP.
 .RE
-.SH NOTES
-The \fBsetupterm\fR routine should be used in place of \fBsetterm\fR.
-It may be useful when you want to test for terminal capabilities without
-committing to the allocation of storage involved in \fBinitscr\fR.
-.PP
-Note that \fBvidattr\fR and \fBvidputs\fR may be macros.
 .SH PORTABILITY
+X/Open notes that \fBvidattr\fR and \fBvidputs\fR may be macros.
+.PP
 The function \fBsetterm\fR is not described by X/Open and must
-be considered non-portable.  All other functions are as described by X/Open.
+be considered non-portable.
+All other functions are as described by X/Open.
 .PP
 \fBsetupterm\fP copies the terminal name to the array \fBttytype\fP.
 This is not part of X/Open Curses, but is assumed by some applications.
@@ -326,11 +377,11 @@ If configured to use the terminal-driver,
 e.g., for the MinGW port,
 .bP
 \fBsetupterm\fP interprets a missing/empty TERM variable as the
-special value ``unknown''.
+special value \*(``unknown\*(''.
 .bP
 \fBsetupterm\fP allows explicit use of the
 the windows console driver by checking if $TERM is set to
-``#win32con'' or an abbreviation of that string.
+\*(``#win32con\*('' or an abbreviation of that string.
 .PP
 Older versions of \fBncurses\fP assumed that the file descriptor passed to
 \fBsetupterm\fP from \fBinitscr\fP or \fBnewterm\fP uses buffered I/O,
@@ -366,7 +417,7 @@ Portable applications should provide 9 parameters after the format;
 zeroes are fine for this purpose.
 .PP
 In response to comments by Thomas E. Dickey,
-X/Open Curses Issue 7 proposed the \fBtiparam\fP function in mid-2009.
+X/Open Curses Issue 7 proposed the \fBtiparm\fP function in mid-2009.
 .PP
 X/Open notes that after calling \fBmvcur\fR, the curses state may not match the
 actual terminal state, and that an application should touch and refresh
@@ -380,8 +431,12 @@ X/Open states that the old location must be given for \fBmvcur\fP.
 This implementation allows the caller to use \-1's for the old ordinates.
 In that case, the old location is unknown.
 .PP
+Other implementions may not declare the capability name arrays.
+Some provide them without declaring them.
+X/Open does not specify them.
+.PP
 Extended terminal capability names, e.g., as defined by \fB@TIC@\ \-x\fP,
-are not stored in the arrays described in this section.
+are not stored in the arrays described here.
 .SH SEE ALSO
 \fBcurses\fR(3X),
 \fBcurs_initscr\fR(3X),