path: root/man/curs_terminfo.3x

'\" t
.\"***************************************************************************
.\" Copyright 2018-2024,2025 Thomas E. Dickey                                *
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
.\"                                                                          *
.\" Permission is hereby granted, free of charge, to any person obtaining a  *
.\" copy of this software and associated documentation files (the            *
.\" "Software"), to deal in the Software without restriction, including      *
.\" without limitation the rights to use, copy, modify, merge, publish,      *
.\" distribute, distribute with modifications, sublicense, and/or sell       *
.\" copies of the Software, and to permit persons to whom the Software is    *
.\" furnished to do so, subject to the following conditions:                 *
.\"                                                                          *
.\" The above copyright notice and this permission notice shall be included  *
.\" in all copies or substantial portions of the Software.                   *
.\"                                                                          *
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
.\"                                                                          *
.\" Except as contained in this notice, the name(s) of the above copyright   *
.\" holders shall not be used in advertising or otherwise to promote the     *
.\" sale, use or other dealings in this Software without prior written       *
.\" authorization.                                                           *
.\"***************************************************************************
.\"
.\" $Id: curs_terminfo.3x,v 1.176 2025/11/12 01:06:36 tom Exp $
.TH curs_terminfo 3X 2025-11-11 "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
\fB\%del_curterm\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>
\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 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 lower-level functions of the
.I curses
standard 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.
.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
Call
.B \%setupterm
from your application to have
.I \%term\%info
manage the terminal device;
this action initializes the terminal-dependent variables listed in
\fB\%term_variables\fP(3X).
(A
.I curses
application calling \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X) achieves
the same result.)
Applications can use the terminal capabilities either directly,
by object definitions corresponding to capability names and codes
(see \fB\%term_variables\fP(3X))
or by calling the functions documented here.
.B \%setupterm
initializes the
.I \%term\%info
variables
.B \%lines
and
.B \%columns
as described in \fB\%use_env\fP(3X).
.PP
Pass parameterized string capability values through
.B \%tparm
to instantiate them.
All
.I \%term\%info
strings
(including the output of
.BR \%tparm ")"
should be sent to the terminal device with
.B \%tputs
or
.BR \%putp "."
Call
\fB\%reset_shell_mode\fP(3X) to restore the terminal modes before
exiting.
(A
.I curses
application calling \fB\%endwin\fP(3X) achieves the same result.)
.\" XXX: What should a "pure" terminfo application that wants to link
.\" only with libtinfo, and not libcurses, do?
.PP
Programs that use cursor addressing should emit certain capabilities
at specific times.
Specifically,
output
.bP
.B \%enter_ca_mode
upon startup,
and
.bP
.B \%exit_ca_mode
before exiting.
.PP
Programs that execute shell subprocesses should
.bP
call \fB\%reset_shell_mode\fP(3X) and output
.B \%exit_ca_mode
before the shell is called,
and
.bP
output
.B \%enter_ca_mode
and call \fB\%reset_prog_mode\fP(3X) after returning from the shell.
.\" XXX: What should a "pure" terminfo application that wants to link
.\" only with libtinfo, and not libcurses, do?
.PP
\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
.B \%setupterm
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
.B ERR
is returned,
examine
.IR errret "."
.RS
.TP 5
.B 1
means that the terminal is a hard-copy type
(lacks destructive backspace),
and cannot be used for
.I curses
applications.
The library determines this fact by checking the terminal type's
.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
.I curses
applications to run.
.IP
.B \%setupterm
determines if the entry is a generic type by checking the
.B \%generic_type
.RB ( gn )
capability.
.TP 5
.B \-1
means that the
.I \%term\%info
database could not be found.
.RE
.IP
If
.I errret
is null,
.B \%setupterm
reports an error message upon finding an error and exits.
Thus,
the simplest call is:
.RS
.IP
.EX
setupterm((char *) NULL, 1, (int *) NULL);
.EE
.RE
.IP
which uses all the defaults and sends the output to
.IR stdout "."
.RE
.\" ********************************************************************
.SS "The Terminal State"
.B \%setupterm
stores its information about the terminal in a
.I \%TERMINAL
structure pointed to by the global variable
.BR \%cur_term "."
If it detects an error,
or decides that the terminal is unsuitable
(hardcopy or generic),
it discards this information,
making it unavailable to applications.
.PP
If
.B \%setupterm
is called repeatedly for the same terminal type,
it reuses the information.
It maintains only one copy of a given type's capabilities in memory.
If called for different types,
.B \%setupterm
allocates new storage for each set of terminal capabilities.
.PP
.B \%set_curterm
sets
.B \%cur_term
to
.IR \%nterm ","
making all of the
.I \%term\%info
Boolean,
numeric,
and string capabilities use the values from
.IR \%nterm "."
It returns the old value of
.BR \%cur_term "."
.PP
.B \%del_curterm
releases the memory pointed to by
.IR \%oterm "."
If
.I \%oterm
is
the same as
.BR \%cur_term ","
references to any of the
.I \%term\%info
Boolean,
numeric,
and string capabilities thereafter may refer to invalid memory locations
until
.B \%setupterm
is called again.
.PP
.B \%restartterm
is similar to
.BR \%setupterm ","
but is intended for use after restoring program memory
to a previous state
(for example,
when reloading an application that has been suspended from one terminal
session and restored in another).
.B \%restartterm
assumes that the display dimensions
and the input and output options are the same as when memory was saved,
but the terminal type and line speed may differ.
Accordingly,
.B \%restartterm
saves relevant terminal state,
calls
.BR \%setupterm ","
then restores that state.
.\" ********************************************************************
.SS "Formatting Output"
\fB\%tparm\fP instantiates the string
.I str
with parameters
.IR pi "."
It returns a pointer to a character string representing
.I str
with the parameters applied to \*(``%\*('' expressions within.
.\" XXX: Whose responsibility is it to free that string?
Application developers should keep in mind some 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
\fB\%tiparm\fP is a newer form of \fB\%tparm\fP that uses
.I \%stdarg.h
rather than a fixed-length parameter list.
Its numeric parameters are
.IR int s
rather than
.IR long "s."
.PP
.B \%tparm
and
.B \%tiparm
assume that the application
passes parameters consistent with the terminal description.
.I \%ncurses
provides two extensions as alternatives to deal with untrusted data.
.bP
The
.B \%tiparm_s
extension is a safer formatting function than
.B \%tparm
or
.BR \%tiparm ","
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
.I mask
parameter has one bit set for each of the parameters
(up to 9)
passed as
.I char
pointers rather than numbers.
.bP
The extension
.B \%tiscan_s
allows the application
to inspect a formatting capability to see what the
.I curses
library would assume.
.\" ********************************************************************
.SS "Output Functions"
String capabilities can contain
.IR padding ","
a time delay
(accommodating performance limitations of hardware terminals)
expressed as
.BI $< n >\c
,
where
.I n
is a nonnegative integral count of milliseconds.
If
.I n
exceeds 30,000
(thirty seconds),
.I \%ncurses
caps it at that value.
.PP
.B \%tputs
interprets time delays in the string
.I str
and acts upon them.
.bP
The
.I str
parameter must be a
.I \%term\%info
string capability or the return value of
.B \%tparm
or
.BR \%tiparm "."
.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.
.PP
.B \%tputs
processes each time delay with the \fB\%delay_output\fP(3X) function,
routing any resulting padding characters through this function.
.PP
\fB\%putp\fR calls
.RB \%\*(`` tputs(\c
.IB str ", 1, putchar)\c"
\*(''.
The output of \fB\%putp\fP always goes to
.IR 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
.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
\fB\%vidattr\fP is like \fB\%vidputs\fP,
except that it outputs through \fI\%putchar\fP(3).
.PP
.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
.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
While
.B \%putp
is a lower-level function
that does not use higher-level
.I curses
state,
.I \%ncurses
declares it in
.I \%curses.h
because System\ V did so
(see section \*(``HISTORY\*('' below).
.\" ********************************************************************
.SS "Terminal Capability Functions"
.BR \%tigetflag ","
.BR \%tigetnum ","
and
.B \%tigetstr
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 of that name
in the \*(``Capabilities\*('' section of \fB\%terminfo\fP(5).
.PP
These functions return special values to denote errors.
.PP
.B \%tigetflag
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
.B \%tigetnum
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
.B \%tigetstr
returns
.TP
.B "(char *)\-1"
if
.I cap-code
is not a string capability,
or
.TP
.B NULL
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 standard
.I \%term\%info
capability name.
.PP
.RS
.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
.RS
.EX
del_curterm(cur_term);
.EE
.RE
the memory will be freed.
.PP
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
Functions that return integers return
.B ERR
upon failure and
.B OK
upon success.
.PP
In
.IR \%ncurses ","
.TP 5
.B del_curterm
fails if its terminal parameter is null.
.TP 5
.B putp
calls \fB\%tputs\fP,
returning the same error codes.
.TP 5
.B restartterm
fails if the associated call to \fB\%setupterm\fP returns
.BR ERR "."
.TP 5
.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
.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 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 originated in
.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
Except for
.IR \%setterm ","
X/Open Curses Issue\ 4 describes these functions.
It specifies no error conditions for them.
.PP
SVr4 describes a successful return value
except where \*(``otherwise noted\*(''
as
\*(``an integer value other than
.IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 539
.SS "Header Files"
On legacy
.I curses
systems,
include
.I \%curses.h
and
.I \%term.h
in that order
to make visible the definitions of the string arrays
storing the capability names and codes.
.SS "Compatibility Macros"
.I \%ncurses
implements a few macros for early System\ V
.I curses
compatibility
(see section \*(``HISTORY\*('' below).
They include
.IR \%crmode ","
.IR \%fixterm ","
.IR \%gettmode ","
.IR \%nocrmode ","
.IR \%resetterm ","
.IR \%saveterm ","
and
.IR \%setterm "."
.PP
In SVr4,
these are found in
.IR \%curses.h ","
but except for
.IR \%setterm ","
are likewise macros.
The one function,
.IR \%setterm ","
is mentioned in the manual page.
It further notes that
.I \%setterm
was replaced by
.IR \%setupterm ","
stating that the call
.RS
.EX
.RI setupterm( term ", 1, (int *)0)"
.EE
.RE
provides the same functionality as
.RS
.EX
.RI setterm( term )
.EE
.RE
and discouraging the latter for new programs.
.SS "Legacy Data"
.I \%setupterm
copies the terminal name to the array
.IR \%ttytype "."
This behavior is not specified by X/Open Curses,
but is assumed by some applications.
.PP
Other implementations 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
.I \%ncurses
assumed that the file descriptor passed to
.I \%setupterm
from
.I \%initscr
or
.I \%newterm
used buffered I/O,
and wrote to the corresponding
.I stdio
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
.IR SIGTSTP "."
.PP
.I \%ncurses
.RI 6. x
uses output buffers managed directly by
.IR \%ncurses "."
The lower-level functions described here
that write to the terminal device
do so via the standard output stream;
they thus are not signal-safe.
The higher-level functions in
.I \%ncurses
employ alternate versions of these functions
using a 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 function parameters
that are passed by value
(and therefore copied),
and in most cases overlooking parameters
that normally would benefit from
.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 C language feature.
.IP
As an extension,
.I \%ncurses
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
.I \%tparm
with a fixed number of parameters,
rather than a variable argument list.
.IP
.I \%ncurses
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
.I \%tiparm
function in mid-2009.
.IP
While
.I \%tiparm
is always provided in
.IR \%ncurses ","
the older form is available only as a build-time configuration option.
If not specially configured,
.I \%tparm
is the same as
.IR \%tiparm "."
.PP
Both forms of
.I \%tparm
have drawbacks.
.bP
Most calls to
.I \%tparm
require 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 memory as a pointer.
That approach dates to the mid-1980s,
before C was standardized.
Since ANSI\ C (1989),
C language standards do not require a pointer to fit in a
.IR long ")."
.bP
Providing the right number of parameters for a variadic function
such as
.I \%tiparm
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
.I \%ncurses
library checks usage of these capabilities,
and returns
.I ERR
if the capability mishandles string parameters.
But it cannot check if a calling program provides strings in the right
places for the
.I \%tparm
calls.
.IP
.IR \%ncurses 's
\fB\%@TPUT@\fR(1) checks its use of these capabilities with a table,
so that it calls
.I \%tparm
correctly.
.SS "Special \fITERM\fP treatment"
If
.I \%ncurses
is configured to use a terminal driver
that does not employ the POSIX
.I \%termios
API,
as with the MinGW port,
.bP
.I \%setupterm
interprets a missing or empty
.I TERM
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
.I \%setupterm
allows explicit use of the Microsoft Windows console driver by checking
whether the
.I TERM
environment variable has the value \*(``#win32con\*(''
or an abbreviation of that string.
.SS "Other Portability Issues"
In SVr4,
.I \%set_curterm
returns an
.IR int ","
.I OK
or
.IR ERR "."
We have chosen to implement the X/Open Curses semantics.
.PP
In SVr4,
the third argument of
.I \%tputs
has the type
.RB \*(`` "int (*)(char)" \*(''.
.PP
At least one implementation of X/Open Curses
(Solaris
.IR \%xcurses ")"
returns a value other than
.I OK
or
.I ERR
from
.IR \%tputs "."
It instead returns the length of the string,
and does no error checking.
.PP
Very old versions of AIX
.\" Can we be more specific?  Like, AIX 4.3.3 and earlier? --GBR
.I curses
required inclusion of
.I \%curses.h
before
.IR \%term.h .
.\" ********************************************************************
.SH HISTORY
SVr2 (1984) introduced the
.I \%term\%info
feature.
Its programming manual mentioned the following low-level functions.
.PP
.TS
Lb Lb
Li Lw(47n)x.
Function	Description
_
fixterm	restore terminal to \*(``in \fIcurses\fP\*('' state
gettmode	establish current terminal modes
mvcur	low level cursor motion
putp	use \fItputs\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 \fIvidputs\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
Li Lw(48n)x.
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
.IR \%setupterm "."
.PP
SVr3 (1987) extended
.I \%term\%info
by adding functions to retrieve capability values
(like the
.I termcap
interface),
and reusing
.I \%tgoto
and
.IR \%tputs "."
.PP
.ne 4v
.TS
Lb Lb
LI 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
Li Lix.
Function	Replaced by
_
crmode	cbreak
fixterm	reset_prog_mode
gettmode	\fRn/a\fP
nocrmode	nocbreak
resetterm	reset_shell_mode
saveterm	def_prog_mode
setterm	setupterm
.TE
.PP
SVr3 kept the
.IR \%mvcur ","
.IR \%vidattr ","
and
.I \%vidputs
functions,
along with
.IR \%putp ","
.IR \%tparm ","
and
.IR \%tputs "."
The latter were needed to support padding,
and to handle capabilities accessed by functions such as
.I \%vidattr
(which used more than the two parameters supported by
.IR \%tgoto ")."
.PP
SVr3 introduced the functions for switching between terminal
descriptions;
for example,
.IR \%set_curterm "."
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
.I \%boolnames
were mentioned in the programming manual at this point,
though the variables had been provided in SVr2.
.PP
SVr4 (1989) added the
.I \%vid_attr
and
.I \%vid_puts
functions.
.PP
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
\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)