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

NAME

6       del_curterm, mvcur, putp, restartterm, set_curterm, setterm, 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       int setterm(const char *term);
28       TERMINAL *set_curterm(TERMINAL *nterm);
29       int del_curterm(TERMINAL *oterm);
30       int restartterm(const char *term, int filedes, int *errret);
31
32       char *tparm(const char *str, ...);
33       int tputs(const char *str, int affcnt, int (*putc)(int));
34       int putp(const char *str);
35
36       int vidputs(chtype attrs, int (*putc)(int));
37       int vidattr(chtype attrs);
38       int vid_puts(attr_t attrs, short pair, void *opts, int (*putc)(int));
39       int vid_attr(attr_t attrs, short pair, void *opts);
40
41       int mvcur(int oldrow, int oldcol, int newrow, int newcol);
42
43       int tigetflag(const char *capname);
44       int tigetnum(const char *capname);
45       char *tigetstr(const char *capname);
46
47       char *tiparm(const char *str, ...);
48

DESCRIPTION

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

RETURN VALUE

282       Routines  that  return  an integer return ERR upon failure and OK (SVr4
283       only specifies “an integer value other than ERR”) upon successful  com‐
284       pletion, unless otherwise noted in the preceding routine descriptions.
285
286       Routines that return pointers always return NULL on error.
287
288       X/Open defines no error conditions.  In this implementation
289
290          del_curterm
291               returns an error if its terminal parameter is null.
292
293          putp calls tputs, returning the same error-codes.
294
295          restartterm
296               returns an error if the associated call to setupterm returns an
297               error.
298
299          setupterm
300               returns an error if it cannot allocate enough memory, or create
301               the initial windows (stdscr, curscr, newscr).  Other error con‐
302               ditions are documented above.
303
304          tputs
305               returns an error if the string parameter is null.  It does  not
306               detect  I/O errors: X/Open states that tputs ignores the return
307               value of the output function putc.
308

HISTORY

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

PORTABILITY

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

SEE ALSO

477       curses(3X),    curs_initscr(3X),   curs_kernel(3X),   curs_termcap(3X),
478       curs_variables(3X), term_variables(3X), putc(3), terminfo(5)
479
480
481
482                                                             curs_terminfo(3X)
Impressum