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

RETURN VALUE

292       Routines that return an integer return ERR upon failure  and  OK  (SVr4
293       only  specifies “an integer value other than ERR”) upon successful com‐
294       pletion, unless otherwise noted in the preceding routine descriptions.
295
296       Routines that return pointers always return NULL on error.
297
298       X/Open defines no error conditions.  In this implementation
299
300          del_curterm
301               returns an error if its terminal parameter is null.
302
303          putp calls tputs, returning the same error-codes.
304
305          restartterm
306               returns an error if the associated call to setupterm returns an
307               error.
308
309          setupterm
310               returns an error if it cannot allocate enough memory, or create
311               the initial windows (stdscr, curscr, newscr).  Other error con‐
312               ditions are documented above.
313
314          tputs
315               returns  an error if the string parameter is null.  It does not
316               detect I/O errors: X/Open states that tputs ignores the  return
317               value of the output function putc.
318
319   Compatibility macros
320       This  implementation  provides a few macros for compatibility with sys‐
321       tems  before  SVr4  (see  HISTORY).   Those  include  crmode,  fixterm,
322       gettmode, nocrmode, resetterm, saveterm, and setterm.
323
324       In  SVr4,  those  are  found in <curses.h>, but except for setterm, are
325       likewise macros.  The one function, setterm, is mentioned in the manual
326       page.   The  manual page notes that the setterm routine was replaced by
327       setupterm, stating that the call:
328
329             setupterm(term, 1, (int *)0)
330
331       provides the same functionality as setterm(term), and is not recommend‐
332       ed  for  new programs.  This implementation provides each of those sym‐
333       bols as macros for BSD compatibility,
334

HISTORY

336       SVr2 introduced the terminfo feature.  Its programming manual mentioned
337       these low-level functions:
338
339       Function    Description
340       ────────────────────────────────────────────────────────────
341       fixterm     restore tty to “in curses” state
342       gettmode    establish current tty modes
343       mvcur       low level cursor motion
344       putp        utility  function that uses tputs to send char‐
345                   acters via putchar.
346       resetterm   set tty modes to “out of curses” state
347       resetty     reset tty flags to stored value
348       saveterm    save current modes as “in curses” state
349       savetty     store current tty flags
350       setterm     establish terminal with given type
351       setupterm   establish terminal with given type
352       tparm       instantiate a string expression with parameters
353       tputs       apply padding information to a string
354       vidattr     like vidputs, but outputs through putchar
355       vidputs     output a string to put terminal in a  specified
356                   video attribute mode
357
358       The  programming  manual  also mentioned functions provided for termcap
359       compatibility (commenting that they “may go away at a later date”):
360
361       Function   Description
362       ────────────────────────────────────────────────
363       tgetent    look up termcap entry for given name
364       tgetflag   get boolean entry for given id
365       tgetnum    get numeric entry for given id
366       tgetstr    get string entry for given id
367       tgoto      apply parameters to given capability
368       tputs      apply padding to capability, calling
369                  a function to put characters
370
371       Early  terminfo  programs  obtained capability values from the TERMINAL
372       structure initialized by setupterm.
373
374       SVr3 extended terminfo by adding functions to retrieve capability  val‐
375       ues (like the termcap interface), and reusing tgoto and tputs:
376
377       Function    Description
378       ───────────────────────────────────────────
379       tigetflag   get boolean entry for given id
380       tigetnum    get numeric entry for given id
381       tigetstr    get string entry for given id
382
383       SVr3  also replaced several of the SVr2 terminfo functions which had no
384       counterpart in the termcap interface, documenting them as obsolete:
385
386       Function    Replaced by
387       ─────────────────────────────
388       crmode      cbreak
389       fixterm     reset_prog_mode
390       gettmode    N/A
391       nocrmode    nocbreak
392       resetterm   reset_shell_mode
393       saveterm    def_prog_mode
394       setterm     setupterm
395
396       SVr3 kept the mvcur, vidattr and vidputs functions,  along  with  putp,
397       tparm  and  tputs.  The latter were needed to support padding, and han‐
398       dling functions such as vidattr (which used more than the  two  parame‐
399       ters supported by tgoto).
400
401       SVr3  introduced  the functions for switching between terminal descrip‐
402       tions, e.g., set_curterm.  The various global variables such  as  bool‐
403       names were mentioned in the programming manual at this point.
404
405       SVr4 added the vid_attr and vid_puts functions.
406
407       There are other low-level functions declared in the curses header files
408       on Unix systems, but none were documented.  The functions marked “obso‐
409       lete” remained in use by the Unix vi editor.
410

PORTABILITY

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

SEE ALSO

503       curses(3X),    curs_initscr(3X),   curs_kernel(3X),   curs_termcap(3X),
504       curs_variables(3X), term_variables(3X), putc(3), terminfo(5)
505
506
507
508                                                             curs_terminfo(3X)
Impressum