+'\" t
.\"***************************************************************************
-.\" Copyright (c) 1999-2008,2010 Free Software Foundation, Inc. *
+.\" 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 *
.\" copy of this software and associated documentation files (the *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_terminfo.3x,v 1.31 2010/01/09 19:43:39 tom Exp $
-.TH curs_terminfo 3X ""
-.ds n 5
-.na
-.hy 0
+.\" $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
+..
+.
.SH NAME
-\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
+\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
-.br
-\fB#include <term.h>\fR
-.PP
-\fBint setupterm(char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
-.br
-\fBint setterm(char *\fR\fIterm\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(char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
-.br
-\fBchar *tparm(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
-.br
-\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)(char));\fR
-.br
-\fBint vid_attr(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB);\fR
-.br
-\fBint mvcur(int \fR\fIoldrow\fR\fB, int \fR\fIoldcol\fR\fB, int \fR\fInewrow\fR, int \fR\fInewcol\fR\fB);\fR
-.br
-\fBint tigetflag(char *\fR\fIcapname\fR\fB);\fR
-.br
-\fBint tigetnum(char *\fR\fIcapname\fR\fB);\fR
-.br
-\fBchar *tigetstr(char *\fR\fIcapname\fR\fB);\fR
-.br
-\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.
-.PP
-Initially, \fBsetupterm\fR should be called. Note that
-\fBsetupterm\fR is automatically called by \fBinitscr\fR and
-\fBnewterm\fR. This defines the set of terminal-dependent variables
-[listed in \fBterminfo\fR(\*n)].
-The \fBterminfo\fR variables
-\fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR as
-follows:
-.RS
+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
-If \fBuse_env(FALSE)\fR has been called, values for
-\fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used.
+None of these functions use
+(or are aware of)
+multibyte character strings such as UTF-8.
+.bP
+Capability names and codes use the POSIX portable character set.
+.bP
+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
-Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR
-exist, their values are used. If these environment variables do not
-exist and the program is running in a window, the current window size
-is used. Otherwise, if the environment variables do not exist, the
-values for \fBlines\fR and \fBcolumns\fR specified in the
-\fBterminfo\fR database are used.
-.RE
+Applications can use the terminal capabilities either directly
+(via header definitions),
+or by special functions.
+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
+.I \%term\%info
+variables
+.B \%lines
+and
+.B \%columns
+are initialized by \fB\%setupterm\fP as follows.
+.bP
+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
+.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
+.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 \fB\%enter_ca_mode\fP upon startup and
+.bP
+output \fB\%exit_ca_mode\fP before exiting.
+.PP
+Programs that execute shell subprocesses should
+.bP
+call \fB\%reset_shell_mode\fP and
+output \fB\%exit_ca_mode\fP before the shell
+is called and
+.bP
+output \fB\%enter_ca_mode\fP and
+call \fB\%reset_prog_mode\fP after returning from the shell.
.PP
-The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this
-order) to get the definitions for these strings, numbers, and flags.
-Parameterized strings should be passed through \fBtparm\fR to instantiate them.
-All \fBterminfo\fR strings [including the output of \fBtparm\fR] should be printed
-with \fBtputs\fR or \fBputp\fR. Call the \fBreset_shell_mode\fR to restore the
-tty modes before exiting [see \fBcurs_kernel\fR(3X)]. Programs which use
-cursor addressing should output \fBenter_ca_mode\fR upon startup and should
-output \fBexit_ca_mode\fR before exiting. Programs desiring shell escapes
-should call
-.PP
-\fBreset_shell_mode\fR and output \fBexit_ca_mode\fR before the shell
-is called and should output \fBenter_ca_mode\fR and call
-\fBreset_prog_mode\fR after returning from the shell.
-.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
-\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
+\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
+.I term
+is the terminal type,
+a character string.
+If
+.I term
+is null,
+the environment variable
+.I TERM
+is read.
+.TP 5
+.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
+.I errret
+points to an optional location where an error status can be returned to
+the caller.
+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.
-If \fBERR\fR is returned, examine \fIerrret\fR:
+.IP
+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
+\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
+\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.
+.B \-1
+means that the
+.I \%term\%info
+database could not be found.
.RE
+.IP
+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
+.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),
+it discards this information,
+making it not available to applications.
.PP
-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.
-.PP
-The \fBsetterm\fR routine is being 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
-is not recommended for new programs.
-.PP
-The \fBset_curterm\fR routine sets the variable \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). It assumes that
-the windows and the input and output options are the same as when memory was
-saved, but the terminal type and baud rate may be different. Accordingly,
-it saves various tty state bits, calls \fBsetupterm\fP,
-and then restores the bits.
+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,
+\fB\%setupterm\fP allocates new storage for each set of terminal
+capabilities.
+.PP
+\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
-The \fBtparm\fR routine instantiates the string \fIstr\fR with
-parameters \fIpi\fR. A pointer is returned to the result of \fIstr\fR
+\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:
+.bP
+Although \fB\%tparm\fP's actual parameters may be integers or strings,
+the prototype expects
+.I long
+(integer) values.
+.bP
+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.
+Its numeric parameters are
+.IR int s
+rather than
+.IR long "s."
.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
-the characters are passed, one at a time.
+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
+\fB\%tputs\fP interprets time-delay information in the string
+.I str
+and outputs it,
+executing the delays:
+.bP
+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 \fB\%tgetstr\fP and \fB\%tgoto\fP functions are part of the
+.I termcap
+interface,
+which happens to share these function names with the
+.I \%term\%info
+API.
+.bP
+.I affcnt
+is the number of lines affected,
+or
+.B 1
+if not applicable.
+.bP
+.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.
-Note that the output of \fBputp\fR always goes to \fBstdout\fR, not to
-the \fIfildes\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,
+.B \%vid_attr
+and
+.B \%vid_puts
+correspond to
+.B \%vidattr
+and
+.BR \%vidputs ,
respectively.
-They use a set of arguments for representing the video attributes plus color,
-i.e.,
-one of type attr_t for the attributes and one of short for
-the color_pair number.
-The \fBvid_attr\fR and \fBvid_puts\fR routines
-are designed to use the attribute constants with the \fIWA_\fR prefix.
-The opts argument is reserved for future use.
-Currently, applications must provide a null pointer for that argument.
-.PP
-The \fBmvcur\fR routine provides low-level cursor motion. It takes
-effect immediately (rather than at the next refresh).
-.PP
-The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return
-the value of the capability corresponding to the \fBterminfo\fR
-\fIcapname\fR passed to them, such as \fBxenl\fR.
-.PP
-The \fBtigetflag\fR routine returns the value \fB-1\fR if
-\fIcapname\fR is not a boolean capability,
-or \fB0\fR if it is canceled or absent from the terminal description.
-.PP
-The \fBtigetnum\fR routine returns the value \fB-2\fR if
-\fIcapname\fR is not a numeric capability,
-or \fB-1\fR if it is canceled or absent from the terminal description.
-.PP
-The \fBtigetstr\fR routine returns the value \fB(char *)-1\fR
-if \fIcapname\fR is not a string capability,
-or \fB0\fR if it is canceled or absent from the terminal description.
-.PP
-The \fIcapname\fR for each capability is given in the table column entitled
-\fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n).
-.sp
+They use multiple parameters to represent the character attributes and
+color;
+namely,
+.bP
+.IR \%attrs ,
+of type
+.IR \%attr_t ,
+for the attributes and
+.bP
+.IR pair ,
+of type
+.IR short ,
+for the color pair number.
+.PP
+Use the attribute constants prefixed with
+.RB \*(`` WA_ \*(''
+with
+.B \%vid_attr
+and
+.BR \%vid_puts .
+.PP
+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
+\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
+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 functions return special values to denote errors.
+.PP
+\fB\%tigetflag\fP returns
+.TP
+.B \-1
+if
+.I cap-code
+is not a Boolean capability,
+or
+.TP
+.B 0
+if it is canceled or absent from the terminal description.
+.PP
+\fB\%tigetnum\fP returns
+.TP
+.B \-2
+if
+.I cap-code
+is not a numeric capability,
+or
+.TP
+.B \-1
+if it is canceled or absent from the terminal description.
+.PP
+\fB\%tigetstr\fP returns
+.TP
+.B "(char *)\-1"
+if
+.I cap-code
+is not a string capability,
+or
+.TP
+.B 0
+if it is canceled or absent from the terminal description.
+.\" ********************************************************************
+.SS "Terminal Capability Names"
+These null-terminated arrays contain
+.bP
+the short \fI\%term\%info\fP names (\*(``codes\*(''),
+.bP
+the \fItermcap\fP names (\*(``names\*(''),
+and
+.bP
+the long \fI\%term\%info\fP names (\*(``fnames\*('')
+.PP
+for each of the predefined
+.I \%term\%info
+variables:
+.PP
.RS
-\fBchar *boolnames[]\fR, \fB*boolcodes[]\fR, \fB*boolfnames[]\fR
-.sp
-\fBchar *numnames[]\fR, \fB*numcodes[]\fR, \fB*numfnames[]\fR
-.sp
-\fBchar *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
+.\" ********************************************************************
+.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
-These null-terminated arrays contain the \fIcapnames\fR, the
-\fBtermcap\fR codes, and the full C names, for each of the
-\fBterminfo\fR variables.
-.SH RETURN VALUE
-Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
-(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
-completion, unless otherwise noted in the preceding routine descriptions.
+the memory will be freed.
.PP
-Routines that return pointers always return \fBNULL\fR on error.
+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
-X/Open defines no error conditions.
-In this implementation
-.RS
+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
+X/Open Curses states that \fB\%tputs\fP ignores the return value
+of the output function \fI\%putc\fP.
+.\" ********************************************************************
.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.
+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
-Note that \fBvidattr\fR and \fBvidputs\fR may be macros.
+.I \%ncurses
+allows
+.I opts
+to be a pointer to
+.IR int ,
+which overrides the
+.I pair
+.RI ( short )
+argument.
+.\" ********************************************************************
.SH PORTABILITY
-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.
+\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 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
-\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
-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.
+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
-In System V Release 4, the third argument of \fBtputs\fR has the type
-\fBint (*putc)(char)\fR.
+Other implementions may not declare the capability name arrays.
+Some provide them without declaring them.
+X/Open Curses does not specify them.
.PP
-At least one implementation of X/Open Curses (Solaris) returns a value
-other than OK/ERR from \fBtputs\fP.
-That returns the length of the string, and does no error-checking.
+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
-X/Open Curses prototypes \fBtparm\fR with a fixed number of parameters,
+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.
-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;
+.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
+.TS
+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 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 interpolate parameters into string capability
+tputs apply padding information to a string
+vidattr like \fBvidputs\fP, but output through \fIputchar\fP
+vidputs T{
+write string to terminal, applying specified attributes
+T}
+.TE
+.PP
+The programming manual also mentioned
+functions provided for
+.I termcap
+compatibility
+(commenting that they \*(``may go away at a later date\*('').
+.PP
+.TS
+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{
+write characters via a function parameter, applying padding
+T}
+.TE
+.PP
+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
+.TS
+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
+.I \%term\%info
+functions that had no counterpart in the
+.I termcap
+interface,
+documenting them as obsolete.
+.PP
+.TS
+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
-In response to comments by Thomas E. Dickey,
-X/Open Curses Issue 7 proposed the \fBtiparam\fP function in mid-2009.
+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 to handle capabilities accessed by functions such as \fB\%vidattr\fP
+(which used more than the two parameters supported by \fB\%tgoto\fP).
.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 ncurses 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.
+SVr3 introduced the functions for switching between terminal
+descriptions;
+for example,
+\fB\%set_curterm\fP.
+Some changes reflected incremental improvements to the SVr2 library.
+.bP
+The
+.I \%TERMINAL
+type definition was introduced in SVr3.01,
+for the
+.I term
+structure provided in SVr2.
+.bP
+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
-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.
+SVr4 (1989) added the \fB\%vid_attr\fP and \fB\%vid_puts\fP functions.
.PP
-Extended terminal capability names, e.g., as defined by \fBtic\ -x\fP,
-are not stored in the arrays described in this section.
+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),
-\fBputc\fR(3),
-\fBterminfo\fR(\*n)
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\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