| .\"*************************************************************************** |
| .\" Copyright 2018-2022,2022 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.82 2022/06/04 22:47:05 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 |
| \fBdel_curterm\fP, |
| \fBmvcur\fP, |
| \fBputp\fP, |
| \fBrestartterm\fP, |
| \fBset_curterm\fP, |
| \fBsetupterm\fP, |
| \fBtigetflag\fP, |
| \fBtigetnum\fP, |
| \fBtigetstr\fP, |
| \fBtiparm\fP, |
| \fBtparm\fP, |
| \fBtputs\fP, |
| \fBvid_attr\fP, |
| \fBvid_puts\fP, |
| \fBvidattr\fP, |
| \fBvidputs\fP \- \fBcurses\fP interfaces to terminfo database |
| .ad |
| .hy |
| .SH SYNOPSIS |
| .nf |
| \fB#include <curses.h>\fP |
| \fB#include <term.h>\fP |
| .sp |
| \fBTERMINAL *cur_term;\fP |
| .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 *\fIterm\fB, int \fIfiledes\fB, int *\fIerrret\fB);\fR |
| .br |
| \fBTERMINAL *set_curterm(TERMINAL *\fInterm\fB);\fR |
| .br |
| \fBint del_curterm(TERMINAL *\fIoterm\fB);\fR |
| .br |
| \fBint restartterm(const char *\fIterm\fB, int \fIfiledes\fB, int *\fIerrret\fB);\fR |
| .sp |
| \fBchar *tparm(const char *\fIstr\fB, ...);\fR |
| .br |
| \fBint tputs(const char *\fIstr\fB, int \fIaffcnt\fB, int (*\fIputc\fB)(int));\fR |
| .br |
| \fBint putp(const char *\fIstr\fB);\fR |
| .sp |
| \fBint vidputs(chtype \fIattrs\fB, int (*\fIputc\fB)(int));\fR |
| .br |
| \fBint vidattr(chtype \fIattrs\fB);\fR |
| .br |
| \fBint vid_puts(attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB, int (*\fIputc\fB)(int));\fR |
| .br |
| \fBint vid_attr(attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB);\fR |
| .sp |
| \fBint mvcur(int \fIoldrow\fB, int \fIoldcol\fB, int \fInewrow\fR, int \fInewcol\fB);\fR |
| .sp |
| \fBint tigetflag(const char *\fIcapname\fB);\fR |
| .br |
| \fBint tigetnum(const char *\fIcapname\fB);\fR |
| .br |
| \fBchar *tigetstr(const char *\fIcapname\fB);\fR |
| .sp |
| \fBchar *tiparm(const char *\fIstr\fB, ...);\fR |
| .br |
| .fi |
| .SH DESCRIPTION |
| These low-level routines must be called by programs that have to deal |
| directly with the \fBterminfo\fP database to handle certain terminal |
| capabilities, such as programming function keys. |
| For all other |
| functionality, \fBcurses\fP routines are more suitable and their use is |
| recommended. |
| .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\fP should be called. |
| The high-level curses functions \fBinitscr\fP and |
| \fBnewterm\fP call \fBsetupterm\fP to initialize the |
| low-level set of terminal-dependent variables |
| [listed in \fBterminfo\fP(\*n)]. |
| .PP |
| Applications can use the |
| terminal capabilities either directly (via header definitions), |
| or by special functions. |
| The header files \fBcurses.h\fP and \fBterm.h\fP should be included (in this |
| order) to get the definitions for these strings, numbers, and flags. |
| .PP |
| The \fBterminfo\fP variables |
| \fBlines\fP and \fBcolumns\fP are initialized by \fBsetupterm\fP as |
| follows: |
| .bP |
| If \fBuse_env(FALSE)\fP has been called, values for |
| \fBlines\fP and \fBcolumns\fP specified in \fBterminfo\fP are used. |
| .bP |
| Otherwise, if the environment variables \fBLINES\fP and \fBCOLUMNS\fP |
| 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\fP and \fBcolumns\fP specified in the |
| \fBterminfo\fP database are used. |
| .PP |
| Parameterized strings should be passed through \fBtparm\fP to instantiate them. |
| All \fBterminfo\fP strings |
| (including the output of \fBtparm\fP) |
| should be printed |
| with \fBtputs\fP or \fBputp\fP. |
| Call \fBreset_shell_mode\fP to restore the |
| tty modes before exiting [see \fBcurs_kernel\fP(3X)]. |
| .PP |
| Programs which use |
| cursor addressing should |
| .bP |
| output \fBenter_ca_mode\fP upon startup and |
| .bP |
| output \fBexit_ca_mode\fP before exiting. |
| .PP |
| Programs which execute shell subprocesses should |
| .bP |
| call \fBreset_shell_mode\fP and |
| output \fBexit_ca_mode\fP before the shell |
| is called and |
| .bP |
| output \fBenter_ca_mode\fP and |
| call \fBreset_prog_mode\fP after returning from the shell. |
| .PP |
| The \fBsetupterm\fP routine reads in the \fBterminfo\fP database, |
| initializing the \fBterminfo\fP structures, but does not set up the |
| output virtualization structures used by \fBcurses\fP. |
| These are its parameters: |
| .RS 3 |
| .TP 5 |
| \fIterm\fP |
| is the terminal type, a character string. |
| If \fIterm\fP is null, the environment variable \fBTERM\fP 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\fP is not null, |
| then \fBsetupterm\fP returns \fBOK\fP or |
| \fBERR\fP and stores a status value in the integer pointed to by |
| \fIerrret\fP. |
| A return value of \fBOK\fP combined with status of \fB1\fP in \fIerrret\fP |
| is normal. |
| .IP |
| If \fBERR\fP is returned, examine \fIerrret\fP: |
| .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\fP database could not be found. |
| .RE |
| .IP |
| If \fIerrret\fP is |
| null, \fBsetupterm\fP prints an error message upon finding an error |
| and exits. |
| Thus, the simplest call is: |
| .sp |
| \fBsetupterm((char *)0, 1, (int *)0);\fP, |
| .sp |
| which uses all the defaults and sends the output to \fBstdout\fP. |
| .RE |
| .\" *************************************************************************** |
| .SS The Terminal State |
| .PP |
| The \fBsetupterm\fP 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\fP routine sets \fBcur_term\fP to |
| \fInterm\fP, and makes all of the \fBterminfo\fP boolean, numeric, and |
| string variables use the values from \fInterm\fP. |
| It returns the old value of \fBcur_term\fP. |
| .PP |
| The \fBdel_curterm\fP routine frees the space pointed to by |
| \fIoterm\fP and makes it available for further use. |
| If \fIoterm\fP is |
| the same as \fBcur_term\fP, references to any of the \fBterminfo\fP |
| boolean, numeric, and string variables thereafter may refer to invalid |
| memory locations until another \fBsetupterm\fP has been called. |
| .PP |
| The \fBrestartterm\fP routine is similar to \fBsetupterm\fP and \fBinitscr\fP, |
| except that it is called after restoring memory to a previous state (for |
| 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\fP routine instantiates the string \fIstr\fP with |
| parameters \fIpi\fP. A pointer is returned to the result of \fIstr\fP |
| with the parameters applied. |
| 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. |
| .bP |
| Padding information is ignored by \fBtparm\fP; |
| it is interpreted by \fBtputs\fP. |
| .bP |
| The capability string is null-terminated. |
| Use \*(``\\200\*('' where an ASCII NUL is needed in the output. |
| .PP |
| \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\fP routine applies padding information |
| (i.e., by interpreting marker embedded in the terminfo capability |
| such as \*(``$<5>\*('' as 5 milliseconds) |
| to the string |
| \fIstr\fP and outputs it: |
| .bP |
| The \fIstr\fP parameter must be a terminfo string |
| variable or the return value from |
| \fBtparm\fP, \fBtiparm\fP, \fBtgetstr\fP, or \fBtgoto\fP. |
| .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\fP is the number of lines affected, or 1 if |
| not applicable. |
| .bP |
| \fIputc\fP is a \fBputchar\fP-like routine to which |
| the characters are passed, one at a time. |
| .PP |
| The \fBputp\fR routine calls \fBtputs(\fIstr\fB, 1, putchar)\fR. |
| The output of \fBputp\fP always goes to \fBstdout\fP, rather than |
| the \fIfiledes\fP specified in \fBsetupterm\fP. |
| .PP |
| The \fBvidputs\fP routine displays the string on the terminal in the |
| video attribute mode \fIattrs\fP, which is any combination of the |
| attributes listed in \fBcurses\fP(3X). |
| The characters are passed to |
| the \fBputchar\fP-like routine \fIputc\fP. |
| .PP |
| The \fBvidattr\fP routine is like the \fBvidputs\fP routine, except |
| that it outputs through \fBputchar\fP. |
| .PP |
| The \fBvid_attr\fP and \fBvid_puts\fP 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\fP and \fBvid_puts\fP routines |
| are designed to use the attribute constants with the \fBWA_\fP 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\fP routine provides low-level cursor motion. |
| It takes effect immediately (rather than at the next refresh). |
| .PP |
| While \fBputp\fP and \fBmvcur\fP are low-level functions which |
| do not use the high-level curses state, |
| they are declared in \fB<curses.h>\fP because SystemV did this |
| (see \fIHISTORY\fP). |
| .\" *************************************************************************** |
| .SS Terminal Capability Functions |
| .PP |
| The \fBtigetflag\fP, \fBtigetnum\fP and \fBtigetstr\fP routines return |
| the value of the capability corresponding to the \fBterminfo\fP |
| \fIcapname\fP passed to them, such as \fBxenl\fP. |
| The \fIcapname\fP for each capability is given in the table column entitled |
| \fIcapname\fP code in the capabilities section of \fBterminfo\fP(\*n). |
| .PP |
| These routines return special values to denote errors. |
| .PP |
| The \fBtigetflag\fP routine returns |
| .TP |
| \fB\-1\fP |
| if \fIcapname\fP is not a boolean capability, |
| or |
| .TP |
| \fB0\fP |
| if it is canceled or absent from the terminal description. |
| .PP |
| The \fBtigetnum\fP routine returns |
| .TP |
| \fB\-2\fP |
| if \fIcapname\fP is not a numeric capability, or |
| .TP |
| \fB\-1\fP |
| if it is canceled or absent from the terminal description. |
| .PP |
| The \fBtigetstr\fP routine returns |
| .TP |
| \fB(char *)\-1\fP |
| if \fIcapname\fP is not a string capability, |
| or |
| .TP |
| \fB0\fP |
| 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\fP names (\*(``names\*(''), and |
| .bP |
| the long terminfo names (\*(``fnames\*('') |
| .PP |
| for each of the predefined \fBterminfo\fP variables: |
| .sp |
| .RS |
| \fBconst char *boolnames[]\fP, \fB*boolcodes[]\fP, \fB*boolfnames[]\fP |
| .br |
| \fBconst char *numnames[]\fP, \fB*numcodes[]\fP, \fB*numfnames[]\fP |
| .br |
| \fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP |
| .RE |
| .\" *************************************************************************** |
| .SS Releasing Memory |
| Each successful call to \fBsetupterm\fP allocates memory to hold the terminal |
| description. |
| As a side-effect, it sets \fBcur_term\fP to point to this memory. |
| If an application calls |
| .sp |
| \fBdel_curterm(cur_term);\fP |
| .sp |
| the memory will be freed. |
| .PP |
| The formatting functions \fBtparm\fP and \fBtiparm\fP extend the storage |
| allocated by \fBsetupterm\fP: |
| .bP |
| the \*(``static\*('' terminfo variables [a-z]. |
| Before ncurses 6.3, those were shared by all screens. |
| With ncurses 6.3, those are allocated per screen. |
| See \fBterminfo\fP(\*n) for details. |
| .bP |
| to improve performance, ncurses 6.3 caches the result of analyzing terminfo |
| strings for their parameter types. |
| That is stored as a binary tree referenced from the \fBTERMINAL\fP structure. |
| .PP |
| The higher-level \fBinitscr\fP and \fBnewterm\fP functions use \fBsetupterm\fP. |
| Normally they do not free this memory, but it is possible to do that using |
| the \fBdelscreen\fP(3X) function. |
| .\" *************************************************************************** |
| .SH RETURN VALUE |
| Routines that return an integer return \fBERR\fP upon failure and \fBOK\fP |
| (SVr4 only specifies \*(``an integer value other than \fBERR\fP\*('') |
| upon successful completion, |
| unless otherwise noted in the preceding routine descriptions. |
| .PP |
| Routines that return pointers always return \fBNULL\fP on error. |
| .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 |
| .\" *************************************************************************** |
| .SS Compatibility macros |
| This implementation provides a few macros for compatibility with systems |
| before SVr4 (see \fIHISTORY\fP). |
| Those include |
| \fBcrmode\fP, |
| \fBfixterm\fP, |
| \fBgettmode\fP, |
| \fBnocrmode\fP, |
| \fBresetterm\fP, |
| \fBsaveterm\fP, and |
| \fBsetterm\fP. |
| .PP |
| In SVr4, those are found in \fB<curses.h>\fP, |
| but except for \fBsetterm\fP, are likewise macros. |
| The one function, \fBsetterm\fP, is mentioned in the manual page. |
| The manual page notes that the \fBsetterm\fP routine |
| was replaced by \fBsetupterm\fP, stating that the call: |
| .sp |
| \fBsetupterm(\fIterm\fB, 1, (int *)0)\fR |
| .sp |
| provides the same functionality as \fBsetterm(\fIterm\fB)\fR, |
| and is not recommended for new programs. |
| This implementation provides each of those symbols |
| as macros for BSD compatibility, |
| .\" *************************************************************************** |
| .SH HISTORY |
| .PP |
| SVr2 introduced the terminfo feature. |
| Its programming manual mentioned these low-level functions: |
| .TS |
| l l |
| _ _ |
| l l. |
| \fBFunction\fP \fBDescription\fP |
| 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\fP \fBDescription\fP |
| 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\fP. |
| .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\fP \fBDescription\fP |
| 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\fP \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. |
| Some of that was incremental improvements to the SVr2 library: |
| .bP |
| The \fBTERMINAL\fP type definition was introduced in SVr3.01, |
| for the \fBterm\fP structure provided in SVr2. |
| .bP |
| The various global variables such as \fBboolnames\fP were mentioned |
| in the programming manual at this point, |
| though the variables were provided in SVr2. |
| .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(1) editor. |
| .SH PORTABILITY |
| .SS Legacy functions |
| .PP |
| X/Open notes that \fBvidattr\fP and \fBvidputs\fP may be macros. |
| .PP |
| The function \fBsetterm\fP 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\fP 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\fP has an \fBint\fP return type and |
| returns \fBOK\fP or \fBERR\fP. We have chosen to implement the X/Open Curses |
| semantics. |
| .PP |
| In System V Release 4, the third argument of \fBtputs\fP has the type |
| \fBint (*putc)(char)\fP. |
| .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\fP, 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\fP using |
| the SCREEN data allocated in either \fBinitscr\fP or \fBnewterm\fP. |
| So though it is documented as a terminfo function, |
| \fBmvcur\fP 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\fP(3X), |
| \fBcurs_initscr\fP(3X), |
| \fBcurs_kernel\fP(3X), |
| \fBcurs_memleaks\fP(3X), |
| \fBcurs_termcap\fP(3X), |
| \fBcurs_variables\fP(3X), |
| \fBterm_variables\fP(3X), |
| \fBputc\fP(3), |
| \fBterminfo\fP(\*n) |