1curs_terminfo(3X)                                            curs_terminfo(3X)
2
3
4

NAME

6       del_curterm, mvcur, putp, restartterm, set_curterm, setupterm,
7       tigetflag, tigetnum, tigetstr, tiparm, tparm, tputs, vid_attr,
8       vid_puts, vidattr, vidputs - curses interfaces to terminfo database
9

SYNOPSIS

11       #include <curses.h>
12       #include <term.h>
13
14       TERMINAL *cur_term;
15
16       const char * const boolnames[];
17       const char * const boolcodes[];
18       const char * const boolfnames[];
19       const char * const numnames[];
20       const char * const numcodes[];
21       const char * const numfnames[];
22       const char * const strnames[];
23       const char * const strcodes[];
24       const char * const strfnames[];
25
26       int setupterm(const char *term, int filedes, int *errret);
27       TERMINAL *set_curterm(TERMINAL *nterm);
28       int del_curterm(TERMINAL *oterm);
29       int restartterm(const char *term, int filedes, int *errret);
30
31       char *tparm(const char *str, ...);
32       int tputs(const char *str, int affcnt, int (*putc)(int));
33       int putp(const char *str);
34
35       int vidputs(chtype attrs, int (*putc)(int));
36       int vidattr(chtype attrs);
37       int vid_puts(attr_t attrs, short pair, void *opts, int (*putc)(int));
38       int vid_attr(attr_t attrs, short pair, void *opts);
39
40       int mvcur(int oldrow, int oldcol, int newrow, int newcol);
41
42       int tigetflag(const char *capname);
43       int tigetnum(const char *capname);
44       char *tigetstr(const char *capname);
45
46       char *tiparm(const char *str, ...);
47

DESCRIPTION

49       These  low-level  routines must be called by programs that have to deal
50       directly with the terminfo database to handle certain terminal capabil‐
51       ities, such as programming function keys.  For all other functionality,
52       curses routines are more suitable and their use is recommended.
53
54       None of these functions use  (or  are  aware  of)  multibyte  character
55       strings such as UTF-8:
56
57       •   capability names use the POSIX portable character set
58
59       •   capability  string  values  have  no  associated encoding; they are
60           strings of 8-bit characters.
61
62   Initialization
63       Initially, setupterm should be called.  The high-level curses functions
64       initscr  and  newterm call setupterm to initialize the low-level set of
65       terminal-dependent variables [listed in terminfo(5)].
66
67       Applications can use the terminal  capabilities  either  directly  (via
68       header  definitions),  or by special functions.  The header files curs‐
69       es.h and term.h should be included (in this order) to get  the  defini‐
70       tions for these strings, numbers, and flags.
71
72       The  terminfo  variables lines and columns are initialized by setupterm
73       as follows:
74
75       •   If use_env(FALSE) has been called, values  for  lines  and  columns
76           specified in terminfo are used.
77
78       •   Otherwise,  if  the  environment variables LINES and COLUMNS exist,
79           their values are used.  If these environment variables do not exist
80           and  the program is running in a window, the current window size is
81           used.  Otherwise, if the environment variables do  not  exist,  the
82           values for lines and columns specified in the terminfo database are
83           used.
84
85       Parameterized strings should be passed  through  tparm  to  instantiate
86       them.   All  terminfo strings (including the output of tparm) should be
87       printed with tputs or putp.  Call reset_shell_mode to restore  the  tty
88       modes before exiting [see curs_kernel(3X)].
89
90       Programs which use cursor addressing should
91
92       •   output enter_ca_mode upon startup and
93
94       •   output exit_ca_mode before exiting.
95
96       Programs which execute shell subprocesses should
97
98       •   call  reset_shell_mode  and output exit_ca_mode before the shell is
99           called and
100
101       •   output enter_ca_mode and call reset_prog_mode after returning  from
102           the shell.
103
104       The  setupterm routine reads in the terminfo database, initializing the
105       terminfo structures, but does not  set  up  the  output  virtualization
106       structures used by curses.  These are its parameters:
107
108          term is the terminal type, a character string.  If term is null, the
109               environment variable TERM is used.
110
111          filedes
112               is the file descriptor used for all output.
113
114          errret
115               points to an optional location where an error status can be re‐
116               turned  to  the  caller.  If errret is not null, then setupterm
117               returns OK or ERR and stores a  status  value  in  the  integer
118               pointed  to by errret.  A return value of OK combined with sta‐
119               tus of 1 in errret is normal.
120
121               If ERR is returned, examine errret:
122
123               1    means that the terminal is hardcopy, cannot  be  used  for
124                    curses applications.
125
126                    setupterm  determines  if  the entry is a hardcopy type by
127                    checking the hc (hardcopy) capability.
128
129               0    means that the terminal could not be found, or that it  is
130                    a  generic  type, having too little information for curses
131                    applications to run.
132
133                    setupterm determines if the entry is  a  generic  type  by
134                    checking the gn (generic) capability.
135
136               -1   means that the terminfo database could not be found.
137
138               If errret is null, setupterm prints an error message upon find‐
139               ing an error and exits.  Thus, the simplest call is:
140
141                     setupterm((char *)0, 1, (int *)0);,
142
143               which uses all the defaults and sends the output to stdout.
144
145   The Terminal State
146       The setupterm routine stores its information about the  terminal  in  a
147       TERMINAL  structure  pointed to by the global variable cur_term.  If it
148       detects an error, or decides that the terminal is unsuitable  (hardcopy
149       or  generic),  it discards this information, making it not available to
150       applications.
151
152       If setupterm is called repeatedly for the same terminal type,  it  will
153       reuse  the  information.   It maintains only one copy of a given termi‐
154       nal's capabilities in memory.  If it is called for  different  terminal
155       types,  setupterm  allocates new storage for each set of terminal capa‐
156       bilities.
157
158       The set_curterm routine sets cur_term to nterm, and makes  all  of  the
159       terminfo  boolean,  numeric,  and  string variables use the values from
160       nterm.  It returns the old value of cur_term.
161
162       The del_curterm routine frees the space pointed to by oterm  and  makes
163       it available for further use.  If oterm is the same as cur_term, refer‐
164       ences to any of the terminfo boolean,  numeric,  and  string  variables
165       thereafter  may  refer  to  invalid  memory locations until another se‐
166       tupterm has been called.
167
168       The restartterm routine is similar to  setupterm  and  initscr,  except
169       that it is called after restoring memory to a previous state (for exam‐
170       ple, when reloading a game saved as a core  image  dump).   restartterm
171       assumes  that the windows and the input and output options are the same
172       as when memory was saved, but the terminal type and baud  rate  may  be
173       different.   Accordingly,  restartterm  saves  various  tty state bits,
174       calls setupterm, and then restores the bits.
175
176   Formatting Output
177       The tparm routine instantiates the string str with  parameters  pi.   A
178       pointer  is  returned to the result of str with the parameters applied.
179       Application developers should keep in mind these quirks of  the  inter‐
180       face:
181
182       •   Although  tparm's actual parameters may be integers or strings, the
183           prototype expects long (integer) values.
184
185       •   Aside from the set_attributes (sgr) capability, most terminal capa‐
186           bilities require no more than one or two parameters.
187
188       •   Padding  information  is  ignored  by  tparm;  it is interpreted by
189           tputs.
190
191       •   The capability string is  null-terminated.   Use  “\200”  where  an
192           ASCII NUL is needed in the output.
193
194       tiparm  is  a  newer  form of tparm which uses <stdarg.h> rather than a
195       fixed-parameter list.  Its numeric parameters are integers (int) rather
196       than longs.
197
198   Output Functions
199       The  tputs  routine  applies padding information (i.e., by interpreting
200       marker embedded in the terminfo capability such as  “$<5>”  as  5  mil‐
201       liseconds) to the string str and outputs it:
202
203       •   The  str parameter must be a terminfo string variable or the return
204           value from tparm, tiparm, tgetstr, or tgoto.
205
206           The tgetstr and tgoto functions are part of the termcap  interface,
207           which  happens to share this function name with the terminfo inter‐
208           face.
209
210affcnt is the number of lines affected, or 1 if not applicable.
211
212putc is a putchar-like routine to which the characters are  passed,
213           one at a time.
214
215       The  putp routine calls tputs(str, 1, putchar).  The output of putp al‐
216       ways goes to stdout, rather than the filedes specified in setupterm.
217
218       The vidputs routine displays the string on the terminal  in  the  video
219       attribute mode attrs, which is any combination of the attributes listed
220       in curses(3X).  The characters are passed to the  putchar-like  routine
221       putc.
222
223       The vidattr routine is like the vidputs routine, except that it outputs
224       through putchar.
225
226       The vid_attr and vid_puts routines correspond to vidattr  and  vidputs,
227       respectively.   They  use a set of arguments for representing the video
228       attributes plus color, i.e.,
229
230attrs of type attr_t for the attributes and
231
232pair of type short for the color-pair number.
233
234       The vid_attr and vid_puts routines are designed to  use  the  attribute
235       constants with the WA_ prefix.
236
237       X/Open  Curses  reserves  the opts argument for future use, saying that
238       applications must provide a null pointer for that argument.  As an  ex‐
239       tension,  this  implementation  allows  opts to be used as a pointer to
240       int, which overrides the pair (short) argument.
241
242       The mvcur routine provides low-level cursor motion.   It  takes  effect
243       immediately (rather than at the next refresh).
244
245       While putp and mvcur are low-level functions which do not use the high-
246       level curses state, they are declared in <curses.h> because SystemV did
247       this (see HISTORY).
248
249   Terminal Capability Functions
250       The  tigetflag,  tigetnum and tigetstr routines return the value of the
251       capability corresponding to the terminfo capname passed to  them,  such
252       as  xenl.  The capname for each capability is given in the table column
253       entitled capname code in the capabilities section of terminfo(5).
254
255       These routines return special values to denote errors.
256
257       The tigetflag routine returns
258
259       -1     if capname is not a boolean capability, or
260
261       0      if it is canceled or absent from the terminal description.
262
263       The tigetnum routine returns
264
265       -2     if capname is not a numeric capability, or
266
267       -1     if it is canceled or absent from the terminal description.
268
269       The tigetstr routine returns
270
271       (char *)-1
272              if capname is not a string capability, or
273
274       0      if it is canceled or absent from the terminal description.
275
276   Terminal Capability Names
277       These null-terminated arrays contain
278
279       •   the short terminfo names (“codes”),
280
281       •   the termcap names (“names”), and
282
283       •   the long terminfo names (“fnames”)
284
285       for each of the predefined terminfo variables:
286
287              const char *boolnames[], *boolcodes[], *boolfnames[]
288              const char *numnames[], *numcodes[], *numfnames[]
289              const char *strnames[], *strcodes[], *strfnames[]
290
291   Releasing Memory
292       Each successful call to setupterm allocates memory to hold the terminal
293       description.  As a side-effect, it sets cur_term to point to this memo‐
294       ry.  If an application calls
295
296            del_curterm(cur_term);
297
298       the memory will be freed.
299
300       The formatting functions tparm and tiparm extend the storage  allocated
301       by setupterm:
302
303       •   the  “static”  terminfo variables [a-z].  Before ncurses 6.3, those
304           were shared by all screens.  With ncurses 6.3, those are  allocated
305           per screen.  See terminfo(5) for details.
306
307       •   to  improve performance, ncurses 6.3 caches the result of analyzing
308           terminfo strings for their parameter types.  That is  stored  as  a
309           binary tree referenced from the TERMINAL structure.
310
311       The higher-level initscr and newterm functions use setupterm.  Normally
312       they do not free this memory, but it is possible to do that  using  the
313       delscreen(3X) function.
314

RETURN VALUE

316       Routines  that  return  an integer return ERR upon failure and OK (SVr4
317       only specifies “an integer value other than ERR”) upon successful  com‐
318       pletion, unless otherwise noted in the preceding routine descriptions.
319
320       Routines that return pointers always return NULL on error.
321
322       X/Open defines no error conditions.  In this implementation
323
324          del_curterm
325               returns an error if its terminal parameter is null.
326
327          putp calls tputs, returning the same error-codes.
328
329          restartterm
330               returns an error if the associated call to setupterm returns an
331               error.
332
333          setupterm
334               returns an error if it cannot allocate enough memory, or create
335               the initial windows (stdscr, curscr, newscr).  Other error con‐
336               ditions are documented above.
337
338          tputs
339               returns an error if the string parameter is null.  It does  not
340               detect  I/O errors: X/Open states that tputs ignores the return
341               value of the output function putc.
342
343   Compatibility macros
344       This implementation provides a few macros for compatibility  with  sys‐
345       tems  before  SVr4  (see  HISTORY).   Those  include  crmode,  fixterm,
346       gettmode, nocrmode, resetterm, saveterm, and setterm.
347
348       In SVr4, those are found in <curses.h>, but  except  for  setterm,  are
349       likewise macros.  The one function, setterm, is mentioned in the manual
350       page.  The manual page notes that the setterm routine was  replaced  by
351       setupterm, stating that the call:
352
353             setupterm(term, 1, (int *)0)
354
355       provides the same functionality as setterm(term), and is not recommend‐
356       ed for new programs.  This implementation provides each of  those  sym‐
357       bols as macros for BSD compatibility,
358

HISTORY

360       SVr2 introduced the terminfo feature.  Its programming manual mentioned
361       these low-level functions:
362
363       Function    Description
364       ────────────────────────────────────────────────────────────
365       fixterm     restore tty to “in curses” state
366       gettmode    establish current tty modes
367       mvcur       low level cursor motion
368       putp        utility function that uses tputs to send  char‐
369                   acters via putchar.
370       resetterm   set tty modes to “out of curses” state
371       resetty     reset tty flags to stored value
372       saveterm    save current modes as “in curses” state
373       savetty     store current tty flags
374       setterm     establish terminal with given type
375       setupterm   establish terminal with given type
376       tparm       instantiate a string expression with parameters
377       tputs       apply padding information to a string
378       vidattr     like vidputs, but outputs through putchar
379       vidputs     output  a string to put terminal in a specified
380                   video attribute mode
381
382       The programming manual also mentioned functions  provided  for  termcap
383       compatibility (commenting that they “may go away at a later date”):
384
385       Function   Description
386       ────────────────────────────────────────────────
387       tgetent    look up termcap entry for given name
388       tgetflag   get boolean entry for given id
389       tgetnum    get numeric entry for given id
390       tgetstr    get string entry for given id
391       tgoto      apply parameters to given capability
392       tputs      apply padding to capability, calling
393                  a function to put characters
394
395       Early terminfo programs obtained capability values  from  the  TERMINAL
396       structure initialized by setupterm.
397
398       SVr3  extended terminfo by adding functions to retrieve capability val‐
399       ues (like the termcap interface), and reusing tgoto and tputs:
400
401       Function    Description
402       ───────────────────────────────────────────
403       tigetflag   get boolean entry for given id
404
405       tigetnum    get numeric entry for given id
406       tigetstr    get string entry for given id
407
408       SVr3 also replaced several of the SVr2 terminfo functions which had  no
409       counterpart in the termcap interface, documenting them as obsolete:
410
411       Function    Replaced by
412       ─────────────────────────────
413       crmode      cbreak
414       fixterm     reset_prog_mode
415       gettmode    N/A
416       nocrmode    nocbreak
417       resetterm   reset_shell_mode
418       saveterm    def_prog_mode
419       setterm     setupterm
420
421       SVr3  kept  the  mvcur, vidattr and vidputs functions, along with putp,
422       tparm and tputs.  The latter were needed to support padding,  and  han‐
423       dling  functions  such as vidattr (which used more than the two parame‐
424       ters supported by tgoto).
425
426       SVr3 introduced the functions for switching between  terminal  descrip‐
427       tions, e.g., set_curterm.  Some of that was incremental improvements to
428       the SVr2 library:
429
430       •   The TERMINAL type definition was introduced  in  SVr3.01,  for  the
431           term structure provided in SVr2.
432
433       •   The  various  global  variables such as boolnames were mentioned in
434           the programming manual at this point,  though  the  variables  were
435           provided in SVr2.
436
437       SVr4 added the vid_attr and vid_puts functions.
438
439       There are other low-level functions declared in the curses header files
440       on Unix systems, but none were documented.  The functions marked “obso‐
441       lete” remained in use by the Unix vi(1) editor.
442

PORTABILITY

444   Legacy functions
445       X/Open notes that vidattr and vidputs may be macros.
446
447       The  function setterm is not described by X/Open and must be considered
448       non-portable.  All other functions are as described by X/Open.
449
450   Legacy data
451       setupterm copies the terminal name to the array ttytype.  This  is  not
452       part of X/Open Curses, but is assumed by some applications.
453
454       Other  implementions  may not declare the capability name arrays.  Some
455       provide them without declaring them.  X/Open does not specify them.
456
457       Extended terminal capability names, e.g., as defined by tic -x, are not
458       stored in the arrays described here.
459
460   Output buffering
461       Older  versions  of  ncurses assumed that the file descriptor passed to
462       setupterm from initscr or newterm uses buffered I/O, and would write to
463       the  corresponding stream.  In addition to the limitation that the ter‐
464       minal was left in block-buffered mode on exit (like System  V  curses),
465       it  was  problematic  because  ncurses  did not allow a reliable way to
466       cleanup on receiving SIGTSTP.
467
468       The current version (ncurses6) uses output buffers managed directly  by
469       ncurses.  Some of the low-level functions described in this manual page
470       write to the standard output.  They are not signal-safe.  The high-lev‐
471       el functions in ncurses use alternate versions of these functions using
472       the more reliable buffering scheme.
473
474   Function prototypes
475       The X/Open Curses prototypes are based on the SVr4 curses header decla‐
476       rations,  which  were defined at the same time the C language was first
477       standardized in the late 1980s.
478
479       •   X/Open Curses uses const  less  effectively  than  a  later  design
480           might,  in  some cases applying it needlessly to values are already
481           constant, and in most cases overlooking parameters  which  normally
482           would  use const.  Using constant parameters for functions which do
483           not use const may prevent the program from compiling.  On the other
484           hand, writable strings are an obsolescent feature.
485
486           As  an  extension,  this implementation can be configured to change
487           the function prototypes to use the const keyword.  The ncurses  ABI
488           6 enables this feature by default.
489
490       •   X/Open  Curses  prototypes tparm with a fixed number of parameters,
491           rather than a variable argument list.
492
493           This implementation uses a variable argument list, but can be  con‐
494           figured  to  use  the  fixed-parameter list.  Portable applications
495           should provide 9 parameters after the format; zeroes are  fine  for
496           this purpose.
497
498           In  response  to review comments by Thomas E. Dickey, X/Open Curses
499           Issue 7 proposed the tiparm function in mid-2009.
500
501   Special TERM treatment
502       If configured to use the terminal-driver, e.g., for the MinGW port,
503
504setupterm interprets a missing/empty TERM variable as  the  special
505           value “unknown”.
506
507setupterm  allows explicit use of the the windows console driver by
508           checking if $TERM is set to “#win32con” or an abbreviation of  that
509           string.
510
511   Other portability issues
512       In  System  V Release 4, set_curterm has an int return type and returns
513       OK or ERR.  We have chosen to implement the X/Open Curses semantics.
514
515       In System V Release 4, the third argument of tputs  has  the  type  int
516       (*putc)(char).
517
518       At  least one implementation of X/Open Curses (Solaris) returns a value
519       other than OK/ERR from tputs.  That returns the length of  the  string,
520       and does no error-checking.
521
522       X/Open  notes  that after calling mvcur, the curses state may not match
523       the actual terminal state, and that an application should touch and re‐
524       fresh the window before resuming normal curses calls.  Both ncurses and
525       System V Release 4 curses implement mvcur using the SCREEN  data  allo‐
526       cated  in  either  initscr or newterm.  So though it is documented as a
527       terminfo function, mvcur is really a curses function which is not  well
528       specified.
529
530       X/Open  states that the old location must be given for mvcur.  This im‐
531       plementation allows the caller to use -1's for the old  ordinates.   In
532       that case, the old location is unknown.
533

SEE ALSO

535       curses(3X),   curs_initscr(3X),   curs_kernel(3X),   curs_memleaks(3X),
536       curs_termcap(3X), curs_variables(3X), term_variables(3X), putc(3), ter‐
537       minfo(5)
538
539
540
541                                                             curs_terminfo(3X)
Impressum