curs_terminfo(3)curs_terminfo(3)NAME
curs_terminfo, del_curterm, mvcur, putp, restartterm, set_curterm,
setupterm, tigetflag, tigetnum, tigetstr, tparm, tputs, vid_attr,
vid_puts, vidattr, vidputs - Curses interfaces to the terminfo database
SYNOPSIS
#include <term.h>
int del_curterm(
TERMINAL *oterm ); int putp(
const char *str ); int restartterm(
char *term,
int fildes,
int *errret ); TERMINAL *set_curterm(
TERMINAL *nterm ); int setupterm(
char *term,
int fildes,
int *errret ); int tigetflag(
char *capname ); int tigetnum(
char *capname ); char *tigetstr(
char *capname ); char *tparm(
char *str,
long int p1,
long int p2,
long int p3,
long int p4,
long int p5,
long int p6,
long int p7,
long int p8,
long int p9 ); int tputs(
const char *str,
int affcnt,
int (*putc)(int) ); include <curses.h>
int mvcur(
int oldrow,
int oldcol,
int newrow,
int newcol ); int vid_attr(
attr_t attr,
short color_pair,
void *opts ); int vidattr(
chtype attrs ); int vid_puts(
attr_t attr,
short color_pair,
void *opts,
int (* putc)(int) ); int vidputs(
chtype attrs,
int (*putc)(int) );
LIBRARY
Curses Library (libcurses)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
del_curterm, mvcur, putp, restartterm, set_curterm, setupterm, tiget‐
flag, tigetnum, tigetstr, tparm, tputs, vid_attr, vid_puts, vidattr,
vidputs: XCURSES4.2
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
DESCRIPTION
These low-level routines must be called by programs that have to deal
directly with the terminfo database to handle certain terminal capabil‐
ities, such as programming function keys. For all other functionality,
higher level Curses routines are more suitable and their use is recom‐
mended.
Initially, applications call setupterm. Note that setupterm is automat‐
ically called by initscr and newterm. The setupterm routine defines the
set of terminal-dependent variables (listed in terminfo(4)). The ter‐
minfo variables lines and columns are initialized by setupterm as fol‐
lows. If use_env(FALSE) has been called, the values for lines and col‐
umns as specified in terminfo are used. Otherwise, if the environment
variables LINES and COLUMNS exist, their values are used. If these
environment variables do not exist and the program is running in a win‐
dow, the current window size is used. Otherwise, if the environment
variables do not exist, the values for lines and columns as specified
in the terminfo database are used.
Applications should include the header files <curses.h> and <term.h>
(in that order) to get the definitions for these strings, numbers, and
flags. Parameterized strings should be passed through tparm to instan‐
tiate them. Applications should print terminfo strings (including the
output of tparm) by using tputs or putp. Applications call
reset_shell_mode to restore the tty modes before exiting (see curs_ker‐
nel(3)). Applications that use cursor addressing should output
enter_ca_mode upon startup and should output exit_ca_mode before exit‐
ing. Applications that use shell escape sequences should call
reset_shell_mode and output exit_ca_mode before the shell is called and
should output enter_ca_mode and call reset_prog_mode after returning
from the shell.
The setupterm routine reads in the terminfo database, initializing the
terminfo structures, but does not set up the output virtualization
structures used by Curses. The routine uses the character string term
for the terminal type; if term is null, the routine uses the environ‐
ment variable TERM. All output is to the fildes file descriptor, which
is initialized for output. If errret is not null, then setupterm
returns OK or ERR and stores a status value in the integer pointed to
by errret. A status of 1 in errret is normal, 0 (zero) means that the
terminal could not be found, and -1 means that the terminfo database
could not be found. If errret is null, setupterm prints an error mes‐
sage on finding an error and exits. Thus, the simplest call for this
routine is to use all the defaults and send output to stdout, as fol‐
lows: setupterm((char *), 1, (int *));
The set_curterm routine sets the variable cur_term to nterm and makes
all of the terminfo boolean, numeric, and string variables use the val‐
ues from nterm.
The del_curterm routine frees the space pointed to by oterm and makes
it available for further use. Following a call to del_curterm, if
oterm is the same as cur_term, program references to any of the ter‐
minfo boolean, numeric, and string variables may refer to invalid mem‐
ory locations until the application calls setupterm.
The restartterm routine is similar to setupterm and initscr, except
that restartterm is called after restoring memory to a previous state.
This routine assumes that the windows and the input and output flags
are the same as when memory was saved, but that the terminal type and
baud rate may be different.
The tparm routine instantiates the string str with the pn parameters.
The routine returns a pointer to the result of applying the parameters
to str.
The tputs routine applies padding information to the string str and
outputs the result. The str parameter must be a terminfo string vari‐
able or the return value from tparm, tgetstr, or tgoto. The affcnt
parameter is the number of lines affected, or 1 if not applicable.
The putp routine executes the call tputs(str, 1, putchar). Note that
the output of putp always goes to stdout, not to the fildes specified
by the setupterm routine.
The vidputs routine displays the string on the terminal in the video
attribute mode attrs, which is any combination of the attributes listed
in the curses(3) reference page. The characters in the string are
passed to the putc routine. which is similar to putchar, except that
characters are passed one at a time.
The vidattr routine is like the vidputs routine, except that it calls
putchar rather than putc to create output.
The vid_attr and vid_puts routines correspond to vidattr and vidputs,
respectively, but take a set of arguments, one of type attr_t for the
attributes and one of short for the color_pair number. The vid_attr and
vid_puts routines therefore support the attribute constants with the
WA_ prefix. The opts argument is reserved for future use. Currently,
applications must provide a null pointer as opts.
The mvcur routine provides low-level cursor motion.
The tigetflag, tigetnum, and tigetstr routines return the value of the
terminfo capability (for example, xenl) that corresponds to capname.
The tigetflag routine returns the value -1 if capname is not a Boolean
capability.
The tigetnum routine returns the value -2 if capname is not a numeric
capability.
The tigetstr routine returns the value (char *)-1 if capname is not a
string capability.
Valid values for capname are specified in the table column entitled
“capname Code” in the capabilities section of the terminfo(4) reference
page.
NOTES
The header file <curses.h> automatically includes the header file
<stdio.h>.
RETURN VALUES
Returns values from tigetflag, tigetnum, and tigetstr are discussed in
the DESCRIPTION section.
All other routines that return an integer return the integer ERR upon
failure and OK upon successful completion.
Routines that return pointers always return NULL on error.
SEE ALSO
Functions: curs_initscr(3), curs_kernel(3), curs_termcap(3), putc(3)
Files: terminfo(4)
Others: standards(5)curs_terminfo(3)