These low-level routines must be called by programs that
- have to deal directly with the terminfo database to handle
+ have to deal directly with the terminfo database to handle
certain terminal capabilities, such as programming func-
- tion keys. For all other functionality, curses routines
+ tion keys. For all other functionality, curses routines
are more suitable and their use is recommended.
- Initially, setupterm should be called. Note that
- setupterm is automatically called by initscr and newterm.
+ Initially, setupterm should be called. Note that se-
+ tupterm is automatically called by initscr and newterm.
This defines the set of terminal-dependent variables
- [listed in terminfo(5)]. The terminfo variables lines and
- columns are initialized by setupterm as follows: If
- use_env(FALSE) has been called, values for lines and
- columns specified in terminfo are used. Otherwise, if the
- environment variables LINES and COLUMNS exist, their val-
+ [listed in terminfo(5)]. The terminfo variables lines and
+ columns are initialized by setupterm as follows: If
+ use_env(FALSE) has been called, values for lines and
+ columns specified in terminfo are used. Otherwise, if the
+ environment variables LINES and COLUMNS exist, their val-
ues 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 specified in
- the terminfo database are used.
+ not exist, the values for lines and columns specified in
+ the terminfo database are used.
- The header files curses.h and term.h should be included
+ The header files curses.h and term.h should be included
(in this order) to get the definitions for these strings,
numbers, and flags. Parameterized strings should be
- passed through tparm to instantiate them. All terminfo
- strings [including the output of tparm] should be printed
- with tputs or putp. Call the reset_shell_mode to restore
- the tty modes before exiting [see curs_kernel(3x)].
- Programs which use cursor addressing should output
- enter_ca_mode upon startup and should output exit_ca_mode
+ passed through tparm to instantiate them. All terminfo
+ strings [including the output of tparm] should be printed
+ with tputs or putp. Call the reset_shell_mode to restore
+ the tty modes before exiting [see curs_kernel(3x)]. Pro-
+ grams which use cursor addressing should output en-
+ ter_ca_mode upon startup and should output exit_ca_mode
before exiting. Programs desiring shell escapes 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, ini-
- tializing the terminfo structures, but does not set up the
- output virtualization structures used by curses. The ter-
- minal type is the character string term; if term is null,
- the environment variable TERM is used. All output is to
- file descriptor fildes 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 return value of OK combined with status of 1 in
- errret is normal. If ERR is returned, examine errret:
-
- 1 means that the terminal is hardcopy, cannot be
+ reset_shell_mode and output exit_ca_mode before the shell
+ is called and should output enter_ca_mode and call re-
+ set_prog_mode after returning from the shell.
+
+ The setupterm routine reads in the terminfo database, ini-
+ tializing the terminfo structures, but does not set up the
+ output virtualization structures used by curses. The ter-
+ minal type is the character string term; if term is null,
+ the environment variable TERM is used. All output is to
+ file descriptor fildes 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 er-
+ rret. A return value of OK combined with status of 1 in
+ errret is normal. If ERR is returned, examine errret:
+
+ 1 means that the terminal is hardcopy, cannot be
used for curses applications.
- 0 means that the terminal could not be found, or
+ 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.
- -1 means that the terminfo database could not be
+ -1 means that the terminfo database could not be
found.
- If errret is null, setupterm prints an error message upon
+ If errret is null, setupterm prints an error message upon
finding an error and exits. Thus, the simplest call is:
- setupterm((char*)0,1,(int*)0);,
+ setupterm((char*)0,1,(int*)0);,
- which uses all the defaults and sends the output to std-
- out.
+ which uses all the defaults and sends the output to std-
+ out.
- The setterm routine is being replaced by setupterm. The
+ The setterm routine is being replaced by setupterm. The
call:
- setupterm(term,1,(int*)0)
+ setupterm(term,1,(int*)0)
- provides the same functionality as setterm(term). The
- setterm routine is included here for BSD compatibility,
+ provides the same functionality as setterm(term). The
+ setterm routine is included here for BSD compatibility,
and is not recommended for new programs.
- 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. It returns
- the old value of cur_term.
+ 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. It returns
+ the old value of cur_term.
- The del_curterm routine frees the space pointed to by
- oterm and makes it available for further use. If oterm is
- the same as cur_term, references to any of the terminfo
- boolean, numeric, and string variables thereafter may
- refer to invalid memory locations until another setupterm
+ The del_curterm routine frees the space pointed to by
+ oterm and makes it available for further use. If oterm is
+ the same as cur_term, references to any of the terminfo
+ boolean, numeric, and string variables thereafter may re-
+ fer to invalid memory locations until another setupterm
has been called.
- The restartterm routine is similar to setupterm and
- initscr, except that it is called after restoring memory
+ The restartterm routine is similar to setupterm and
+ initscr, 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 mem-
@@ -130,162 +173,148 @@
different. Accordingly, it saves various tty state bits,
does a setupterm, and then restores the bits.
- The tparm routine instantiates the string str with parame-
- ters pi. A pointer is returned to the result of str with
+ The tparm routine instantiates the string str with parame-
+ ters pi. A pointer is returned to the result of str with
the parameters applied.
- The tputs routine applies padding information to the
- string str and outputs it. The str must be a terminfo
- string variable or the return value from tparm, tgetstr,
- or tgoto. affcnt is the number of lines affected, or 1 if
- not applicable. putc is a putchar-like routine to which
+ The tputs routine applies padding information to the
+ string str and outputs it. The str must be a terminfo
+ string variable or the return value from tparm, tgetstr,
+ or tgoto. affcnt is the number of lines affected, or 1 if
+ not applicable. putc is a putchar-like routine to which
the characters are passed, one at a time.
- The putp routine calls tputs(str,1,putchar). Note that
- the output of putp always goes to stdout, not to the
- fildes specified in setupterm.
-
- The vidputs routine displays the string on the terminal in
- the video attribute mode attrs, which is any combination
- of the attributes listed in curses(3x). The characters
- are passed to the putchar-like routine putc.
-
- The vidattr routine is like the vidputs routine, except
- that it outputs through putchar.
-
- The mvcur routine provides low-level cursor motion. It
- takes effect immediately (rather than at the next
- refresh).
-
- The tigetflag, tigetnum and tigetstr routines return the
- value of the capability corresponding to the terminfocap-
- name passed to them, such as xenl.
-
- The tigetflag routine returns the value -1 if capname is
- not a boolean capability, or 0 if it is canceled or absent
+ The putp routine calls tputs(str,1,putchar). Note that
+ the output of putp always goes to stdout, not to the
+ fildes specified in setupterm.
+
+ The vidputs routine displays the string on the terminal in
+ the video attribute mode attrs, which is any combination
+ of the attributes listed in curses(3x). The characters
+ are passed to the putchar-like routine putc.
+
+ The vidattr routine is like the vidputs routine, except
+ that it outputs through putchar.
+
+ The vid_attr and vid_puts routines correspond to vidattr
+ and 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 vid_attr and vid_puts routines
+ are designed to use the attribute constants with the WA_
+ prefix. The opts argument is reserved for future use.
+ Currently, applications must provide a null pointer for
+ that argument.
+
+ The mvcur routine provides low-level cursor motion. It
+ takes effect immediately (rather than at the next re-
+ fresh).
+
+ The tigetflag, tigetnum and tigetstr routines return the
+ value of the capability corresponding to the terminfocap-
+ name passed to them, such as xenl.
+
+ The tigetflag routine returns the value -1 if capname is
+ not a boolean capability, or 0 if it is canceled or absent
from the terminal description.
- The tigetnum routine returns the value -2 if capname is
- not a numeric capability, or -1 if it is canceled or
- absent from the terminal description.
+ The tigetnum routine returns the value -2 if capname is
+ not a numeric capability, or -1 if it is canceled or ab-
+ sent from the terminal description.
- The tigetstr routine returns the value (char*)-1 if
- capname is not a string capability, or 0 if it is canceled
- or absent from the terminal description.
+ The tigetstr routine returns the value (char*)-1 if cap-
+ name is not a string capability, or 0 if it is canceled or
+ absent from the terminal description.
- The capname for each capability is given in the table col-
- umn entitled capname code in the capabilities section of
- terminfo(5).
+ The capname for each capability is given in the table col-
+ umn entitled capname code in the capabilities section of
+ terminfo(5).
- char*boolnames, *boolcodes, *boolfnames
+ char*boolnames, *boolcodes, *boolfnames
- char*numnames, *numcodes, *numfnames
+ char*numnames, *numcodes, *numfnames
- char*strnames, *strcodes, *strfnames
+ char*strnames, *strcodes, *strfnames
- These null-terminated arrays contain the capnames, the
- termcap codes, and the full C names, for each of the ter-
- minfo variables.
+ These null-terminated arrays contain the capnames, the
+ termcap codes, and the full C names, for each of the ter-
+ minfo variables.
RETURN VALUE
- Routines that return an integer return ERR upon failure
- and OK (SVr4 only specifies "an integer value other than
- ERR") upon successful completion, unless otherwise noted
+ Routines that return an integer return ERR upon failure
+ and OK (SVr4 only specifies "an integer value other than
+ ERR") upon successful completion, unless otherwise noted
in the preceding routine descriptions.
- Routines that return pointers always return NULL on error.
+ Routines that return pointers always return NULL on error.
+
+ X/Open defines no error conditions. In this implementa-
+ tion
+
+ del_curterm
+ returns an error if its terminal parameter is
+ null.
+
+ restartterm
+ returns an error if the associated call to se-
+ tupterm returns an error.
+
+ setupterm
+ returns an error if it cannot allocate enough
+ memory, or create the initial windows (stdscr,
+ curscr, newscr). Other error conditions are
+ documented above.
NOTES
- The setupterm routine should be used in place of setterm.
+ The setupterm routine should be used in place of setterm.
It may be useful when you want to test for terminal capa-
bilities without committing to the allocation of storage
- involved in initscr.
+ involved in initscr.
- Note that vidattr and vidputs may be macros.
+ Note that vidattr and vidputs may be macros.
PORTABILITY
- The function setterm is not described in the XSI Curses
+ The function setterm is not described in the XSI Curses
standard and must be considered non-portable. All other
functions are as described in the XSI curses standard.
- In System V Release 4, set_curterm has an int return type
- and returns OK or ERR. We have chosen to implement the
+ In System V Release 4, set_curterm has an int return type
+ and returns OK or ERR. We have chosen to implement the
XSI Curses semantics.
- In System V Release 4, the third argument of tputs has the
- type int(*putc)(char).
-
- The XSI Curses standard prototypes tparm with a fixed num-
- ber of parameters, rather than a variable argument list.
-
- XSI notes that after calling mvcur, the curses state may
- not match the actual terminal state, and that an applica-
- tion should touch and refresh the window before resuming
- normal curses calls. Both ncurses and System V Release 4
- curses implement mvcur using the SCREEN data allocated in
- either initscr or newterm. So though it is documented as
- a terminfo function, mvcur is really a curses function
+ In System V Release 4, the third argument of tputs has the
+ type int(*putc)(char).
+
+ The XSI Curses standard prototypes tparm with a fixed num-
+ ber of parameters, rather than a variable argument list.
+ This implementation uses a variable argument list.
+ Portable applications should provide 9 parameters after
+ the format; zeroes are fine for this purpose.
+
+ XSI notes that after calling mvcur, the curses state may
+ not match the actual terminal state, and that an applica-
+ tion should touch and refresh the window before resuming
+ normal curses calls. Both ncurses and System V Release 4
+ curses implement mvcur using the SCREEN data allocated in
+ either initscr or newterm. So though it is documented as
+ a terminfo function, mvcur is really a curses function
which is not well specified.