+'\" t
.\"***************************************************************************
-.\" Copyright 2018-2020,2021 Thomas E. Dickey *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_terminfo.3x,v 1.72 2021/01/02 23:50:04 tom Exp $
-.TH curs_terminfo 3X ""
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: curs_terminfo.3x,v 1.136 2024/04/14 00:14:40 tom Exp $
+.TH curs_terminfo 3X 2024-04-13 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
..
-.ds n 5
-.na
-.hy 0
+.
.SH NAME
-\fBdel_curterm\fR,
-\fBmvcur\fR,
-\fBputp\fR,
-\fBrestartterm\fR,
-\fBset_curterm\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
+\fB\%del_curterm\fP,
+\fB\%mvcur\fP,
+\fB\%putp\fP,
+\fB\%restartterm\fP,
+\fB\%set_curterm\fP,
+\fB\%setupterm\fP,
+\fB\%tigetflag\fP,
+\fB\%tigetnum\fP,
+\fB\%tigetstr\fP,
+\fB\%tiparm\fP,
+\fB\%tiparm_s\fP,
+\fB\%tiscan_s\fP,
+\fB\%tparm\fP,
+\fB\%tputs\fP,
+\fB\%vid_attr\fP,
+\fB\%vid_puts\fP,
+\fB\%vidattr\fP,
+\fB\%vidputs\fP \-
+\fIcurses\fR interfaces to \fI\%term\%info\fR database
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fR
-\fB#include <term.h>\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
-\fBTERMINAL *set_curterm(TERMINAL *\fR\fInterm\fR\fB);\fR
-.br
-\fBint del_curterm(TERMINAL *\fR\fIoterm\fR\fB);\fR
-.br
-\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 *\fR\fIstr\fR\fB, int \fR\fIaffcnt\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
-.br
-\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 vidattr(chtype \fR\fIattrs\fR\fB);\fR
-.br
-\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 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 tigetnum(const char *\fR\fIcapname\fR\fB);\fR
-.br
-\fBchar *tigetstr(const char *\fR\fIcapname\fR\fB);\fR
-.sp
-\fBchar *tiparm(const char *\fR\fIstr\fR\fB, ...);\fR
-.br
+\fB#include <curses.h>
+\fB#include <term.h>
+.PP
+\fBTERMINAL *cur_term;
+.PP
+\fBconst char * const boolnames[];
+\fBconst char * const boolcodes[];
+\fBconst char * const boolfnames[];
+\fBconst char * const numnames[];
+\fBconst char * const numcodes[];
+\fBconst char * const numfnames[];
+\fBconst char * const strnames[];
+\fBconst char * const strcodes[];
+\fBconst char * const strfnames[];
+.PP
+\fBint setupterm(const char *\fIterm\fP, int \fIfiledes\fP, int *\fIerrret\fP);
+\fBTERMINAL *set_curterm(TERMINAL *\fInterm\fP);
+\fBint del_curterm(TERMINAL *\fIoterm\fP);
+\fBint restartterm(const char *\fIterm\fP, int \fIfiledes\fP, int *\fIerrret\fP);
+.PP
+\fBchar *tparm(const char *\fIstr\fP, \fR.\|.\|.\fP);
+ \fI/* or */
+\fBchar *tparm(const char *\fIstr\fP, long \fIp1\fP \fR.\|.\|.\fP \fBlong\fP \fIp9\fP);
+.PP
+\fBint tputs(const char *\fIstr\fP, int \fIaffcnt\fP, int (*\fIputc\fP)(int));
+\fBint putp(const char *\fIstr\fP);
+.PP
+\fBint vidputs(chtype \fIattrs\fP, int (*\fIputc\fP)(int));
+\fBint vidattr(chtype \fIattrs\fP);
+\fBint vid_puts(attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP, int (*\fIputc\fP)(int));
+\fBint vid_attr(attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP);
+.PP
+\fBint mvcur(int \fIoldrow\fP, int \fIoldcol\fP, int \fInewrow\fP, int \fInewcol\fP);
+.PP
+\fBint tigetflag(const char *\fIcap-code\fP);
+\fBint tigetnum(const char *\fIcap-code\fP);
+\fBchar *tigetstr(const char *\fIcap-code\fP);
+.PP
+\fBchar *tiparm(const char *\fIstr\fP, \fR.\|.\|.\fP);
+.PP
+\fI/* extensions */
+\fBchar *tiparm_s(int \fIexpected\fP, int \fImask\fP, const char *\fIstr\fP, ...);
+\fBint tiscan_s(int *\fIexpected\fP, int *\fImask\fP, const char *\fIstr\fP);
+.PP
+\fI/* deprecated */
+\fBint setterm(const char *\fIterm\fP);
.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
-functionality, \fBcurses\fR routines are more suitable and their use is
-recommended.
+These low-level functions must be called by programs that deal directly
+with the
+.I \%term\%info
+database to handle certain terminal capabilities,
+such as programming function keys.
+For all other functionality,
+.I curses
+functions 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:
+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
+Capability names and codes use the POSIX portable character set.
.bP
-capability string values have no associated encoding;
+Capability string values have no associated encoding;
they are strings of 8-bit characters.
.SS Initialization
+Initially,
+\fB\%setupterm\fP should be called.
+The high-level
+.I curses
+functions \fB\%initscr\fP and \fB\%newterm\fP call \fB\%setupterm\fP to
+initialize the low-level set of terminal-dependent variables listed in
+\fB\%term_variables\fP(3X).
.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),
+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.
+The header files
+.I \%curses.h
+and
+.I \%term.h
+should be included
+(in that 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:
+The
+.I \%term\%info
+variables
+.B \%lines
+and
+.B \%columns
+are initialized by \fB\%setupterm\fP as follows.
.bP
-If \fBuse_env(FALSE)\fR has been called, values for
-\fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used.
+If \fB\%use_env(FALSE)\fP has been called,
+values for
+.B \%lines
+and
+.B \%columns
+specified in
+.I \%term\%info
+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 and the program is running in a window, the current window size
+Otherwise,
+if the environment variables
+.I LINES
+and
+.I \%COLUMNS
+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.
-.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
+Otherwise,
+if the environment variables do not exist,
+the values for
+.B \%lines
+and
+.B \%columns
+specified in the
+.I \%term\%info
+database are used.
+.PP
+Parameterized strings should be passed through \fB\%tparm\fP to
+instantiate them.
+All
+.I \%term\%info
+strings
+(including the output of \fB\%tparm\fP)
+should be sent to the terminal device with \fB\%tputs\fP or
+\fB\%putp\fP.
+Call \fB\%reset_shell_mode\fP to restore the terminal modes before
+exiting;
+see \fB\%curs_kernel\fP(3X).
+.PP
+Programs that use
cursor addressing should
.bP
-output \fBenter_ca_mode\fR upon startup and
+output \fB\%enter_ca_mode\fP upon startup and
.bP
-output \fBexit_ca_mode\fR before exiting.
+output \fB\%exit_ca_mode\fP before exiting.
.PP
-Programs which execute shell subprocesses should
+Programs that execute shell subprocesses should
.bP
-call \fBreset_shell_mode\fR and
-output \fBexit_ca_mode\fR before the shell
+call \fB\%reset_shell_mode\fP and
+output \fB\%exit_ca_mode\fP before the shell
is called and
.bP
-output \fBenter_ca_mode\fR and
-call \fBreset_prog_mode\fR after returning from the shell.
+output \fB\%enter_ca_mode\fP and
+call \fB\%reset_prog_mode\fP 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.
-These are its parameters:
+\fB\%setupterm\fP reads in the
+.I \%term\%info
+database,
+initializing the
+.I \%term\%info
+structures,
+but does not set up the output virtualization structures used by
+.IR curses .
+Its parameters follow.
.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.
+.I term
+is the terminal type,
+a character string.
+If
+.I term
+is null,
+the environment variable
+.I TERM
+is read.
.TP 5
-\fIfiledes\fP
-is the file descriptor used for all output.
+.I filedes
+is the file descriptor used for getting and setting terminal I/O modes.
+.IP
+Higher-level applications use \fB\%newterm\fP(3X) to initialize the
+terminal,
+passing an output
+.I stream
+rather than a
+.IR descriptor .
+In
+.IR curses ,
+the two are the same because \fB\%newterm\fP calls \fB\%setupterm\fP,
+passing the file descriptor derived from its output stream parameter.
.TP 5
-\fIerrret\fP
+.I errret
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 return value of \fBOK\fR combined with status of \fB1\fR in \fIerrret\fR
+If
+.I errret
+is not null,
+then \fB\%setupterm\fP returns
+.B OK
+or
+.B ERR
+and stores a status value in the integer pointed to by
+.IR errret .
+A return value of
+.B OK
+combined with status of
+.B 1
+in
+.I errret
is normal.
.IP
-If \fBERR\fR is returned, examine \fIerrret\fR:
+If
+.B ERR
+is returned,
+examine
+.I errret:
.RS
.TP 5
.B 1
-means that the terminal is hardcopy, cannot be used for curses applications.
+means that the terminal is hardcopy,
+and cannot be used for
+.I curses
+applications.
.IP
-\fBsetupterm\fP determines if the entry is a hardcopy type by
-checking the \fBhc\fP (\fBhardcopy\fP) capability.
+\fB\%setupterm\fP determines if the entry is a hardcopy type by
+checking the
+.B \%hardcopy
+.RB ( hc )
+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.
+having too little information for
+.I curses
+applications to run.
.IP
-\fBsetupterm\fP determines if the entry is a generic type by
-checking the \fBgn\fP (\fBgeneric\fP) capability.
+\fB\%setupterm\fP determines if the entry is a generic type by
+checking the
+.B \%generic_type
+.RB ( gn )
+capability.
.TP 5
.B \-1
-means that the \fBterminfo\fR database could not be found.
+means that the
+.I \%term\%info
+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:
-.sp
- \fBsetupterm((char *)0, 1, (int *)0);\fR,
-.sp
-which uses all the defaults and sends the output to \fBstdout\fR.
+If
+.I errret
+is null,
+\fB\%setupterm\fP reports an error message upon finding an error and
+exits.
+Thus,
+the simplest call is:
+.RS
+.IP
+.EX
+setupterm((char *)0, 1, (int *)0);
+.EE
.RE
-.\" ***************************************************************************
-.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.
+.IP
+which uses all the defaults and sends the output to
+.BR stdout .
+.RE
+.\" ********************************************************************
+.SS "The Terminal State"
+\fB\%setupterm\fP stores its information about the terminal in a
+.I \%TERMINAL
+structure pointed to by the global variable \fB\%cur_term\fP.
If it detects an error,
-or decides that the terminal is unsuitable (hardcopy or generic),
+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,
+If \fB\%setupterm\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.
-.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
-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).
-\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
+\fB\%setupterm\fP allocates new storage for each set of terminal
+capabilities.
.PP
-The \fBtparm\fR routine instantiates the string \fIstr\fR with
-parameters \fIpi\fR. A pointer is returned to the result of \fIstr\fR
+\fB\%set_curterm\fP sets \fB\%cur_term\fP to
+.IR \%nterm ,
+and makes all of the
+.I \%term\%info
+Boolean,
+numeric,
+and string variables use the values from
+.IR \%nterm .
+It returns the old value of \fB\%cur_term\fP.
+.PP
+\fB\%del_curterm\fP frees the space pointed to by
+.I \%oterm
+and makes it available for further use.
+If
+.I \%oterm
+is
+the same as \fB\%cur_term\fP,
+references to any of the
+.I \%term\%info
+Boolean,
+numeric,
+and string variables thereafter may refer to invalid memory locations
+until another \fB\%setupterm\fP has been called.
+.PP
+\fB\%restartterm\fP is similar to \fB\%setupterm\fP and \fB\%initscr\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).
+\fB\%restartterm\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,
+\fB\%restartterm\fP saves various terminal state bits,
+calls \fB\%setupterm\fP,
+and then restores the bits.
+.\" ********************************************************************
+.SS "Formatting Output"
+\fB\%tparm\fP instantiates the string
+.I str
+with parameters
+.IR pi .
+A pointer is returned to the result of
+.I str
with the parameters applied.
-Application developers should keep in mind these quirks of the interface:
+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.
+Although \fB\%tparm\fP's actual parameters may be integers or strings,
+the prototype expects
+.I long
+(integer) values.
.bP
-Aside from the \fBset_attributes\fP (\fBsgr\fP) capability,
+Aside from the
+.B \%set_attributes\fP
+.RB ( sgr )
+capability,
most terminal capabilities require no more than one or two parameters.
+.bP
+Padding information is ignored by \fB\%tparm\fP;
+it is interpreted by \fB\%tputs\fP.
+.bP
+The capability string is null-terminated.
+Use \*(``\e200\*('' 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
+\fB\%tiparm\fP is a newer form of \fB\%tparm\fP which uses
+.I \%stdarg.h
rather than a fixed-parameter list.
-Its numeric parameters are integers (int) rather than longs.
-.\" ***************************************************************************
-.SS Output Functions
+Its numeric parameters are
+.IR int s
+rather than
+.IR long "s."
+.PP
+Both \fB\%tparm\fP and \fB\%tiparm\fP assume that the application passes
+parameters consistent with the terminal description.
+Two extensions are provided as alternatives to deal with untrusted data.
+.bP
+\fB\%tiparm_s\fP is an extension which is a safer formatting function
+than \fB\%tparm\fR or \fB\%tiparm\fR,
+because it allows the developer to tell the
+.I curses
+library how many parameters to expect in the parameter list,
+and which may be string parameters.
+.IP
+The \fImask\fP parameter has one bit set for each of the parameters
+(up to 9)
+passed as
+.I char
+pointers rather than numbers.
+.bP
+The extension \fB\%tiscan_s\fP allows the application to inspect a
+formatting capability to see what the
+.I curses
+library would assume.
+.\" ********************************************************************
+.SS "Output Functions"
+String capabilities can contain padding information,
+a time delay
+(accommodating performance limitations of hardware terminals)
+expressed as \fB$<\fIn\fB>\fR,
+where \fIn\fP is a nonnegative integral count of milliseconds.
+If \fIn\fP exceeds 30,000
+(thirty seconds),
+it is capped at that value.
.PP
-The \fBtputs\fR routine applies padding information to the string
-\fIstr\fR and outputs it:
+\fB\%tputs\fP interprets time-delay information in the string
+.I str
+and outputs it,
+executing the delays:
.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.
+The
+.I str
+parameter must be a
+.I \%term\%info
+string variable or the return value of
+\fB\%tparm\fP,
+\fB\%tiparm\fP,
+\fB\%tgetstr\fP,
+or \fB\%tgoto\fP.
.IP
-The \fBtgetstr\fP and \fBtgoto\fP functions are part of the \fItermcap\fP
+The \fB\%tgetstr\fP and \fB\%tgoto\fP functions are part of the
+.I termcap
interface,
-which happens to share this function name with the \fIterminfo\fP interface.
+which happens to share these function names with the
+.I \%term\%info
+API.
.bP
-\fIaffcnt\fR is the number of lines affected, or 1 if
-not applicable.
+.I affcnt
+is the number of lines affected,
+or
+.B 1
+if not applicable.
.bP
-\fIputc\fR is a \fBputchar\fR-like routine to which
-the characters are passed, one at a time.
+.I putc
+is a
+.IR \%putchar -like
+function to which the characters are passed,
+one at a time.
+.IP
+If \fB\%tputs\fP processes a time-delay,
+it uses the \fB\%delay_output\fP(3X) function,
+routing any resulting padding characters through this function.
.PP
-The \fBputp\fR routine calls \fBtputs(\fR\fIstr\fR\fB, 1, putchar)\fR.
-The output of \fBputp\fR always goes to \fBstdout\fR, rather than
-the \fIfiledes\fR specified in \fBsetupterm\fR.
+\fB\%putp\fR calls
+.RB \%\*(`` tputs(\c
+.IB str ", 1, putchar)\c"
+\*(''.
+The output of \fB\%putp\fP always goes to
+.BR stdout ,
+rather than the
+.I \%file\%des
+specified in \fB\%setupterm\fP.
.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
-the \fBputchar\fR-like routine \fIputc\fR.
+\fB\%vidputs\fP displays the string on the terminal in the video
+attribute mode
+.IR attrs ,
+which is any combination of the attributes listed in \fB\%curses\fP(3X).
+The characters are passed to the
+.IR \%putchar -like
+function
+.IR putc .
.PP
-The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except
-that it outputs through \fBputchar\fR.
+\fB\%vidattr\fP is like \fB\%vidputs\fP,
+except that it outputs through \fI\%putchar\fP(3).
.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.,
+.B \%vid_attr
+and
+.B \%vid_puts
+correspond to
+.B \%vidattr
+and
+.BR \%vidputs ,
+respectively.
+They use multiple parameters to represent the character attributes and
+color;
+namely,
.bP
-\fIattrs\fP of type \fBattr_t\fP for the attributes and
+.IR \%attrs ,
+of type
+.IR \%attr_t ,
+for the attributes and
.bP
-\fIpair\fP of type \fBshort\fP for the color-pair number.
+.IR pair ,
+of type
+.IR short ,
+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.
+Use the attribute constants prefixed with
+.RB \*(`` WA_ \*(''
+with
+.B \%vid_attr
+and
+.BR \%vid_puts .
.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).
+X/Open Curses reserves the
+.I opts
+argument for future use,
+saying that applications must provide a null pointer for that argument;
+but see section \*(``EXTENSIONS\*('' below.
.PP
-While \fBputp\fR 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 \fBHISTORY\fP).
-.\" ***************************************************************************
-.SS Terminal Capability Functions
+\fB\%mvcur\fP provides low-level cursor motion.
+It takes effect immediately
+(rather than at the next refresh).
+Unlike the other low-level output functions,
+which either write to the standard output or pass an output function
+parameter,
+\fB\%mvcur\fP uses an output file descriptor derived from
+the output stream parameter of \fB\%newterm\fP(3X).
.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 \fIcapname\fR for each capability is given in the table column entitled
-\fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n).
+While \fB\%putp\fP and \fB\%mvcur\fP are low-level functions that do not
+use high-level
+.I curses
+state,
+.I \%ncurses
+declares them in
+.I \%curses.h
+because System\ V did this
+(see section \*(``HISTORY\*('' below).
+.\" ********************************************************************
+.SS "Terminal Capability Functions"
+\fB\%tigetflag\fP,
+\fB\%tigetnum\fP,
+and \fB\%tigetstr\fP return the value of the capability corresponding to
+the
+.I \%term\%info
+.IR cap-code ,
+such as
+.BR xenl ,
+passed to them.
+The
+.I cap-code
+for each capability is given in the table column entitled
+.I cap-code
+code in the capabilities section of \fB\%terminfo\fP(5).
.PP
-These routines return special values to denote errors.
+These functions return special values to denote errors.
.PP
-The \fBtigetflag\fR routine returns
+\fB\%tigetflag\fP returns
.TP
-\fB\-1\fR
-if \fIcapname\fR is not a boolean capability,
+.B \-1
+if
+.I cap-code
+is not a Boolean capability,
or
.TP
-\fB0\fR
+.B 0
if it is canceled or absent from the terminal description.
.PP
-The \fBtigetnum\fR routine returns
+\fB\%tigetnum\fP returns
.TP
-\fB\-2\fR
-if \fIcapname\fR is not a numeric capability, or
+.B \-2
+if
+.I cap-code
+is not a numeric capability,
+or
.TP
-\fB\-1\fR
+.B \-1
if it is canceled or absent from the terminal description.
.PP
-The \fBtigetstr\fR routine returns
+\fB\%tigetstr\fP returns
.TP
-\fB(char *)\-1\fR
-if \fIcapname\fR is not a string capability,
+.B "(char *)\-1"
+if
+.I cap-code
+is not a string capability,
or
.TP
-\fB0\fR
+.B 0
if it is canceled or absent from the terminal description.
-.\" ***************************************************************************
-.SS Terminal Capability Names
-.PP
+.\" ********************************************************************
+.SS "Terminal Capability Names"
These null-terminated arrays contain
.bP
-the short terminfo names (\*(``codes\*(''),
+the short \fI\%term\%info\fP names (\*(``codes\*(''),
.bP
-the \fBtermcap\fR names (\*(``names\*(''), and
+the \fItermcap\fP names (\*(``names\*(''),
+and
.bP
-the long terminfo names (\*(``fnames\*('')
+the long \fI\%term\%info\fP names (\*(``fnames\*('')
+.PP
+for each of the predefined
+.I \%term\%info
+variables:
.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
+.nf
+\fBconst char *boolnames[]\fP, \fB*boolcodes[]\fP, \fB*boolfnames[]\fP
+\fBconst char *numnames[]\fP, \fB*numcodes[]\fP, \fB*numfnames[]\fP
+\fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP
+.fi
.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.
+.\" ********************************************************************
+.SS "Releasing Memory"
+Each successful call to \fB\%setupterm\fP allocates memory to hold the
+terminal description.
+As a side effect,
+it sets \fB\%cur_term\fP to point to this memory.
+If an application calls
+.IP
+.EX
+del_curterm(cur_term);
+.EE
.PP
-Routines that return pointers always return \fBNULL\fR on error.
+the memory will be freed.
.PP
-X/Open defines no error conditions.
-In this implementation
-.RS 3
+The formatting functions \fB\%tparm\fP and \fB\%tiparm\fP extend the
+storage allocated by \fB\%setupterm\fP as follows.
+.bP
+They add the \*(``static\*(''
+.I \%term\%info
+variables [a-z].
+Before
+.I \%ncurses
+6.3,
+those were shared by all screens.
+With
+.I \%ncurses
+6.3,
+those are allocated per screen.
+See \fB\%terminfo\fP(5).
+.bP
+To improve performance,
+.I \%ncurses
+6.3 caches the result of analyzing
+.I \%term\%info
+strings for their parameter types.
+That is stored as a binary tree referenced from the
+.I \%TERMINAL
+structure.
+.PP
+The higher-level \fB\%initscr\fP and \fB\%newterm\fP functions use
+\fB\%setupterm\fP.
+Normally they do not free this memory,
+but it is possible to do that using the \fB\%delscreen\fP(3X) function.
+.\" ********************************************************************
+.SH RETURN VALUE
+X/Open Curses defines no failure conditions.
+In
+.IR \%ncurses ,
.TP 5
-\fBdel_curterm\fP
-returns an error
-if its terminal parameter is null.
+.B del_curtem
+fails if its terminal parameter is null.
.TP 5
-\fBputp\fP
-calls \fBtputs\fP, returning the same error-codes.
+.B putp
+calls \fB\%tputs\fP,
+returning the same error codes.
.TP 5
-\fBrestartterm\fP
-returns an error
-if the associated call to \fBsetupterm\fP returns an error.
+.B restartterm
+fails if the associated call to \fB\%setupterm\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).
+.B setupterm
+fails if it cannot allocate enough memory,
+or create the initial windows
+.RB ( \%stdscr ,
+.BR \%curscr ,
+and
+.BR \%newscr )
Other error conditions are documented above.
.TP 5
-\fBtputs\fP
-returns an error if the string parameter is null.
+.B tparm
+returns a null pointer if the capability would require unexpected
+parameters;
+that is,
+too many,
+too few,
+or incorrect types
+(strings where integers are expected,
+or vice versa).
+.TP 5
+.B tputs
+fails 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
+X/Open Curses states that \fB\%tputs\fP ignores the return value
+of the output function \fI\%putc\fP.
+.\" ********************************************************************
+.SH NOTES
+The
+.B \%vid_attr
+function in
+.I \%ncurses
+is a special case.
+It was originally implemented based on a draft of X/Open Curses,
+as a macro,
+before other parts of the
+.I \%ncurses
+wide-character API were developed,
+and unlike the other wide-character functions,
+is also provided in the non-wide-character configuration.
+.\" ********************************************************************
+.SH EXTENSIONS
+The functions marked as extensions were designed for
+.IR \%ncurses ,
+and are not found in SVr4
+.IR curses ,
+4.4BSD
+.IR curses ,
+or any other previous
+.I curses
+implementation.
+.PP
+.I \%ncurses
+allows
+.I opts
+to be a pointer to
+.IR int ,
+which overrides the
+.I pair
+.RI ( short )
+argument.
+.\" ********************************************************************
+.SH PORTABILITY
+\fB\%setterm\fP is not described by X/Open and must be considered
+non-portable.
+All other functions are as described by X/Open.
+.SS "Compatibility Macros"
This implementation provides a few macros for compatibility with systems
-before SVr4 (see \fBHISTORY\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\fR, are likewise macros.
-The one function, \fBsetterm\fR, is mentioned in the manual page.
-The manual page notes that the \fBsetterm\fR routine
-was replaced by \fBsetupterm\fR, stating that the call:
-.sp
- \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR
-.sp
-provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR,
-and is not recommended for new programs.
-This implementation provides each of those symbols
-as macros for BSD compatibility,
-.\" ***************************************************************************
+before SVr4
+(see section \*(``HISTORY\*('' below).
+They include
+\fB\%Bcrmode\fP,
+\fB\%Bfixterm\fP,
+\fB\%Bgettmode\fP,
+\fB\%Bnocrmode\fP,
+\fB\%Bresetterm\fP,
+\fB\%Bsaveterm\fP,
+and
+\fB\%Bsetterm\fP.
+.PP
+In SVr4,
+these are found in
+.IR \%curses.h ,
+but except for \fB\%setterm\fP,
+are likewise macros.
+The one function,
+\fB\%setterm\fP,
+is mentioned in the manual page.
+It further notes that \fB\%setterm\fP was replaced by \fB\%setupterm\fP,
+stating that the call
+.RS
+.EX
+setupterm(\fIterm\fP, 1, (int *)0)
+.EE
+.RE
+provides the same functionality as \fB\%setterm(\fIterm\fB)\fR,
+discouraging the latter for new programs.
+.I \%ncurses
+implements each of these symbols as macros for BSD
+.I curses
+compatibility.
+.SS "Legacy Data"
+\fB\%setupterm\fP copies the terminal name to the array \fB\%ttytype\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 Curses does not specify them.
+.PP
+Extended terminal capability names,
+as defined by
+.RB \%\*(`` "@TIC@ \-x" \*('',
+are not stored in the arrays described here.
+.SS "Output Buffering"
+Older versions of \fI\%ncurses\fP assumed that the file descriptor
+passed to \fB\%setupterm\fP from \fB\%initscr\fP or \fB\%newterm\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
+.IR curses ),
+it was problematic because
+.I \%ncurses
+did not allow a reliable way to clean up on receiving
+.BR SIGTSTP .
+.PP
+The current version (ncurses6)
+uses output buffers managed directly by
+.IR \%ncurses .
+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
+.I \%ncurses
+employ alternate versions of these functions using the more reliable
+buffering scheme.
+.SS "Function Prototypes"
+The X/Open Curses prototypes are based on the SVr4
+.I 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
+.I \%const
+less effectively than a later design might,
+sometimes applying it needlessly to values that are already constant,
+and in most cases overlooking parameters that normally would use
+.IR \%const .
+Passing
+.IR \%const -qualified
+parameters to functions that do not declare them
+.I \%const
+may prevent the program from compiling.
+On the other hand,
+\*(``writable strings\*('' are an obsolescent feature.
+.IP
+As an extension,
+this implementation can be configured to change the function prototypes
+to use the
+.I \%const
+keyword.
+The
+.I \%ncurses
+ABI 6 enables this feature by default.
+.bP
+X/Open Curses prototypes \fB\%tparm\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 nine 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 \fB\%tiparm\fP function in mid-2009.
+.IP
+While \fB\%tiparm\fP is always provided in \fI\%ncurses\fP,
+the older form is only available as a build-time configuration option.
+If not specially configured,
+\fB\%tparm\fP is the same as \fB\%tiparm\fP.
+.PP
+Both forms of \fB\%tparm\fP have drawbacks:
+.bP
+Most of the calls to \fB\%tparm\fP use only one or two parameters.
+Passing nine on each call is awkward.
+.IP
+Using
+.I long
+for the numeric parameter type is a workaround to make the parameter use
+the same amount of stack as a pointer.
+That approach dates back to the mid-1980s,
+before C was standardized.
+Since then,
+there is a standard
+(and pointers are not required to fit in a
+.IR long ).
+.bP
+Providing the right number of parameters for a variadic function
+such as \fB\%tiparm\fP can be a problem,
+in particular for string parameters.
+However,
+only a few
+.I \%term\%info
+capabilities use string parameters
+(for instance,
+the ones used for programmable function keys).
+.IP
+The \fI\%ncurses\fP library checks usage of these capabilities,
+and returns an error if the capability mishandles string parameters.
+But it cannot check if a calling program provides strings in the right
+places for the \fB\%tparm\fP calls.
+.IP
+The \fB\%@TPUT@\fR(1) program checks its use of these capabilities with
+a table,
+so that it calls \fB\%tparm\fP correctly.
+.SS "Special \fITERM\fP treatment"
+If configured to use the terminal driver,
+.\" XXX: as opposed to the Unix terminal driver, termio(s)?
+as with the MinGW port,
+.bP
+\fB\%setupterm\fP interprets a missing/empty \fITERM\fP variable as the
+special value \*(``unknown\*(''.
+.IP
+SVr4
+.I curses
+uses the special value \*(``dumb\*(''.
+.IP
+The difference between the two is that the former uses the
+.B \%generic_type
+.RB ( gn )
+.I \%term\%info
+capability,
+while the latter does not.
+A generic terminal is unsuitable for full-screen applications.
+.bP
+\fB\%setupterm\fP allows explicit use of the
+the windows console driver by checking if \fB$TERM\fP is set to
+\*(``#win32con\*('' or an abbreviation of that string.
+.SS "Other Portability Issues"
+In SVr4,
+\fB\%set_curterm\fP returns an
+.IR int ,
+.B OK
+or
+.BR ERR .
+We have chosen to implement the X/Open Curses semantics.
+.PP
+In SVr4,
+the third argument of \fB\%tputs\fP has the type
+.RB \*(`` "int (*putc)(char)" \*(''.
+.PP
+At least one implementation of X/Open Curses (Solaris) returns a value
+other than
+.B OK
+or
+.B ERR
+from \fB\%tputs\fP.
+It instead returns the length of the string,
+and does no error checking.
+.PP
+X/Open Curses notes that after calling \fB\%mvcur\fP,
+the
+.I curses
+state may not match the actual terminal state,
+and that an application should touch and refresh the window before
+resuming normal
+.I curses
+calls.
+Both
+.I \%ncurses
+and SVr4
+.I curses
+implement \fB\%mvcur\fP using the
+.I SCREEN
+data allocated in either \fB\%initscr\fP or \fB\%newterm\fP.
+So though it is documented as a
+.I \%term\%info
+function,
+\fB\%mvcur\fP is really a
+.I curses
+function that is not well specified.
+.PP
+X/Open Curses states that the old location must be given for
+\fB\%mvcur\fP to accommodate terminals that lack absolute cursor
+positioning.
+.\" X/Open Curses Issue 7, p. 161
+.I \%ncurses
+allows the caller to use \-1 for either or both old coordinates.
+The \-1 tells
+.I \%ncurses
+that the old location is unknown,
+and that it must use only absolute motion,
+as with the
+.B \%cursor_address
+.RB ( cup )
+capability,
+rather than the least costly combination of absolute and relative
+motion.
+.\" ********************************************************************
.SH HISTORY
+SVr2 (1984) introduced the
+.I \%term\%info
+feature.
+Its programming manual mentioned the following low-level functions.
.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
+lB lB
+lB lx.
+Function Description
+_
+fixterm restore terminal to \*(``in \fIcurses\fP\*('' state
+gettmode establish current terminal 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
+putp use \fBtputs\fP to send characters via \fIputchar\fP
+resetterm set terminal modes to \*(``out of \fIcurses\fP\*(''\
+ state
+resetty reset terminal flags to stored value
+saveterm save current modes as \*(``in \fIcurses\fP\*('' state
+savetty store current terminal flags
setterm establish terminal with given type
setupterm establish terminal with given type
-tparm instantiate a string expression with parameters
+tparm interpolate parameters into string capability
tputs apply padding information to a string
-vidattr like \fBvidputs\fP, but outputs through \fBputchar\fP
+vidattr like \fBvidputs\fP, but output through \fIputchar\fP
vidputs T{
-output a string to put terminal in a specified video attribute mode
+write string to terminal, applying specified attributes
T}
.TE
.PP
The programming manual also mentioned
-functions provided for termcap compatibility
-(commenting that they \*(``may go away at a later date\*(''):
+functions provided for
+.I termcap
+compatibility
+(commenting that they \*(``may go away at a later date\*('').
+.PP
.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
+lB lB
+lB lx.
+Function Description
+_
+tgetent look up \fItermcap\fP 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
+write characters via a function parameter, applying padding
T}
.TE
.PP
-Early terminfo programs obtained capability values from the
-\fBTERMINAL\fP structure initialized by \fBsetupterm\fR.
+Early
+.I \%term\%info
+programs obtained capability values from the
+.I \%TERMINAL
+structure initialized by \fB\%setupterm\fP.
+.PP
+SVr3 (1987) extended
+.I \%term\%info
+by adding functions to retrieve capability values
+(like the
+.I termcap
+interface),
+and reusing \fB\%tgoto\fP and \fB\%tputs\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\fR \fBDescription\fR
-tigetflag get boolean entry for given \fIid\fP
+lB lB
+lB lx.
+Function Description
+_
+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:
+SVr3 also replaced several of the SVr2
+.I \%term\%info
+functions that had no counterpart in the
+.I termcap
+interface,
+documenting them as obsolete.
+.PP
.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
+lB lB
+l lx.
+Function Replaced by
+_
+crmode cbreak
+fixterm reset_prog_mode
+gettmode \fIn/a\fP
+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.
+SVr3 kept the \fB\%mvcur\fP,
+\fB\%vidattr\fP,
+and \fB\%vidputs\fP functions,
+along with \fB\%putp\fP,
+\fB\%tparm\fP,
+and \fB\%tputs\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).
+and to handle capabilities accessed by functions such as \fB\%vidattr\fP
+(which used more than the two parameters supported by \fB\%tgoto\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
-.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.
+descriptions;
+for example,
+\fB\%set_curterm\fP.
+Some changes reflected incremental improvements to the SVr2 library.
.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\*(''.
+The
+.I \%TERMINAL
+type definition was introduced in SVr3.01,
+for the
+.I term
+structure provided in SVr2.
.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
+Various global variables such as \fB\%boolnames\fP were mentioned
+in the programming manual at this point,
+though the variables had been provided in SVr2.
.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 X/Open Curses
-semantics.
+SVr4 (1989) added the \fB\%vid_attr\fP and \fB\%vid_puts\fP functions.
.PP
-In System V Release 4, the third argument of \fBtputs\fR has the type
-\fBint (*putc)(char)\fR.
-.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.
+Other low-level functions are declared in the
+.I curses
+header files of Unix systems,
+but none are documented.
+Those noted as \*(``obsolete\*('' by SVr3 remained in use by System\ V's
+\fIvi\fP(1) editor.
.SH SEE ALSO
-\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)
+\fB\%curses\fP(3X),
+\fB\%curs_initscr\fP(3X),
+\fB\%curs_kernel\fP(3X),
+\fB\%curs_memleaks\fP(3X),
+\fB\%curs_termcap\fP(3X),
+\fB\%curs_variables\fP(3X),
+\fB\%putc\fP(3),
+\fB\%term_variables\fP(3X),
+\fB\%terminfo\fP(5)
projects / ncurses.git / blobdiff