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
TERMINAL *oterm ); int putp(
const char *str ); int restartterm(
int *errret ); TERMINAL *set_curterm(
TERMINAL *nterm ); int setupterm(
int *errret ); int tigetflag(
char *capname ); int tigetnum(
char *capname ); char *tigetstr(
char *capname ); char *tparm(
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 (*putc)(int) ); include <curses.h>
int newcol ); int vid_attr(
void *opts ); int vidattr(
chtype attrs ); int vid_puts(
int (* putc)(int) ); int vidputs(
int (*putc)(int) );
Curses Library (libcurses)
Interfaces documented on this reference page conform to
industry standards as follows:
del_curterm, mvcur, putp, restartterm, set_curterm,
setupterm, tigetflag, 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.
These low-level routines must be called by programs that
have to deal directly with the terminfo database to handle
certain terminal capabilities, such as programming function
keys. For all other functionality, higher level
Curses routines are more suitable and their use is recommended.
Initially, applications call setupterm. Note that
setupterm is automatically called by initscr and newterm.
The setupterm routine defines the set of terminal-dependent
variables (listed in terminfo(4)). The terminfo variables
lines and columns are initialized by setupterm as
follows. If use_env(FALSE) has been called, the values for
lines and columns 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 window,
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 instantiate 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_kernel(3)). Applications that use cursor
addressing should output enter_ca_mode upon startup and
should output exit_ca_mode before exiting. 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 environment 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
message 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 follows: 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 values 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 terminfo boolean,
numeric, and string variables may refer to invalid memory
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 variable 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.
The header file <curses.h> automatically includes the
header file <stdio.h>.
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.
Functions: curs_initscr(3), curs_kernel(3), curs_termcap(3), putc(3)
[ Back ]