-.\" $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.65 2020/09/29 20:07:42 Rueben.Thomas 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
+.nf
\fB#include <curses.h>\fR
.br
\fB#include <term.h>\fR
-
-\fBint setupterm(const char *term, int fildes, int *errret);\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 setterm(const char *term);\fR
+\fBint setterm(const char *\fR\fIterm\fR\fB);\fR
.br
-\fBTERMINAL *set_curterm(TERMINAL *nterm);\fR
+\fBTERMINAL *set_curterm(TERMINAL *\fR\fInterm\fR\fB);\fR
.br
-\fBint del_curterm(TERMINAL *oterm);\fR
+\fBint del_curterm(TERMINAL *\fR\fIoterm\fR\fB);\fR
.br
-\fBint restartterm(const char *term, int fildes, int *errret);\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
-\fBchar *tparm(const char *str, ...);\fR
+\fBint tputs(const char *\fR\fIstr\fR\fB, int \fR\fIaffcnt\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
.br
-\fBchar *tparam(const char *str, char *buffer, int size, ...);\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 tputs(const char *str, int affcnt, int (*putc)(int));\fR
+\fBint vidattr(chtype \fR\fIattrs\fR\fB);\fR
.br
-\fBint putp(const char *str);\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 vidputs(chtype attrs, int (*putc)(char));\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 vidattr(chtype attrs);\fR
+\fBint tigetnum(const char *\fR\fIcapname\fR\fB);\fR
.br
-\fBint mvcur(int oldrow, int oldcol, int newrow, int newcol);\fR
-.br
-\fBint tigetflag(const char *capname);\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
+.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<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
-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)
projects / ncurses.git / blobdiff