X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_terminfo.3x;h=229da5d63b6c30c5ef9c1034f970f6438a86ea11;hp=1b31a02d6ecc98a8b4b6ddcc765a6cafea63e340;hb=14d46fadc442db9df4567357cda396235418120e;hpb=3a9b6a3bf0269231bef7de74757a910dedd04e0c diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x index 1b31a02d..229da5d6 100644 --- a/man/curs_terminfo.3x +++ b/man/curs_terminfo.3x @@ -1,213 +1,647 @@ -.\" $Id: curs_terminfo.3x,v 1.6 1996/06/15 22:45:50 tom Exp $ +.\"*************************************************************************** +.\" Copyright 2018,2020 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_terminfo.3x,v 1.67 2020/11/07 23:49:07 tom Exp $ .TH curs_terminfo 3X "" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. .ds n 5 +.na +.hy 0 .SH NAME -\fBsetupterm\fR, \fBsetterm\fR, -\fBset_curterm\fR, \fBdel_curterm\fR, \fBrestartterm\fR, \fBtparm\fR, -\fBtputs\fR, \fBputp\fR, \fBvidputs\fR, \fBvidattr\fR, \fBmvcur\fR, -\fBtigetflag\fR, \fBtigetnum\fR, \fBtigetstr\fR - \fBcurses\fR -interfaces to terminfo database +\fBdel_curterm\fR, +\fBmvcur\fR, +\fBputp\fR, +\fBrestartterm\fR, +\fBset_curterm\fR, +\fBsetterm\fR, +\fBsetupterm\fR, +\fBtigetflag\fR, +\fBtigetnum\fR, +\fBtigetstr\fR, +\fBtiparm\fR, +\fBtparm\fR, +\fBtputs\fR, +\fBvid_attr\fR, +\fBvid_puts\fR, +\fBvidattr\fR, +\fBvidputs\fR \- \fBcurses\fR interfaces to terminfo database +.ad +.hy .SH SYNOPSIS -\fB#include \fR -.br +.nf \fB#include \fR - -\fBint setupterm(const char *term, int fildes, int *errret);\fR -.br -\fBint setterm(const char *term);\fR -.br -\fBTERMINAL *set_curterm(TERMINAL *nterm);\fR +.sp +\fBTERMINAL *cur_term;\fR +.sp +\fBconst char * const boolnames[];\fP +\fBconst char * const boolcodes[];\fP +\fBconst char * const boolfnames[];\fP +\fBconst char * const numnames[];\fP +\fBconst char * const numcodes[];\fP +\fBconst char * const numfnames[];\fP +\fBconst char * const strnames[];\fP +\fBconst char * const strcodes[];\fP +\fBconst char * const strfnames[];\fP +.sp +\fBint setupterm(const char *\fR\fIterm\fR\fB, int \fR\fIfiledes\fR\fB, int *\fR\fIerrret\fR\fB);\fR .br -\fBint del_curterm(TERMINAL *oterm);\fR +\fBint setterm(const char *\fR\fIterm\fR\fB);\fR .br -\fBint restartterm(const char *term, int fildes, int *errret);\fR +\fBTERMINAL *set_curterm(TERMINAL *\fR\fInterm\fR\fB);\fR .br -\fBchar *tparm(const char *str, ...);\fR +\fBint del_curterm(TERMINAL *\fR\fIoterm\fR\fB);\fR .br -\fBchar *tparam(const char *str, char *buffer, int size, ...);\fR +\fBint restartterm(const char *\fR\fIterm\fR\fB, int \fR\fIfiledes\fR\fB, int *\fR\fIerrret\fR\fB);\fR +.sp +\fBchar *tparm(const char *\fR\fIstr\fR\fB, ...);\fR .br -\fBint tputs(const char *str, int affcnt, int (*putc)(int));\fR +\fBint tputs(const char *\fR\fIstr\fR\fB, int \fR\fIaffcnt\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR .br -\fBint putp(const char *str);\fR +\fBint putp(const char *\fR\fIstr\fR\fB);\fR +.sp +\fBint vidputs(chtype \fR\fIattrs\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR .br -\fBint vidputs(chtype attrs, int (*putc)(char));\fR +\fBint vidattr(chtype \fR\fIattrs\fR\fB);\fR .br -\fBint vidattr(chtype attrs);\fR +\fBint vid_puts(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR .br -\fBint mvcur(int oldrow, int oldcol, int newrow, int newcol);\fR +\fBint vid_attr(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB);\fR +.sp +\fBint mvcur(int \fR\fIoldrow\fR\fB, int \fR\fIoldcol\fR\fB, int \fR\fInewrow\fR, int \fR\fInewcol\fR\fB);\fR +.sp +\fBint tigetflag(const char *\fR\fIcapname\fR\fB);\fR .br -\fBint tigetflag(const char *capname);\fR +\fBint tigetnum(const char *\fR\fIcapname\fR\fB);\fR .br -\fBint tigetnum(const char *capname);\fR -.br -\fBchar *tigetstr(const char *capname);\fR +\fBchar *tigetstr(const char *\fR\fIcapname\fR\fB);\fR +.sp +\fBchar *tiparm(const char *\fR\fIstr\fR\fB, ...);\fR .br +.fi .SH DESCRIPTION These low-level routines must be called by programs that have to deal directly with the \fBterminfo\fR database to handle certain terminal -capabilities, such as programming function keys. For all other +capabilities, such as programming function keys. +For all other functionality, \fBcurses\fR routines are more suitable and their use is recommended. - -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)]. The \fBterminfo\fR variables +.PP +None of these functions use (or are aware of) multibyte character strings +such as UTF-8: +.bP +capability names use the POSIX portable character set +.bP +capability string values have no associated encoding; +they are strings of 8-bit characters. +.SS Initialization +.PP +Initially, \fBsetupterm\fR should be called. +The high-level curses functions \fBinitscr\fR and +\fBnewterm\fR call \fBsetupterm\fP to initialize the +low-level set of terminal-dependent variables +[listed in \fBterminfo\fR(\*n)]. +.PP +Applications can use 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: If \fBuse_env(FALSE)\fR has been called, values for +follows: +.bP +If \fBuse_env(FALSE)\fR has been called, values for \fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used. +.bP Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR -exist, their values are used. If these environment variables do not +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 +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. - -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 - -\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. - +.PP +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 \fBreset_shell_mode\fR to restore the +tty modes before exiting [see \fBcurs_kernel\fR(3X)]. +.PP +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 -output virtualization structures used by \fBcurses\fR. The terminal -type is the character string \fIterm\fR; if \fIterm\fR is null, the -environment variable \fBTERM\fR is used. All output is to file -descriptor \fBfildes\fR which is initialized for output. If -\fIerrret\fR is not null, then \fBsetupterm\fR returns \fBOK\fR or +output virtualization structures used by \fBcurses\fR. +These are its parameters: +.RS 3 +.TP 5 +\fIterm\fP +is the terminal type, a character string. +If \fIterm\fR is null, the environment variable \fBTERM\fR is used. +.TP 5 +\fIfiledes\fP +is the file descriptor used for all output. +.TP 5 +\fIerrret\fP +points to an optional location where an error status can be returned to +the caller. +If \fIerrret\fR is not null, +then \fBsetupterm\fR returns \fBOK\fR or \fBERR\fR and stores a status value in the integer pointed to by -\fIerrret\fR. A status of \fB1\fR in \fIerrret\fR is normal, \fB0\fR -means that the terminal could not be found, and \fB-1\fR means that -the \fBterminfo\fR database could not be found. If \fIerrret\fR is +\fIerrret\fR. +A return value of \fBOK\fR combined with status of \fB1\fR in \fIerrret\fR +is normal. +.IP +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. +.IP +\fBsetupterm\fP determines if the entry is a hardcopy type by +checking the \fBhc\fP (\fBhardcopy\fP) capability. +.TP 5 +.B 0 +means that the terminal could not be found, +or that it is a generic type, +having too little information for curses applications to run. +.IP +\fBsetupterm\fP determines if the entry is a generic type by +checking the \fBgn\fP (\fBgeneric\fP) capability. +.TP 5 +.B \-1 +means that the \fBterminfo\fR database could not be found. +.RE +.IP +If \fIerrret\fR is null, \fBsetupterm\fR prints an error message upon finding an error -and exits. Thus, the simplest call is: - +and exits. +Thus, the simplest call is: +.sp \fBsetupterm((char *)0, 1, (int *)0);\fR, - +.sp which uses all the defaults and sends the output to \fBstdout\fR. - -The \fBsetterm\fR routine is being replaced by \fBsetupterm\fR. The call: - +.RE +.PP +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. - -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 +\fIoterm\fR and makes it available for further use. +If \fIoterm\fR is the same as \fBcur_term\fR, references to any of the \fBterminfo\fR boolean, numeric, and string variables thereafter may refer to invalid 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, does a setupterm, 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 with the parameters applied. - -The \fBtparam\fR routine is included for compatibility with the GNU termcap -implementation. It works like \fBtparm\fR but you specify a buffer and buffer -size to be filled with the expanded string. - +Application developers should keep in mind these quirks of the interface: +.bP +Although \fBtparm\fP's actual parameters may be integers or strings, +the prototype expects \fBlong\fP (integer) values. +.bP +Aside from the \fBset_attributes\fP (\fBsgr\fP) capability, +most terminal capabilities require no more than one or two parameters. +.PP +\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 -variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or -\fBtgoto\fR. \fIaffcnt\fR is the number of lines affected, or 1 if -not applicable. \fIputc\fR is a \fBputchar\fR-like routine to which +\fIstr\fR and outputs it: +.bP +The \fIstr\fR parameter must be a terminfo string +variable or the return value from +\fBtparm\fR, \fBtiparm\fP, \fBtgetstr\fR, or \fBtgoto\fR. +.IP +The \fBtgetstr\fP and \fBtgoto\fP functions are part of the \fItermcap\fP +interface, +which happens to share this function name with the \fIterminfo\fP interface. +.bP +\fIaffcnt\fR is the number of lines affected, or 1 if +not applicable. +.bP +\fIputc\fR is a \fBputchar\fR-like routine to which the characters are passed, one at a time. - +.PP The \fBputp\fR routine calls \fBtputs(\fR\fIstr\fR\fB, 1, putchar)\fR. -Note that the output of \fBputp\fR always goes to \fBstdout\fR, not to -the \fIfildes\fR specified in \fBsetupterm\fR. - +The output of \fBputp\fR always goes to \fBstdout\fR, rather than +the \fIfiledes\fR specified in \fBsetupterm\fR. +.PP The \fBvidputs\fR routine displays the string on the terminal in the video attribute mode \fIattrs\fR, which is any combination of the -attributes listed in \fBcurses\fR(3X). The characters are passed to +attributes listed in \fBcurses\fR(3X). +The characters are passed to the \fBputchar\fR-like routine \fIputc\fR. - +.PP The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except that it outputs through \fBputchar\fR. - -The \fBmvcur\fR routine provides low-level cursor motion. It takes +.PP +The \fBvid_attr\fR and \fBvid_puts\fR routines correspond +to vidattr and vidputs, respectively. +They use a set of arguments for representing the video attributes plus color, +i.e., +.bP +\fIattrs\fP of type \fBattr_t\fP for the attributes and +.bP +\fIpair\fP of type \fBshort\fP for the color-pair number. +.PP +The \fBvid_attr\fR and \fBvid_puts\fR routines +are designed to use the attribute constants with the \fIWA_\fR prefix. +.PP +X/Open Curses reserves the \fIopts\fP argument for future use, +saying that applications must provide a null pointer for that argument. +As an extension, +this implementation allows \fIopts\fP to be used as a pointer to \fBint\fP, +which overrides the \fIpair\fP (\fBshort\fP) 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. - -The \fBtigetflag\fR routine returns the value \fB-1\fR if -\fIcapname\fR is not a boolean capability. - -The \fBtigetnum\fR routine returns the value \fB-2\fR if -\fIcapname\fR is not a numeric capability. - -The \fBtigetstr\fR routine returns the value \fB(char *)-1\fR -if \fIcapname\fR is not a string capability. - The \fIcapname\fR for each capability is given in the table column entitled \fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n). - -\fBchar *boolnames\fR, \fB*boolcodes\fR, \fB*boolfnames\fR - -\fBchar *numnames\fR, \fB*numcodes\fR, \fB*numfnames\fR - -\fBchar *strnames\fR, \fB*strcodes\fR, \fB*strfnames\fR - -These null-terminated arrays contain the \fIcapnames\fR, the -\fBtermcap\fR codes, and the full C names, for each of the -\fBterminfo\fR variables. +.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 +.PP +These null-terminated arrays contain +.bP +the short terminfo names (\*(``codes\*(''), +.bP +the \fBtermcap\fR names (\*(``names\*(''), and +.bP +the long terminfo names (\*(``fnames\*('') +.PP +for each of the predefined \fBterminfo\fR variables: +.sp +.RS +\fBconst char *boolnames[]\fR, \fB*boolcodes[]\fR, \fB*boolfnames[]\fR +.br +\fBconst char *numnames[]\fR, \fB*numcodes[]\fR, \fB*numfnames[]\fR +.br +\fBconst char *strnames[]\fR, \fB*strcodes[]\fR, \fB*strfnames[]\fR +.RE .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 -completion, unless otherwise noted in the preceding routine descriptions. - +(SVr4 only specifies \*(``an integer value other than \fBERR\fR\*('') +upon successful completion, +unless otherwise noted in the preceding routine descriptions. +.PP Routines that return pointers always return \fBNULL\fR on error. -.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. - -Note that \fBvidattr\fR and \fBvidputs\fR may be macros. +.PP +X/Open defines no error conditions. +In this implementation +.RS 3 +.TP 5 +\fBdel_curterm\fP +returns an error +if its terminal parameter is null. +.TP 5 +\fBputp\fP +calls \fBtputs\fP, returning the same error-codes. +.TP 5 +\fBrestartterm\fP +returns an error +if the associated call to \fBsetupterm\fP returns an error. +.TP 5 +\fBsetupterm\fP +returns an error +if it cannot allocate enough memory, or +create the initial windows (stdscr, curscr, newscr). +Other error conditions are documented above. +.TP 5 +\fBtputs\fP +returns an error if the string parameter is null. +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 HISTORY +.PP +SVr2 introduced the terminfo feature. +Its programming manual mentioned these low-level functions: +.TS +l l +_ _ +l l. +\fBFunction\fR \fBDescription\fR +fixterm restore tty to \*(``in curses\*('' state +gettmode establish current tty modes +mvcur low level cursor motion +putp T{ +utility function that uses \fBtputs\fP to send characters via \fBputchar\fP. +T} +resetterm set tty modes to \*(``out of curses\*('' state +resetty reset tty flags to stored value +saveterm save current modes as \*(``in curses\*('' state +savetty store current tty flags +setterm establish terminal with given type +setupterm establish terminal with given type +tparm instantiate a string expression with parameters +tputs apply padding information to a string +vidattr like \fBvidputs\fP, but outputs through \fBputchar\fP +vidputs T{ +output a string to put terminal in a specified video attribute mode +T} +.TE +.PP +The programming manual also mentioned +functions provided for termcap compatibility +(commenting that they \*(``may go away at a later date\*(''): +.TS +l l +_ _ +l l. +\fBFunction\fR \fBDescription\fR +tgetent look up termcap entry for given \fIname\fP +tgetflag get boolean entry for given \fIid\fP +tgetnum get numeric entry for given \fIid\fP +tgetstr get string entry for given \fIid\fP +tgoto apply parameters to given capability +tputs T{ +apply padding to capability, calling a function to put characters +T} +.TE +.PP +Early terminfo programs obtained capability values from the +\fBTERMINAL\fP structure initialized by \fBsetupterm\fR. +.PP +SVr3 extended terminfo by adding functions to retrieve capability values +(like the termcap interface), +and reusing tgoto and tputs: +.TS +l l +_ _ +l l. +\fBFunction\fR \fBDescription\fR +tigetflag get boolean entry for given \fIid\fP +tigetnum get numeric entry for given \fIid\fP +tigetstr get string entry for given \fIid\fP +.TE +.PP +SVr3 also replaced several of the SVr2 terminfo functions +which had no counterpart in the termcap interface, +documenting them as obsolete: +.TS +l l +_ _ +l l. +\fBFunction\fR \fBReplaced by\fP +crmode cbreak +fixterm reset_prog_mode +gettmode N/A +nocrmode nocbreak +resetterm reset_shell_mode +saveterm def_prog_mode +setterm setupterm +.TE +.PP +SVr3 kept the \fBmvcur\fP, \fBvidattr\fP and \fBvidputs\fP functions, +along with \fBputp\fP, \fBtparm\fP and \fBtputs\fP. +The latter were needed to support padding, +and handling functions such as \fBvidattr\fP +(which used more than the two parameters supported by \fBtgoto\fP). +.PP +SVr3 introduced the functions for switching between terminal +descriptions, e.g., \fBset_curterm\fP. +The various global variables such as \fBboolnames\fP were mentioned +in the programming manual at this point. +.PP +SVr4 added the \fBvid_attr\fP and \fBvid_puts\fP functions. +.PP +There are other low-level functions declared in the curses header files +on Unix systems, +but none were documented. +The functions marked \*(``obsolete\*('' remained in use +by the Unix \fBvi\fP editor. .SH PORTABILITY -The function \fBsetterm\fR is not described in the XSI Curses standard and must -be considered non-portable. All other functions are as described in the XSI -curses standard. - +.SS Legacy functions +.PP +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. +.SS Legacy data +.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. +.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 here. +.SS Output buffering +.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, +and would write to the corresponding stream. +In addition to the limitation that the terminal was left in block-buffered +mode on exit (like System V curses), +it was problematic because \fBncurses\fP +did not allow a reliable way to cleanup on receiving SIGTSTP. +.PP +The current version (ncurses6) +uses output buffers managed directly by \fBncurses\fP. +Some of the low-level functions described in this manual page write +to the standard output. +They are not signal-safe. +The high-level functions in \fBncurses\fP use +alternate versions of these functions +using the more reliable buffering scheme. +.SS Function prototypes +.PP +The X/Open Curses prototypes are based on the SVr4 curses header declarations, +which were defined at the same time the C language was first standardized in +the late 1980s. +.bP +X/Open Curses uses \fBconst\fP less effectively than a later design might, +in some cases applying it needlessly to values are already constant, +and in most cases overlooking parameters which normally would use \fBconst\fP. +Using constant parameters for functions which do not use \fBconst\fP +may prevent the program from compiling. +On the other hand, \fIwritable strings\fP are an obsolescent feature. +.IP +As an extension, this implementation can be configured to change the +function prototypes to use the \fBconst\fP keyword. +The ncurses ABI 6 enables this feature by default. +.bP +X/Open Curses prototypes \fBtparm\fR with a fixed number of parameters, +rather than a variable argument list. +.IP +This implementation uses a variable argument list, but can be +configured to use the fixed-parameter list. +Portable applications should provide 9 parameters after the format; +zeroes are fine for this purpose. +.IP +In response to review comments by Thomas E. Dickey, +X/Open Curses Issue 7 proposed the \fBtiparm\fP function in mid-2009. +.SS Special TERM treatment +.PP +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\*(''. +.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. +.SS Other portability issues +.PP In System V Release 4, \fBset_curterm\fR has an \fBint\fR return type and -returns \fBOK\fR or \fBERR\fR. We have chosen to implement the XSI Curses +returns \fBOK\fR or \fBERR\fR. We have chosen to implement the X/Open Curses semantics. - +.PP In System V Release 4, the third argument of \fBtputs\fR has the type \fBint (*putc)(char)\fR. - -The XSI Curses standard prototypes \fBtparm\fR with a fixed number of parameters, -rather than a variable argument list. +.PP +At least one implementation of X/Open Curses (Solaris) returns a value +other than \fBOK\fP/\fBERR\fP from \fBtputs\fP. +That returns the length of the string, and does no error-checking. +.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 +the window before resuming normal curses calls. +Both \fBncurses\fP and System V Release 4 curses implement \fBmvcur\fR using +the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR. +So though it is documented as a terminfo function, +\fBmvcur\fR is really a curses function which is not well specified. +.PP +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. .SH SEE ALSO -\fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_termcap\fR(3X), -\fBputc\fR(3S), \fBterminfo\fR(\*n) -.\"# -.\"# The following sets edit modes for GNU EMACS -.\"# Local Variables: -.\"# mode:nroff -.\"# fill-column:79 -.\"# End: +\fBcurses\fR(3X), +\fBcurs_initscr\fR(3X), +\fBcurs_kernel\fR(3X), +\fBcurs_termcap\fR(3X), +\fBcurs_variables\fR(3X), +\fBterm_variables\fR(3X), +\fBputc\fR(3), +\fBterminfo\fR(\*n)