These low-level routines must be called by programs that have to deal
- directly with the terminfo database to handle certain terminal capabil-
+ directly with the terminfo database to handle certain terminal capabil-
ities, such as programming function keys. For all other functionality,
- curses routines are more suitable and their use is recommended.
+ curses routines are more suitable and their use is recommended.
None of these functions use (or are aware of) multibyte character
strings such as UTF-8:
- o capability names use the POSIX portable character set
+ o capability names use the POSIX portable character set
- o capability string values have no associated encoding; they are
+ o capability string values have no associated encoding; they are
strings of 8-bit characters.
- Initially, setupterm should be called. The high-level curses functions
- initscr and newterm call setupterm to initialize the low-level set of
- terminal-dependent variables [listed in terminfo(5)].
+ Initially, setupterm should be called. The high-level curses functions
+ initscr and newterm call setupterm to initialize the low-level set of
+ terminal-dependent variables [listed in terminfo(5)].
Applications can use the terminal capabilities either directly (via
- header definitions), or by special functions. The header files curs-
- es.h and term.h should be included (in this order) to get the defini-
+ header definitions), or by special functions. The header files curs-
+ es.h and term.h should be included (in this order) to get the defini-
tions for these strings, numbers, and flags.
- The terminfo variables lines and columns are initialized by setupterm
+ The terminfo variables lines and columns are initialized by setupterm
as follows:
- o If use_env(FALSE) has been called, values for lines and columns
- specified in terminfo are used.
+ o If use_env(FALSE) has been called, values for lines and columns
+ specified in terminfo are used.
- o Otherwise, if the environment variables LINES and COLUMNS exist,
+ o 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 specified in the terminfo database are
+ values for lines and columns specified in the terminfo database are
used.
- 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 reset_shell_mode to restore the tty
- modes before exiting [see curs_kernel(3X)].
+ 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 reset_shell_mode to restore the tty
+ modes before exiting [see curs_kernel(3x)].
Programs which use cursor addressing should
- o output enter_ca_mode upon startup and
+ o output enter_ca_mode upon startup and
- o output exit_ca_mode before exiting.
+ o output exit_ca_mode before exiting.
Programs which execute shell subprocesses should
- o call reset_shell_mode and output exit_ca_mode before the shell is
+ o call reset_shell_mode and output exit_ca_mode before the shell is
called and
- o output enter_ca_mode and call reset_prog_mode after returning from
+ o 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. These are its parameters:
+ The setupterm routine reads in the terminfo database, initializing the
+ terminfo structures, but does not set up the output virtualization
+ structures used by curses. These are its parameters:
- term is the terminal type, a character string. If term is null, the
- environment variable TERM is used.
+ term is the terminal type, a character string. If term is null, the
+ environment variable TERM is used.
- filedes
+ filedes
is the file descriptor used for all output.
- errret
+ errret
points to an optional location where an error status can be re-
- turned to the caller. 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 sta-
- tus of 1 in errret is normal.
+ turned to the caller. 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 sta-
+ tus of 1 in errret is normal.
- If ERR is returned, examine errret:
+ If ERR is returned, examine errret:
- 1 means that the terminal is hardcopy, cannot be used for
+ 1 means that the terminal is hardcopy, cannot be used for
curses applications.
- setupterm determines if the entry is a hardcopy type by
- checking the hc (hardcopy) capability.
+ setupterm determines if the entry is a hardcopy type by
+ checking the hc (hardcopy) capability.
- 0 means that the terminal could not be found, or that it is
+ 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.
- setupterm determines if the entry is a generic type by
- checking the gn (generic) capability.
+ setupterm determines if the entry is a generic type by
+ checking the gn (generic) capability.
- -1 means that the terminfo database could not be found.
+ -1 means that the terminfo database could not be found.
- If errret is null, setupterm prints an error message upon find-
+ If errret is null, setupterm prints an error message upon find-
ing 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 stdout.
+ which uses all the defaults and sends the output to stdout.
- The setupterm routine stores its information about the terminal in a
- TERMINAL structure pointed to by the global variable cur_term. If it
+ The setupterm routine stores its information about the terminal in a
+ TERMINAL structure pointed to by the global variable cur_term. If it
detects an error, or decides that the terminal is unsuitable (hardcopy
or generic), it discards this information, making it not available to
applications.
- If setupterm is called repeatedly for the same terminal type, it will
+ If setupterm is called repeatedly for the same terminal type, it will
reuse the information. It maintains only one copy of a given termi-
nal's capabilities in memory. If it is called for different terminal
- types, setupterm allocates new storage for each set of terminal capa-
+ types, setupterm allocates new storage for each set of terminal capa-
bilities.
- The set_curterm routine sets 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 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, refer-
- ences to any of the terminfo boolean, numeric, and string variables
- thereafter may refer to invalid memory locations until another se-
- tupterm has been called.
+ 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, refer-
+ ences to any of the terminfo boolean, numeric, and string variables
+ thereafter may refer to invalid memory locations until another se-
+ tupterm has been called.
- The restartterm routine is similar to setupterm and initscr, except
+ The restartterm routine is similar to setupterm and initscr, except
that it is called after restoring memory to a previous state (for exam-
- ple, when reloading a game saved as a core image dump). restartterm
+ ple, when reloading a game saved as a core image dump). restartterm
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, restartterm saves various tty state bits,
- calls setupterm, and then restores the bits.
+ different. Accordingly, restartterm saves various tty state bits,
+ calls setupterm, and then restores the bits.
- The tparm routine instantiates the string str with parameters pi. A
- pointer is returned to the result of str with the parameters applied.
+ The tparm routine instantiates the string str with parameters pi. A
+ pointer is returned to the result of str with the parameters applied.
Application developers should keep in mind these quirks of the inter-
face:
- o Although tparm's actual parameters may be integers or strings, the
- prototype expects long (integer) values.
+ o Although tparm's actual parameters may be integers or strings, the
+ prototype expects long (integer) values.
- o Aside from the set_attributes (sgr) capability, most terminal capa-
+ o Aside from the set_attributes (sgr) capability, most terminal capa-
bilities require no more than one or two parameters.
- o Padding information is ignored by tparm; it is interpreted by
- tputs.
+ o Padding information is ignored by tparm; it is interpreted by
+ tputs.
- o The capability string is null-terminated. Use "\200" where an
+ o The capability string is null-terminated. Use "\200" where an
ASCII NUL is needed in the output.
- tiparm is a newer form of tparm which uses <stdarg.h> rather than a
+ tiparm is a newer form of tparm which uses <stdarg.h> rather than a
fixed-parameter list. Its numeric parameters are integers (int) rather
than longs.
- The tputs routine applies padding information (i.e., by interpreting
+ The tputs routine applies padding information (i.e., by interpreting
marker embedded in the terminfo capability such as "$<5>" as 5 mil-
- liseconds) to the string str and outputs it:
+ liseconds) to the string str and outputs it:
- o The str parameter must be a terminfo string variable or the return
- value from tparm, tiparm, tgetstr, or tgoto.
+ o The str parameter must be a terminfo string variable or the return
+ value from tparm, tiparm, tgetstr, or tgoto.
- The tgetstr and tgoto functions are part of the termcap interface,
- which happens to share this function name with the terminfo inter-
+ The tgetstr and tgoto functions are part of the termcap interface,
+ which happens to share this function name with the terminfo inter-
face.
- oaffcnt is the number of lines affected, or 1 if not applicable.
+ oaffcnt is the number of lines affected, or 1 if not applicable.
- oputc is a putchar-like routine to which the characters are passed,
+ oputc is a putchar-like routine to which the characters are passed,
one at a time.
- The putp routine calls tputs(str,1,putchar). The output of putp al-
- ways goes to stdout, rather than the filedes specified in setupterm.
+ The putp routine calls tputs(str,1,putchar). The output of putp al-
+ ways goes to stdout, rather than the filedes 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 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 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,
+ 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.,
- oattrs of type attr_t for the attributes and
+ oattrs of type attr_t for the attributes and
- opair of type short for the color-pair number.
+ opair of type 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 vid_attr and vid_puts routines are designed to use the attribute
+ constants with the WA_ prefix.
- X/Open Curses reserves the opts argument for future use, saying that
+ X/Open Curses reserves the opts argument for future use, saying that
applications must provide a null pointer for that argument. As an ex-
- tension, this implementation allows opts to be used as a pointer to
- int, which overrides the pair (short) argument.
+ tension, this implementation allows opts to be used as a pointer to
+ int, which overrides the pair (short) argument.
- The mvcur routine provides low-level cursor motion. It takes effect
+ The mvcur routine provides low-level cursor motion. It takes effect
immediately (rather than at the next refresh).
- While putp and mvcur are low-level functions which do not use the high-
- level curses state, they are declared in <curses.h> because SystemV did
- this (see HISTORY).
+ While putp and mvcur are low-level functions which do not use the high-
+ level curses state, they are declared in <curses.h> because SystemV did
+ this (see HISTORY).
- The tigetflag, tigetnum and tigetstr routines return the value of the
- capability corresponding to the terminfocapname passed to them, such
- as xenl. The capname for each capability is given in the table column
- entitled capname code in the capabilities section of terminfo(5).
+ The tigetflag, tigetnum and tigetstr routines return the value of the
+ capability corresponding to the terminfocapname passed to them, such
+ as xenl. The capname for each capability is given in the table column
+ entitled capname code in the capabilities section of terminfo(5).
These routines return special values to denote errors.
- The tigetflag routine returns
+ The tigetflag routine returns
- -1 if capname is not a boolean capability, or
+ -1 if capname is not a boolean capability, or
- 0 if it is canceled or absent from the terminal description.
+ 0 if it is canceled or absent from the terminal description.
- The tigetnum routine returns
+ The tigetnum routine returns
- -2 if capname is not a numeric capability, or
+ -2 if capname is not a numeric capability, or
- -1 if it is canceled or absent from the terminal description.
+ -1 if it is canceled or absent from the terminal description.
- The tigetstr routine returns
+ The tigetstr routine returns
- (char*)-1
- if capname is not a string capability, or
+ (char*)-1
+ if capname is not a string capability, or
- 0 if it is canceled or absent from the terminal description.
+ 0 if it is canceled or absent from the terminal description.
These null-terminated arrays contain
- o the short terminfo names ("codes"),
+ o the short terminfo names ("codes"),
- o the termcap names ("names"), and
+ o the termcap names ("names"), and
- o the long terminfo names ("fnames")
+ o the long terminfo names ("fnames")
- for each of the predefined terminfo variables:
+ for each of the predefined terminfo variables:
- constchar*boolnames[], *boolcodes[], *boolfnames[]
- constchar*numnames[], *numcodes[], *numfnames[]
- constchar*strnames[], *strcodes[], *strfnames[]
+ constchar*boolnames[], *boolcodes[], *boolfnames[]
+ constchar*numnames[], *numcodes[], *numfnames[]
+ constchar*strnames[], *strcodes[], *strfnames[]
- Routines that return an integer return ERR upon failure and OK (SVr4
- only specifies "an integer value other than ERR") upon successful com-
+ Routines that return an integer return ERR upon failure and OK (SVr4
+ only specifies "an integer value other than ERR") upon successful com-
pletion, 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 implementation
- del_curterm
+ del_curterm
returns an error if its terminal parameter is null.
- putp calls tputs, returning the same error-codes.
+ putp calls tputs, returning the same error-codes.
- restartterm
- returns an error if the associated call to setupterm returns an
+ restartterm
+ returns an error if the associated call to setupterm returns an
error.
- setupterm
+ setupterm
returns an error if it cannot allocate enough memory, or create
the initial windows (stdscr, curscr, newscr). Other error con-
ditions are documented above.
- tputs
+ tputs
returns an error if the string parameter is null. It does not
- detect I/O errors: X/Open states that tputs ignores the return
- value of the output function putc.
+ detect I/O errors: X/Open states that tputs ignores the return
+ value of the output function putc.
This implementation provides a few macros for compatibility with sys-
- tems before SVr4 (see HISTORY). Those include crmode, fixterm,
- gettmode, nocrmode, resetterm, saveterm, and setterm.
+ tems before SVr4 (see HISTORY). Those include crmode, fixterm,
+ gettmode, nocrmode, resetterm, saveterm, and setterm.
- In SVr4, those are found in <curses.h>, but except for setterm, are
- likewise macros. The one function, setterm, is mentioned in the manual
- page. The manual page notes that the setterm routine was replaced by
- setupterm, stating that the call:
+ In SVr4, those are found in <curses.h>, but except for setterm, are
+ likewise macros. The one function, setterm, is mentioned in the manual
+ page. The manual page notes that the setterm routine was replaced by
+ setupterm, stating that the call:
- setupterm(term,1,(int*)0)
+ setupterm(term,1,(int*)0)
- provides the same functionality as setterm(term), and is not recommend-
+ provides the same functionality as setterm(term), and is not recommend-
ed for new programs. This implementation provides each of those sym-
bols as macros for BSD compatibility,
@@ -398,13 +398,13 @@
SVr2 introduced the terminfo feature. Its programming manual mentioned
these low-level functions:
- FunctionDescription
+ FunctionDescription
------------------------------------------------------------
fixterm restore tty to "in curses" state
gettmode establish current tty modes
mvcur low level cursor motion
- putp utility function that uses tputs to send char-
- acters via putchar.
+ putp utility function that uses tputs to send char-
+ acters via putchar.
resetterm set tty modes to "out of curses" state
resetty reset tty flags to stored value
saveterm save current modes as "in curses" state
@@ -413,39 +413,39 @@
setupterm establish terminal with given type
tparm instantiate a string expression with parameters
tputs apply padding information to a string
- vidattr like vidputs, but outputs through putchar
+ vidattr like vidputs, but outputs through putchar
vidputs output a string to put terminal in a specified
video attribute mode
The programming manual also mentioned functions provided for termcap
compatibility (commenting that they "may go away at a later date"):
- FunctionDescription
+ FunctionDescription
------------------------------------------------
- tgetent look up termcap entry for given name
- tgetflag get boolean entry for given id
- tgetnum get numeric entry for given id
- tgetstr get string entry for given id
+ tgetent look up termcap entry for given name
+ tgetflag get boolean entry for given id
+ tgetnum get numeric entry for given id
+ tgetstr get string entry for given id
tgoto apply parameters to given capability
tputs apply padding to capability, calling
a function to put characters
- Early terminfo programs obtained capability values from the TERMINAL
- structure initialized by setupterm.
+ Early terminfo programs obtained capability values from the TERMINAL
+ structure initialized by setupterm.
SVr3 extended terminfo by adding functions to retrieve capability val-
ues (like the termcap interface), and reusing tgoto and tputs:
- FunctionDescription
+ FunctionDescription
-------------------------------------------
- tigetflag get boolean entry for given id
- tigetnum get numeric entry for given id
- tigetstr get string entry for given id
+ tigetflag get boolean entry for given id
+ tigetnum get numeric entry for given id
+ tigetstr get string entry for given id
SVr3 also replaced several of the SVr2 terminfo functions which had no
counterpart in the termcap interface, documenting them as obsolete:
- FunctionReplacedby
+ FunctionReplacedby
-----------------------------
crmode cbreak
fixterm reset_prog_mode
@@ -455,127 +455,134 @@
saveterm def_prog_mode
setterm setupterm
- SVr3 kept the mvcur, vidattr and vidputs functions, along with putp,
- tparm and tputs. The latter were needed to support padding, and han-
- dling functions such as vidattr (which used more than the two parame-
- ters supported by tgoto).
+ SVr3 kept the mvcur, vidattr and vidputs functions, along with putp,
+ tparm and tputs. The latter were needed to support padding, and han-
+ dling functions such as vidattr (which used more than the two parame-
+ ters supported by tgoto).
SVr3 introduced the functions for switching between terminal descrip-
- tions, e.g., set_curterm. The various global variables such as bool-
- names were mentioned in the programming manual at this point.
+ tions, e.g., set_curterm. Some of that was incremental improvements to
+ the SVr2 library:
- SVr4 added the vid_attr and vid_puts functions.
+ o The TERMINAL type definition was introduced in SVr3.01, for the
+ term structure provided in SVr2.
+
+ o The various global variables such as boolnames were mentioned in
+ the programming manual at this point, though the variables were
+ provided in SVr2.
+
+ SVr4 added the vid_attr and vid_puts functions.
There are other low-level functions declared in the curses header files
on Unix systems, but none were documented. The functions marked "obso-
- lete" remained in use by the Unix vi editor.
+ lete" remained in use by the Unix vi editor.
- X/Open notes that vidattr and vidputs may be macros.
+ X/Open notes that vidattr and vidputs may be macros.
- The function setterm is not described by X/Open and must be considered
+ The function setterm is not described by X/Open and must be considered
non-portable. All other functions are as described by X/Open.
- setupterm copies the terminal name to the array ttytype. This is not
+ setupterm copies the terminal name to the array ttytype. This is not
part of X/Open Curses, but is assumed by some applications.
- Other implementions may not declare the capability name arrays. Some
+ Other implementions may not declare the capability name arrays. Some
provide them without declaring them. X/Open does not specify them.
- Extended terminal capability names, e.g., as defined by tic-x, are not
+ Extended terminal capability names, e.g., as defined by tic-x, are not
stored in the arrays described here.
- Older versions of ncurses assumed that the file descriptor passed to
- setupterm from initscr or newterm uses buffered I/O, and would write to
- the corresponding stream. In addition to the limitation that the ter-
- minal was left in block-buffered mode on exit (like System V curses),
- it was problematic because ncurses did not allow a reliable way to
+ Older versions of ncurses assumed that the file descriptor passed to
+ setupterm from initscr or newterm uses buffered I/O, and would write to
+ the corresponding stream. In addition to the limitation that the ter-
+ minal was left in block-buffered mode on exit (like System V curses),
+ it was problematic because ncurses did not allow a reliable way to
cleanup on receiving SIGTSTP.
- The current version (ncurses6) uses output buffers managed directly by
- ncurses. Some of the low-level functions described in this manual page
+ The current version (ncurses6) uses output buffers managed directly by
+ ncurses. Some of the low-level functions described in this manual page
write to the standard output. They are not signal-safe. The high-lev-
- el functions in ncurses use alternate versions of these functions using
+ el functions in ncurses use alternate versions of these functions using
the more reliable buffering scheme.
The X/Open Curses prototypes are based on the SVr4 curses header decla-
- rations, which were defined at the same time the C language was first
+ rations, which were defined at the same time the C language was first
standardized in the late 1980s.
- o X/Open Curses uses const less effectively than a later design
- might, in some cases applying it needlessly to values are already
- constant, and in most cases overlooking parameters which normally
- would use const. Using constant parameters for functions which do
- not use const may prevent the program from compiling. On the other
- hand, writablestrings are an obsolescent feature.
+ o X/Open Curses uses const less effectively than a later design
+ might, in some cases applying it needlessly to values are already
+ constant, and in most cases overlooking parameters which normally
+ would use const. Using constant parameters for functions which do
+ not use const may prevent the program from compiling. On the other
+ hand, writablestrings are an obsolescent feature.
- As an extension, this implementation can be configured to change
- the function prototypes to use the const keyword. The ncurses ABI
+ As an extension, this implementation can be configured to change
+ the function prototypes to use the const keyword. The ncurses ABI
6 enables this feature by default.
- o X/Open Curses prototypes tparm with a fixed number of parameters,
+ o X/Open Curses prototypes tparm with a fixed number of parameters,
rather than a variable argument list.
- This implementation uses a variable argument list, but can be con-
- figured to use the fixed-parameter list. Portable applications
- should provide 9 parameters after the format; zeroes are fine for
+ This implementation uses a variable argument list, but can be con-
+ figured to use the fixed-parameter list. Portable applications
+ should provide 9 parameters after the format; zeroes are fine for
this purpose.
- In response to review comments by Thomas E. Dickey, X/Open Curses
- Issue 7 proposed the tiparm function in mid-2009.
+ In response to review comments by Thomas E. Dickey, X/Open Curses
+ Issue 7 proposed the tiparm function in mid-2009.
If configured to use the terminal-driver, e.g., for the MinGW port,
- osetupterm interprets a missing/empty TERM variable as the special
+ osetupterm interprets a missing/empty TERM variable as the special
value "unknown".
- osetupterm allows explicit use of the the windows console driver by
- checking if $TERM is set to "#win32con" or an abbreviation of that
+ osetupterm allows explicit use of the the windows console driver by
+ checking if $TERM is set to "#win32con" or an abbreviation of that
string.
- In System V Release 4, set_curterm has an int return type and returns
- OK or ERR. We have chosen to implement the X/Open Curses semantics.
+ In System V Release 4, set_curterm has an int return type and returns
+ OK or ERR. We have chosen to implement the X/Open Curses semantics.
- In System V Release 4, the third argument of tputs has the type int
- (*putc)(char).
+ In System V Release 4, the third argument of tputs has the type int
+ (*putc)(char).
- At least one implementation of X/Open Curses (Solaris) returns a value
- other than OK/ERR from tputs. That returns the length of the string,
+ At least one implementation of X/Open Curses (Solaris) returns a value
+ other than OK/ERR from tputs. That returns the length of the string,
and does no error-checking.
- X/Open notes that after calling mvcur, the curses state may not match
+ X/Open notes that after calling mvcur, the curses state may not match
the actual terminal state, and that an application should touch and re-
- fresh the window before resuming normal curses calls. Both ncurses and
- System V Release 4 curses implement mvcur using the SCREEN data allo-
- cated in either initscr or newterm. So though it is documented as a
- terminfo function, mvcur is really a curses function which is not well
+ fresh the window before resuming normal curses calls. Both ncurses and
+ System V Release 4 curses implement mvcur using the SCREEN data allo-
+ cated 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.
- X/Open states that the old location must be given for mvcur. This im-
- plementation allows the caller to use -1's for the old ordinates. In
+ X/Open states that the old location must be given for mvcur. This im-
+ plementation allows the caller to use -1's for the old ordinates. In
that case, the old location is unknown.