1curs_terminfo(3X) curs_terminfo(3X)
2
6 del_curterm, mvcur, putp, restartterm, set_curterm, setupterm,
7 tigetflag, tigetnum, tigetstr, tiparm, tiparm_s, tiscan_s, tparm,
8 tputs, vid_attr, vid_puts, vidattr, vidputs - curses interfaces to
9 terminfo database
10
12 #include <curses.h>
13 #include <term.h>
14 TERMINAL *cur_term;
16 const char * const boolnames[];
18 const char * const boolcodes[];
19 const char * const boolfnames[];
20 const char * const numnames[];
21 const char * const numcodes[];
22 const char * const numfnames[];
23 const char * const strnames[];
24 const char * const strcodes[];
25 const char * const strfnames[];
26 int setupterm(const char *term, int filedes, int *errret);
28 TERMINAL *set_curterm(TERMINAL *nterm);
29 int del_curterm(TERMINAL *oterm);
30 int restartterm(const char *term, int filedes, int *errret);
31 char *tparm(const char *str, ...);
33 or
34 char *tparm(const char *str, long p1 ... long p9);
35 int tputs(const char *str, int affcnt, int (*putc)(int));
37 int putp(const char *str);
38 int vidputs(chtype attrs, int (*putc)(int));
40 int vidattr(chtype attrs);
41 int vid_puts(attr_t attrs, short pair, void *opts, int (*putc)(int));
42 int vid_attr(attr_t attrs, short pair, void *opts);
43 int mvcur(int oldrow, int oldcol, int newrow, int newcol);
45 int tigetflag(const char *capname);
47 int tigetnum(const char *capname);
48 char *tigetstr(const char *capname);
49 char *tiparm(const char *str, ...);
51 /* extensions */
53 char *tiparm_s(int expected, int mask, const char *str, ...);
54 int tiscan_s(int *expected, int *mask, const char *str);
55
57 These low-level routines must be called by programs that have to deal
58 directly with the terminfo database to handle certain terminal capabil‐
59 ities, such as programming function keys. For all other functionality,
60 curses routines are more suitable and their use is recommended.
61 None of these functions use (or are aware of) multibyte character
63 strings such as UTF-8:
64 • capability names use the POSIX portable character set
66 • capability string values have no associated encoding; they are
68 strings of 8-bit characters.
69 Initialization
71 Initially, setupterm should be called. The high-level curses functions
72 initscr and newterm call setupterm to initialize the low-level set of
73 terminal-dependent variables [listed in terminfo(5)].
74 Applications can use the terminal capabilities either directly (via
76 header definitions), or by special functions. The header files curs‐
77 es.h and term.h should be included (in this order) to get the defini‐
78 tions for these strings, numbers, and flags.
79 The terminfo variables lines and columns are initialized by setupterm
81 as follows:
82 • If use_env(FALSE) has been called, values for lines and columns
84 specified in terminfo are used.
85 • Otherwise, if the environment variables LINES and COLUMNS exist,
87 their values are used. If these environment variables do not exist
88 and the program is running in a window, the current window size is
89 used. Otherwise, if the environment variables do not exist, the
90 values for lines and columns specified in the terminfo database are
91 used.
92 Parameterized strings should be passed through tparm to instantiate
94 them. All terminfo strings (including the output of tparm) should be
95 printed with tputs or putp. Call reset_shell_mode to restore the tty
96 modes before exiting [see curs_kernel(3X)].
97 Programs which use cursor addressing should
99 • output enter_ca_mode upon startup and
101 • output exit_ca_mode before exiting.
103 Programs which execute shell subprocesses should
105 • call reset_shell_mode and output exit_ca_mode before the shell is
107 called and
108 • output enter_ca_mode and call reset_prog_mode after returning from
110 the shell.
111 The setupterm routine reads in the terminfo database, initializing the
113 terminfo structures, but does not set up the output virtualization
114 structures used by curses. These are its parameters:
115 term is the terminal type, a character string. If term is null, the
117 environment variable TERM is used.
118 filedes
120 is the file descriptor used for all output.
121 errret
123 points to an optional location where an error status can be re‐
124 turned to the caller. If errret is not null, then setupterm
125 returns OK or ERR and stores a status value in the integer
126 pointed to by errret. A return value of OK combined with sta‐
127 tus of 1 in errret is normal.
128 If ERR is returned, examine errret:
130 1 means that the terminal is hardcopy, cannot be used for
132 curses applications.
133 setupterm determines if the entry is a hardcopy type by
135 checking the hc (hardcopy) capability.
136 0 means that the terminal could not be found, or that it is
138 a generic type, having too little information for curses
139 applications to run.
140 setupterm determines if the entry is a generic type by
142 checking the gn (generic) capability.
143 -1 means that the terminfo database could not be found.
145 If errret is null, setupterm prints an error message upon find‐
147 ing an error and exits. Thus, the simplest call is:
148 setupterm((char *)0, 1, (int *)0);,
150 which uses all the defaults and sends the output to stdout.
152 The Terminal State
154 The setupterm routine stores its information about the terminal in a
155 TERMINAL structure pointed to by the global variable cur_term. If it
156 detects an error, or decides that the terminal is unsuitable (hardcopy
157 or generic), it discards this information, making it not available to
158 applications.
159 If setupterm is called repeatedly for the same terminal type, it will
161 reuse the information. It maintains only one copy of a given termi‐
162 nal's capabilities in memory. If it is called for different terminal
163 types, setupterm allocates new storage for each set of terminal capa‐
164 bilities.
165 The set_curterm routine sets cur_term to nterm, and makes all of the
167 terminfo boolean, numeric, and string variables use the values from
168 nterm. It returns the old value of cur_term.
169 The del_curterm routine frees the space pointed to by oterm and makes
171 it available for further use. If oterm is the same as cur_term, refer‐
172 ences to any of the terminfo boolean, numeric, and string variables
173 thereafter may refer to invalid memory locations until another se‐
174 tupterm has been called.
175 The restartterm routine is similar to setupterm and initscr, except
177 that it is called after restoring memory to a previous state (for exam‐
178 ple, when reloading a game saved as a core image dump). restartterm
179 assumes that the windows and the input and output options are the same
180 as when memory was saved, but the terminal type and baud rate may be
181 different. Accordingly, restartterm saves various tty state bits,
182 calls setupterm, and then restores the bits.
183 Formatting Output
185 The tparm routine instantiates the string str with parameters pi. A
186 pointer is returned to the result of str with the parameters applied.
187 Application developers should keep in mind these quirks of the inter‐
188 face:
189 • Although tparm's actual parameters may be integers or strings, the
191 prototype expects long (integer) values.
192 • Aside from the set_attributes (sgr) capability, most terminal capa‐
194 bilities require no more than one or two parameters.
195 • Padding information is ignored by tparm; it is interpreted by
197 tputs.
198 • The capability string is null-terminated. Use “\200” where an
200 ASCII NUL is needed in the output.
201 tiparm is a newer form of tparm which uses <stdarg.h> rather than a
203 fixed-parameter list. Its numeric parameters are integers (int) rather
204 than longs.
205 Both tparm and tiparm assume that the application passes parameters
207 consistent with the terminal description. Two extensions are provided
208 as alternatives to deal with untrusted data:
209 • tiparm_s is an extension which is a safer formatting function than
211 tparm or tiparm, because it allows the developer to tell the curses
212 library how many parameters to expect in the parameter list, and
213 which may be string parameters.
214 The mask parameter has one bit set for each of the parameters (up
216 to 9) which will be passed as char* rather than numbers.
217 • The extension tiscan_s allows the application to inspect a format‐
219 ting capability to see what the curses library would assume.
220 Output Functions
222 The tputs routine applies padding information (i.e., by interpreting
223 marker embedded in the terminfo capability such as “$<5>” as 5 mil‐
224 liseconds) to the string str and outputs it:
225 • The str parameter must be a terminfo string variable or the return
227 value from tparm, tiparm, tgetstr, or tgoto.
228 The tgetstr and tgoto functions are part of the termcap interface,
230 which happens to share this function name with the terminfo inter‐
231 face.
232 • affcnt is the number of lines affected, or 1 if not applicable.
234 • putc is a putchar-like routine to which the characters are passed,
236 one at a time.
237 The putp routine calls tputs(str, 1, putchar). The output of putp al‐
239 ways goes to stdout, rather than the filedes specified in setupterm.
240 The vidputs routine displays the string on the terminal in the video
242 attribute mode attrs, which is any combination of the attributes listed
243 in curses(3X). The characters are passed to the putchar-like routine
244 putc.
245 The vidattr routine is like the vidputs routine, except that it outputs
247 through putchar.
248 The vid_attr and vid_puts routines correspond to vidattr and vidputs,
250 respectively. They use a set of arguments for representing the video
251 attributes plus color, i.e.,
252 • attrs of type attr_t for the attributes and
254 • pair of type short for the color-pair number.
256 The vid_attr and vid_puts routines are designed to use the attribute
258 constants with the WA_ prefix.
259 X/Open Curses reserves the opts argument for future use, saying that
261 applications must provide a null pointer for that argument. As an ex‐
262 tension, this implementation allows opts to be used as a pointer to
263 int, which overrides the pair (short) argument.
264 The mvcur routine provides low-level cursor motion. It takes effect
266 immediately (rather than at the next refresh).
267 While putp and mvcur are low-level functions which do not use the high-
269 level curses state, they are declared in <curses.h> because SystemV did
270 this (see HISTORY).
271 Terminal Capability Functions
273 The tigetflag, tigetnum and tigetstr routines return the value of the
274 capability corresponding to the terminfo capname passed to them, such
275 as xenl. The capname for each capability is given in the table column
276 entitled capname code in the capabilities section of terminfo(5).
277 These routines return special values to denote errors.
279 The tigetflag routine returns
281 -1 if capname is not a boolean capability, or
283 0 if it is canceled or absent from the terminal description.
285 The tigetnum routine returns
287 -2 if capname is not a numeric capability, or
289 -1 if it is canceled or absent from the terminal description.
291 The tigetstr routine returns
293 (char *)-1
295 if capname is not a string capability, or
296 0 if it is canceled or absent from the terminal description.
298 Terminal Capability Names
300 These null-terminated arrays contain
301 • the short terminfo names (“codes”),
303 • the termcap names (“names”), and
305 • the long terminfo names (“fnames”)
307 for each of the predefined terminfo variables:
309 const char *boolnames[], *boolcodes[], *boolfnames[]
311 const char *numnames[], *numcodes[], *numfnames[]
312 const char *strnames[], *strcodes[], *strfnames[]
313 Releasing Memory
315 Each successful call to setupterm allocates memory to hold the terminal
316 description. As a side-effect, it sets cur_term to point to this memo‐
317 ry. If an application calls
318 del_curterm(cur_term);
320 the memory will be freed.
322 The formatting functions tparm and tiparm extend the storage allocated
324 by setupterm:
325 • the “static” terminfo variables [a-z]. Before ncurses 6.3, those
327 were shared by all screens. With ncurses 6.3, those are allocated
328 per screen. See terminfo(5) for details.
329 • to improve performance, ncurses 6.3 caches the result of analyzing
331 terminfo strings for their parameter types. That is stored as a
332 binary tree referenced from the TERMINAL structure.
333 The higher-level initscr and newterm functions use setupterm. Normally
335 they do not free this memory, but it is possible to do that using the
336 delscreen(3X) function.
337
339 Routines that return an integer return ERR upon failure and OK (SVr4
340 only specifies “an integer value other than ERR”) upon successful com‐
341 pletion, unless otherwise noted in the preceding routine descriptions.
342 Routines that return pointers always return NULL on error.
344 X/Open defines no error conditions. In this implementation
346 del_curterm
348 returns an error if its terminal parameter is null.
349 putp calls tputs, returning the same error-codes.
351 restartterm
353 returns an error if the associated call to setupterm returns an
354 error.
355 setupterm
357 returns an error if it cannot allocate enough memory, or create
358 the initial windows (stdscr, curscr, newscr). Other error con‐
359 ditions are documented above.
360 tparm
362 returns a null if the capability would require unexpected pa‐
363 rameters, e.g., too many, too few, or incorrect types (strings
364 where integers are expected, or vice versa).
365 tputs
367 returns an error if the string parameter is null. It does not
368 detect I/O errors: X/Open states that tputs ignores the return
369 value of the output function putc.
370 Compatibility macros
372 This implementation provides a few macros for compatibility with sys‐
373 tems before SVr4 (see HISTORY). Those include crmode, fixterm,
374 gettmode, nocrmode, resetterm, saveterm, and setterm.
375 In SVr4, those are found in <curses.h>, but except for setterm, are
377 likewise macros. The one function, setterm, is mentioned in the manual
378 page. The manual page notes that the setterm routine was replaced by
379 setupterm, stating that the call:
380 setupterm(term, 1, (int *)0)
382 provides the same functionality as setterm(term), and is not recommend‐
384 ed for new programs. This implementation provides each of those sym‐
385 bols as macros for BSD compatibility,
386
388 SVr2 introduced the terminfo feature. Its programming manual mentioned
389 these low-level functions:
390 Function Description
392 ────────────────────────────────────────────────────────────
393 fixterm restore tty to “in curses” state
394 gettmode establish current tty modes
395 mvcur low level cursor motion
396 putp utility function that uses tputs to send char‐
397 acters via putchar.
398 resetterm set tty modes to “out of curses” state
400 resetty reset tty flags to stored value
401 saveterm save current modes as “in curses” state
402 savetty store current tty flags
403 setterm establish terminal with given type
404 setupterm establish terminal with given type
405 tparm instantiate a string expression with parameters
406 tputs apply padding information to a string
407 vidattr like vidputs, but outputs through putchar
408 vidputs output a string to put terminal in a specified
409 video attribute mode
410 The programming manual also mentioned functions provided for termcap
412 compatibility (commenting that they “may go away at a later date”):
413 Function Description
415 ────────────────────────────────────────────────
416 tgetent look up termcap entry for given name
417 tgetflag get boolean entry for given id
418 tgetnum get numeric entry for given id
419 tgetstr get string entry for given id
420 tgoto apply parameters to given capability
421 tputs apply padding to capability, calling
422 a function to put characters
423 Early terminfo programs obtained capability values from the TERMINAL
425 structure initialized by setupterm.
426 SVr3 extended terminfo by adding functions to retrieve capability val‐
428 ues (like the termcap interface), and reusing tgoto and tputs:
429 Function Description
431 ───────────────────────────────────────────
432 tigetflag get boolean entry for given id
433 tigetnum get numeric entry for given id
434 tigetstr get string entry for given id
435 SVr3 also replaced several of the SVr2 terminfo functions which had no
437 counterpart in the termcap interface, documenting them as obsolete:
438 Function Replaced by
440 ─────────────────────────────
441 crmode cbreak
442 fixterm reset_prog_mode
443 gettmode N/A
444 nocrmode nocbreak
445 resetterm reset_shell_mode
446 saveterm def_prog_mode
447 setterm setupterm
448 SVr3 kept the mvcur, vidattr and vidputs functions, along with putp,
450 tparm and tputs. The latter were needed to support padding, and han‐
451 dling functions such as vidattr (which used more than the two parame‐
452 ters supported by tgoto).
453 SVr3 introduced the functions for switching between terminal descrip‐
455 tions, e.g., set_curterm. Some of that was incremental improvements to
456 the SVr2 library:
457 • The TERMINAL type definition was introduced in SVr3.01, for the
459 term structure provided in SVr2.
460 • The various global variables such as boolnames were mentioned in
462 the programming manual at this point, though the variables were
463 provided in SVr2.
464 SVr4 added the vid_attr and vid_puts functions.
466 There are other low-level functions declared in the curses header files
468 on Unix systems, but none were documented. The functions marked “obso‐
469 lete” remained in use by the Unix vi(1) editor.
470
472 Extensions
473 The functions marked as extensions were designed for ncurses(3X), and
474 are not found in SVr4 curses, 4.4BSD curses, or any other previous ver‐
475 sion of curses.
476 Legacy functions
478 X/Open notes that vidattr and vidputs may be macros.
479 The function setterm is not described by X/Open and must be considered
481 non-portable. All other functions are as described by X/Open.
482 Legacy data
484 setupterm copies the terminal name to the array ttytype. This is not
485 part of X/Open Curses, but is assumed by some applications.
486 Other implementions may not declare the capability name arrays. Some
488 provide them without declaring them. X/Open does not specify them.
489 Extended terminal capability names, e.g., as defined by tic -x, are not
491 stored in the arrays described here.
492 Output buffering
494 Older versions of ncurses assumed that the file descriptor passed to
495 setupterm from initscr or newterm uses buffered I/O, and would write to
496 the corresponding stream. In addition to the limitation that the ter‐
497 minal was left in block-buffered mode on exit (like System V curses),
498 it was problematic because ncurses did not allow a reliable way to
499 cleanup on receiving SIGTSTP.
500 The current version (ncurses6) uses output buffers managed directly by
502 ncurses. Some of the low-level functions described in this manual page
503 write to the standard output. They are not signal-safe. The high-lev‐
504 el functions in ncurses use alternate versions of these functions using
505 the more reliable buffering scheme.
506 Function prototypes
508 The X/Open Curses prototypes are based on the SVr4 curses header decla‐
509 rations, which were defined at the same time the C language was first
510 standardized in the late 1980s.
511 • X/Open Curses uses const less effectively than a later design
513 might, in some cases applying it needlessly to values are already
514 constant, and in most cases overlooking parameters which normally
515 would use const. Using constant parameters for functions which do
516 not use const may prevent the program from compiling. On the other
517 hand, writable strings are an obsolescent feature.
518 As an extension, this implementation can be configured to change
520 the function prototypes to use the const keyword. The ncurses ABI
521 6 enables this feature by default.
522 • X/Open Curses prototypes tparm with a fixed number of parameters,
524 rather than a variable argument list.
525 This implementation uses a variable argument list, but can be con‐
527 figured to use the fixed-parameter list. Portable applications
528 should provide 9 parameters after the format; zeroes are fine for
529 this purpose.
530 In response to review comments by Thomas E. Dickey, X/Open Curses
532 Issue 7 proposed the tiparm function in mid-2009.
533 While tiparm is always provided in ncurses, the older form is only
535 available as a build-time configuration option. If not specially
536 configured, tparm is the same as tiparm.
537 Both forms of tparm have drawbacks:
539 • Most of the calls to tparm use only one or two parameters. Passing
541 nine on each call is awkward.
542 Using long for the numeric parameter type is a workaround to make
544 the parameter use the same amount of stack as a pointer. That ap‐
545 proach dates back to the mid-1980s, before C was standarized.
546 Since then, there is a standard (and pointers are not required to
547 fit in a long).
548 • Providing the right number of parameters for a variadic function
550 such as tiparm can be a problem, in particular for string parame‐
551 ters. However, only a few terminfo capabilities use string parame‐
552 ters (e.g., the ones used for programmable function keys).
553 The ncurses library checks usage of these capabilities, and returns
555 an error if the capability mishandles string parameters. But it
556 cannot check if a calling program provides strings in the right
557 places for the tparm calls.
558 The tput(1) program checks its use of these capabilities with a ta‐
560 ble, so that it calls tparm correctly.
561 Special TERM treatment
563 If configured to use the terminal-driver, e.g., for the MinGW port,
564 • setupterm interprets a missing/empty TERM variable as the special
566 value “unknown”.
567 • setupterm allows explicit use of the the windows console driver by
569 checking if $TERM is set to “#win32con” or an abbreviation of that
570 string.
571 Other portability issues
573 In System V Release 4, set_curterm has an int return type and returns
574 OK or ERR. We have chosen to implement the X/Open Curses semantics.
575 In System V Release 4, the third argument of tputs has the type int
577 (*putc)(char).
578 At least one implementation of X/Open Curses (Solaris) returns a value
580 other than OK/ERR from tputs. That returns the length of the string,
581 and does no error-checking.
582 X/Open notes that after calling mvcur, the curses state may not match
584 the actual terminal state, and that an application should touch and re‐
585 fresh the window before resuming normal curses calls. Both ncurses and
586 System V Release 4 curses implement mvcur using the SCREEN data allo‐
587 cated in either initscr or newterm. So though it is documented as a
588 terminfo function, mvcur is really a curses function which is not well
589 specified.
590 X/Open states that the old location must be given for mvcur. This im‐
592 plementation allows the caller to use -1's for the old ordinates. In
593 that case, the old location is unknown.
594
596 curses(3X), curs_initscr(3X), curs_kernel(3X), curs_memleaks(3X),
597 curs_termcap(3X), curs_variables(3X), term_variables(3X), putc(3), ter‐
598 minfo(5)
599 curs_terminfo(3X)