X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_terminfo.3x;h=7d440bf53ebca8388f5df312e241ac3dd93a232b;hp=12d4b0fe044d17ac80d8ab3ebc120e4c35a0b96c;hb=7517964d4343789c36b7ded32feb81961b03b725;hpb=ba78eb501a2ed01647123dbe7279ca0f38782e04 diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x index 12d4b0fe..7d440bf5 100644 --- a/man/curs_terminfo.3x +++ b/man/curs_terminfo.3x @@ -26,8 +26,12 @@ .\" 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\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),