'\" t
.\"***************************************************************************
-.\" Copyright 2018-2022,2023 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.125 2023/12/30 23:46:56 tom Exp $
-.TH curs_terminfo 3X 2023-12-30 "ncurses 6.4" "Library calls"
+.\" $Id: curs_terminfo.3x,v 1.129 2024/01/13 22:15:55 tom Exp $
+.TH curs_terminfo 3X 2024-01-13 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.PP
\fBint mvcur(int \fIoldrow\fP, int \fIoldcol\fP, int \fInewrow\fP, int \fInewcol\fP);
.PP
-\fBint tigetflag(const char *\fIcapname\fP);
-\fBint tigetnum(const char *\fIcapname\fP);
-\fBchar *tigetstr(const char *\fIcapname\fP);
+\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
\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
+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
-routines are more suitable and their use is recommended.
+functions are more suitable and their use is recommended.
.PP
None of these functions use
(or are aware of)
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).
+initialize the low-level set of terminal-dependent variables listed in
+\fB\%term_variables\fP(3X).
.PP
-Applications can use the
-terminal capabilities either directly
+Applications can use the terminal capabilities either directly
(via header definitions),
or by special functions.
The header files
.I \%term.h
should be included
(in that order)
-to get the definitions for these strings, numbers, and flags.
+to get the definitions for these strings,
+numbers,
+and flags.
.PP
The
.I \%term\%info
variables
-\fBlines\fP and \fBcolumns\fP are initialized by \fB\%setupterm\fP as
-follows:
+.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 \fBlines\fP and \fBcolumns\fP specified in
+values for
+.B \%lines
+and
+.B \%columns
+specified in
.I \%term\%info
are used.
.bP
Otherwise,
-if the environment variables \fILINES\fP and \fI\%COLUMNS\fP exist,
+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
+If these environment variables do not exist and the program is running
+in a window,
+the current window size
is used.
-Otherwise, if the environment variables do not exist, the
-values for \fBlines\fP and \fBcolumns\fP specified in the
+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 \fBtparm\fP to instantiate them.
+Parameterized strings should be passed through \fB\%tparm\fP to
+instantiate them.
All
.I \%term\%info
strings
-(including the output of \fBtparm\fP)
-should be printed
-with \fBtputs\fP or \fBputp\fP.
-Call \fBreset_shell_mode\fP to restore the
-tty modes before exiting [see \fBcurs_kernel\fP(3X)].
-.PP
-Programs which use
+(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\fP upon startup and
+output \fB\%enter_ca_mode\fP upon startup and
.bP
-output \fBexit_ca_mode\fP 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\fP and
-output \fBexit_ca_mode\fP 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\fP and
-call \fBreset_prog_mode\fP 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 \fB\%setupterm\fP routine reads in the
+\fB\%setupterm\fP reads in the
.I \%term\%info
database,
initializing the
structures,
but does not set up the output virtualization structures used by
.I curses.
-These are its parameters:
+Its parameters follow.
.RS 3
.TP 5
-\fIterm\fP
-is the terminal type, a character string.
-If \fIterm\fP is null,
-the environment variable \fITERM\fP 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
+.I filedes
is the file descriptor used for getting and setting terminal I/O modes.
.IP
-Higher-level applications use \fBnewterm\fP(3X) for initializing the terminal,
-passing an output \fIstream\fP rather than a \fIdescriptor\fP.
-In curses, the two are the same because \fBnewterm\fP calls \fBsetupterm\fP,
+Higher-level applications use \fB\%newterm\fP(3X) to initialize the
+terminal,
+passing an output
+.I stream
+rather than a
+.I descriptor.
+In
+.I 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\fP is not null,
-then \fBsetupterm\fP returns \fBOK\fP or
-\fBERR\fP and stores a status value in the integer pointed to by
-\fIerrret\fP.
-A return value of \fBOK\fP combined with status of \fB1\fP in \fIerrret\fP
+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
+.I errret.
+A return value of
+.B OK
+combined with status of
+.B 1
+in
+.I errret
is normal.
.IP
-If \fBERR\fP is returned, examine \fIerrret\fP:
+If
+.B ERR
+is returned,
+examine
+.I errret:
.RS
.TP 5
.B 1
-means that the terminal is hardcopy, cannot be used
-for \fIcurses\fP 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 \fBhc\fP (\fBhardcopy\fP) capability.
+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 \fIcurses\fP 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 \fBgn\fP \%(\fBgeneric_type\fP) capability.
+checking the
+.B \%generic_type
+.RB ( gn )
+capability.
.TP 5
.B \-1
means that the
database could not be found.
.RE
.IP
-If \fIerrret\fP is
-null, \fB\%setupterm\fP prints an error message upon finding an error
-and exits.
-Thus, the simplest call is:
+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
-\fBsetupterm((char *)0, 1, (int *)0);\fP
+.EX
+setupterm((char *)0, 1, (int *)0);
+.EE
.RE
.IP
-which uses all the defaults and sends the output to \fBstdout\fP.
+which uses all the defaults and sends the output to
+.BR stdout .
.RE
-.\" ***************************************************************************
+.\" ********************************************************************
.SS "The Terminal State"
-The \fBsetupterm\fP routine stores its information about the terminal
-in a \fI\%TERMINAL\fP structure pointed to by the global variable \fBcur_term\fP.
+\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.
+\fB\%setupterm\fP allocates new storage for each set of terminal
+capabilities.
.PP
\fB\%set_curterm\fP sets \fB\%cur_term\fP to
.I \%nterm,
.I \%nterm.
It returns the old value of \fB\%cur_term\fP.
.PP
-\fB\%del_curterm\fP routine frees the space pointed to by
+\fB\%del_curterm\fP frees the space pointed to by
.I \%oterm
and makes it available for further use.
If
and string variables thereafter may refer to invalid memory locations
until another \fB\%setupterm\fP has been called.
.PP
-The \fBrestartterm\fP routine is similar to \fBsetupterm\fP and \fBinitscr\fP,
-except that it is called after restoring memory to a previous state (for
-example, when reloading a game saved as a core image dump).
-\fBrestartterm\fP assumes that the windows and the input and output options
-are the same as when memory was saved,
+\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, \fBrestartterm\fP saves various tty state bits,
-calls \fBsetupterm\fP, and then restores the bits.
-.\" ***************************************************************************
+Accordingly,
+\fB\%restartterm\fP saves various terminal state bits,
+calls \fB\%setupterm\fP,
+and then restores the bits.
+.\" ********************************************************************
.SS "Formatting Output"
-The \fBtparm\fP routine instantiates the string \fIstr\fP with
-parameters \fIpi\fP. A pointer is returned to the result of \fIstr\fP
+\fB\%tparm\fP instantiates the string
+.I str
+with parameters
+.I 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 \fBtparm\fP;
-it is interpreted by \fBtputs\fP.
+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.
rather than
.IR long s.
.PP
-Both \fBtparm\fP and \fBtiparm\fP assume that the application passes
+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:
+Two extensions are provided as alternatives to deal with untrusted data.
.bP
-\fBtiparm_s\fP is an extension which is a safer formatting function
-than \fBtparm\fR or \fBtiparm\fR,
-because it allows the developer to tell the curses
+\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) which will be passed as char* rather than numbers.
+(up to 9)
+passed as
+.I char
+pointers rather than numbers.
.bP
-The extension \fBtiscan_s\fP allows the application
-to inspect a formatting capability to see what the curses library would assume.
-.\" ***************************************************************************
+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
(thirty seconds),
it is capped at that value.
.PP
-The \fBtputs\fP routine interprets time-delay information in the string
-\fIstr\fP and outputs it, executing the delays:
+\fB\%tputs\fP interprets time-delay information in the string
+.I str
+and outputs it,
+executing the delays:
.bP
-The \fIstr\fP parameter must be a terminfo string
-variable or the return value from
-\fBtparm\fP, \fBtiparm\fP, \fBtgetstr\fP, or \fBtgoto\fP.
+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
+which happens to share these function names with the
.I \%term\%info
-interface.
+API.
.bP
-\fIaffcnt\fP 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\fP is a \fI\%putchar\fP-like function 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 \fBtputs\fP processes a time-delay,
-it uses the \fBdelay_output\fP(3X) function,
+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(\fIstr\fB, 1, \%putchar)\fR.
-The output of \fBputp\fP always goes to \fBstdout\fP, rather than
-the \fIfiledes\fP specified in \fBsetupterm\fP.
-.PP
-The \fBvidputs\fP routine displays the string on the terminal in the
-video attribute mode \fIattrs\fP, which is any combination of the
-attributes listed in \fBcurses\fP(3X).
-The characters are passed to
-the \fI\%putchar\fP-like function \fIputc\fP.
-.PP
-The \fBvidattr\fP routine is like the \fBvidputs\fP routine, except
-that it outputs through \fI\%putchar\fP.
+\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
+\fB\%vidputs\fP displays the string on the terminal in the video
+attribute mode
+.I attrs,
+which is any combination of the attributes listed in \fB\%curses\fP(3X).
+The characters are passed to the
+.IR \%putchar -like
+function
+.I putc.
+.PP
+\fB\%vidattr\fP is like \fB\%vidputs\fP,
+except that it outputs through \fI\%putchar\fP(3).
.PP
.B \%vid_attr
and
saying that applications must provide a null pointer for that argument;
but see section \*(``EXTENSIONS\*('' below.
.PP
-The \fBmvcur\fP routine provides low-level cursor motion.
-It takes effect immediately (rather than at the next refresh).
+\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,
-\fBmvcur\fP uses an output file descriptor derived from
-the output stream parameter of \fBnewterm\fP(3X).
+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 \fBputp\fP and \fBmvcur\fP are low-level functions which
-do not use the high-level curses state,
-they are declared in
+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 \fIHISTORY\fP).
-.\" ***************************************************************************
+(see section \*(``HISTORY\*('' below).
+.\" ********************************************************************
.SS "Terminal Capability Functions"
-The \fBtigetflag\fP, \fBtigetnum\fP and \fBtigetstr\fP routines return
-the value of the capability corresponding to the
+\fB\%tigetflag\fP,
+\fB\%tigetnum\fP,
+and \fB\%tigetstr\fP return the value of the capability corresponding to
+the
.I \%term\%info
-\fIcapname\fP passed to them, such as \fBxenl\fP.
-The \fIcapname\fP for each capability is given in the table column entitled
-\fIcapname\fP code in the capabilities section of \fB\%terminfo\fP(5).
+.I 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\fP routine returns
+\fB\%tigetflag\fP returns
.TP
-\fB\-1\fP
-if \fIcapname\fP is not a Boolean capability,
+.B \-1
+if
+.I cap-code
+is not a Boolean capability,
or
.TP
-\fB0\fP
+.B 0
if it is canceled or absent from the terminal description.
.PP
-The \fBtigetnum\fP routine returns
+\fB\%tigetnum\fP returns
.TP
-\fB\-2\fP
-if \fIcapname\fP is not a numeric capability, or
+.B \-2
+if
+.I cap-code
+is not a numeric capability,
+or
.TP
-\fB\-1\fP
+.B \-1
if it is canceled or absent from the terminal description.
.PP
-The \fBtigetstr\fP routine returns
+\fB\%tigetstr\fP returns
.TP
-\fB(char *)\-1\fP
-if \fIcapname\fP is not a string capability,
+.B "(char *)\-1"
+if
+.I cap-code
+is not a string capability,
or
.TP
-\fB0\fP
+.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
+the \fItermcap\fP names (\*(``names\*(''),
+and
.bP
the long \fI\%term\%info\fP names (\*(``fnames\*('')
.PP
\fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP
.fi
.RE
-.\" ***************************************************************************
+.\" ********************************************************************
.SS "Releasing Memory"
-Each successful call to \fBsetupterm\fP allocates memory to hold the terminal
-description.
-As a side-effect, it sets \fBcur_term\fP to point to this memory.
+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
-\fBdel_curterm(cur_term);\fP
+.EX
+del_curterm(cur_term);
+.EE
.PP
the memory will be freed.
.PP
-The formatting functions \fBtparm\fP and \fBtiparm\fP extend the storage
-allocated by \fBsetupterm\fP:
+The formatting functions \fB\%tparm\fP and \fB\%tiparm\fP extend the
+storage allocated by \fB\%setupterm\fP as follows.
.bP
-the \*(``static\*('' terminfo variables [a-z].
-Before \fI\%ncurses\fP 6.3, those were shared by all screens.
-With \fI\%ncurses\fP 6.3, those are allocated per screen.
-See \fB\%terminfo\fP(5) for details.
+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,
-\fI\%ncurses\fP 6.3 caches the result of analyzing terminfo
+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 \fI\%TERMINAL\fP structure.
+That is stored as a binary tree referenced from the
+.I \%TERMINAL
+structure.
.PP
-The higher-level \fBinitscr\fP and \fBnewterm\fP functions use \fBsetupterm\fP.
-Normally they do not free this memory, but it is possible to do that using
-the \fBdelscreen\fP(3X) function.
-.\" ***************************************************************************
+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 defines no failure conditions.
+X/Open Curses defines no failure conditions.
In
.I \%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
+.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
-\fBtparm\fP
-returns a null if the capability would require unexpected parameters,
-e.g., too many, too few, or incorrect types
-(strings where integers are expected, or vice versa).
+.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
-\fBtputs\fP
-returns an error if the string parameter is null.
+.B tputs
+fails if the string parameter is null.
It does not detect I/O errors:
-X/Open Curses states that \fBtputs\fP ignores the return value
-of the output function \fIputc\fP.
-.\" ***************************************************************************
+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
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
.I \%ncurses,
.IR curses ,
4.4BSD
.IR curses ,
-or any other previous curses implementation.
+or any other previous
+.I curses
+implementation.
.PP
.I \%ncurses
allows
.I pair
.RI ( short )
argument.
-.\" ***************************************************************************
+.\" ********************************************************************
.SH PORTABILITY
\fB\%setterm\fP is not described by X/Open and must be considered
non-portable.
\fB\%Bgettmode\fP,
\fB\%Bnocrmode\fP,
\fB\%Bresetterm\fP,
-\fB\%Bsaveterm\fP, and
+\fB\%Bsaveterm\fP,
+and
\fB\%Bsetterm\fP.
.PP
In SVr4,
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.
+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.
.PP
Extended terminal capability names,
as defined by
-.RB \%\*(`` "@TIC@\ \-x" \*('',
+.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
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;
+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,
.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 long).
+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 terminfo capabilities use string parameters
-(e.g., the ones used for programmable function keys).
+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.
a table,
so that it calls \fB\%tparm\fP correctly.
.SS "Special \fITERM\fP treatment"
-If configured to use the terminal-driver,
-e.g., for the MinGW port,
+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 curses uses the
-special value \*(``dumb\*(''.
+SVr4
+.I curses
+uses the special value \*(``dumb\*(''.
.IP
-The difference between the two is that
-the former uses the \fBgn\fP (\fB\%generic_type\fR) terminfo capability,
+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
.I curses
function that is not well specified.
.PP
-X/Open notes that after calling \fBmvcur\fP, the curses state may not match the
-actual terminal state, and that an application should touch and refresh
-the window before resuming normal curses calls.
-Both \fI\%ncurses\fP and System V Release 4 curses implement \fBmvcur\fP
-using the \fISCREEN\fP data allocated in either \fBinitscr\fP or
-\fBnewterm\fP.
-So though it is documented as a terminfo function,
-\fBmvcur\fP is really a curses function which is not well specified.
+X/Open 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
The \-1 tells
.I \%ncurses
that the old location is unknown,
-and that it must use only absolute motion
-(such as \fI\%cursor_address\fP)
-rather than the least costly combination of absolute and relative motion.
-.\" ***************************************************************************
+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
lB lx.
Function Description
_
-fixterm restore tty to \*(``in curses\*('' state
-gettmode establish current tty modes
+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 \fI\%putchar\fP
-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 interpolate parameters into string capability
tputs apply padding information to a string
vidattr like \fBvidputs\fP, but output through \fIputchar\fP
-vidputs write string to terminal, applying specified attributes
+vidputs T{
+write string to terminal, applying specified attributes
+T}
.TE
.PP
The programming manual also mentioned
tgetnum get numeric entry for given \fIid\fP
tgetstr get string entry for given \fIid\fP
tgoto apply parameters to given capability
-tputs write characters via a function parameter, applying padding
+tputs T{
+write characters via a function parameter, applying padding
+T}
.TE
.PP
Early
projects / ncurses.git / blobdiff