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

PORTABILITY

310   Legacy functions
311       X/Open notes that vidattr and vidputs may be macros.
312
313       The function setterm is not described by X/Open and must be  considered
314       non-portable.  All other functions are as described by X/Open.
315
316   Legacy data
317       setupterm  copies  the terminal name to the array ttytype.  This is not
318       part of X/Open Curses, but is assumed by some applications.
319
320       Other implementions may not declare the capability name  arrays.   Some
321       provide them without declaring them.  X/Open does not specify them.
322
323       Extended terminal capability names, e.g., as defined by tic -x, are not
324       stored in the arrays described here.
325
326   Output buffering
327       Older versions of ncurses assumed that the file  descriptor  passed  to
328       setupterm from initscr or newterm uses buffered I/O, and would write to
329       the corresponding stream.  In addition to the limitation that the  ter‐
330       minal  was  left in block-buffered mode on exit (like System V curses),
331       it was problematic because ncurses did not  allow  a  reliable  way  to
332       cleanup on receiving SIGTSTP.
333
334       The  current version (ncurses6) uses output buffers managed directly by
335       ncurses.  Some of the low-level functions described in this manual page
336       write to the standard output.  They are not signal-safe.  The high-lev‐
337       el functions in ncurses use alternate versions of these functions using
338       the more reliable buffering scheme.
339
340   Function prototypes
341       The X/Open Curses prototypes are based on the SVr4 curses header decla‐
342       rations, which were defined at the same time the C language  was  first
343       standardized in the late 1980s.
344
345       ·   X/Open  Curses  uses  const  less  effectively  than a later design
346           might, in some cases applying it needlessly to values  are  already
347           constant,  and  in most cases overlooking parameters which normally
348           would use const.  Using constant parameters for functions which  do
349           not use const may prevent the program from compiling.  On the other
350           hand, writable strings are an obsolescent feature.
351
352           As an extension, this implementation can be  configured  to  change
353           the  function prototypes to use the const keyword.  The ncurses ABI
354           6 enables this feature by default.
355
356       ·   X/Open Curses prototypes tparm with a fixed number  of  parameters,
357           rather than a variable argument list.
358
359           This  implementation uses a variable argument list, but can be con‐
360           figured to use the  fixed-parameter  list.   Portable  applications
361           should  provide  9 parameters after the format; zeroes are fine for
362           this purpose.
363
364           In response to review comments by Thomas E. Dickey,  X/Open  Curses
365           Issue 7 proposed the tiparm function in mid-2009.
366
367   Special TERM treatment
368       If configured to use the terminal-driver, e.g., for the MinGW port,
369
370       ·   setupterm  interprets  a missing/empty TERM variable as the special
371           value “unknown”.
372
373       ·   setupterm allows explicit use of the the windows console driver  by
374           checking  if $TERM is set to “#win32con” or an abbreviation of that
375           string.
376
377   Other portability issues
378       In System V Release 4, set_curterm has an int return type  and  returns
379       OK or ERR.  We have chosen to implement the X/Open Curses semantics.
380
381       In  System  V  Release  4, the third argument of tputs has the type int
382       (*putc)(char).
383
384       At least one implementation of X/Open Curses (Solaris) returns a  value
385       other  than  OK/ERR from tputs.  That returns the length of the string,
386       and does no error-checking.
387
388       X/Open notes that after calling mvcur, the curses state may  not  match
389       the actual terminal state, and that an application should touch and re‐
390       fresh the window before resuming normal curses calls.  Both ncurses and
391       System  V  Release 4 curses implement mvcur using the SCREEN data allo‐
392       cated in either initscr or newterm.  So though it is  documented  as  a
393       terminfo  function, mvcur is really a curses function which is not well
394       specified.
395
396       X/Open states that the old location must be given for mvcur.  This  im‐
397       plementation  allows  the caller to use -1's for the old ordinates.  In
398       that case, the old location is unknown.
399

SEE ALSO

401       curses(3X),   curs_initscr(3X),   curs_kernel(3X),    curs_termcap(3X),
402       curs_variables(3X), term_variables(3X), putc(3), terminfo(5)
403
404
405
406                                                             curs_terminfo(3X)
Impressum