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 must be a terminfo string variable or the return value from
198           tparm, tgetstr, or tgoto.
199
200       ·   affcnt is the number of lines affected, or 1 if not applicable.
201
202       ·   putc  is a putchar-like routine to which the characters are passed,
203           one at a time.
204
205       The putp routine calls tputs(str, 1, putchar).  The output of putp  al‐
206       ways goes to stdout, rather than the filedes specified in setupterm.
207
208       The  vidputs  routine  displays the string on the terminal in the video
209       attribute mode attrs, which is any combination of the attributes listed
210       in  curses(3X).   The characters are passed to the putchar-like routine
211       putc.
212
213       The vidattr routine is like the vidputs routine, except that it outputs
214       through putchar.
215
216       The  vid_attr  and vid_puts routines correspond to vidattr and vidputs,
217       respectively.  They use a set of arguments for representing  the  video
218       attributes plus color, i.e.,
219
220       ·   attrs of type attr_t for the attributes and
221
222       ·   pair of type short for the color-pair number.
223
224       The  vid_attr  and  vid_puts routines are designed to use the attribute
225       constants with the WA_ prefix.
226
227       X/Open Curses reserves the opts argument for future  use,  saying  that
228       applications  must provide a null pointer for that argument.  As an ex‐
229       tension, this implementation allows opts to be used  as  a  pointer  to
230       int, which overrides the pair (short) argument.
231
232       The  mvcur  routine  provides low-level cursor motion.  It takes effect
233       immediately (rather than at the next refresh).
234
235   Terminal Capability Functions
236       The tigetflag, tigetnum and tigetstr routines return the value  of  the
237       capability  corresponding  to the terminfo capname passed to them, such
238       as xenl.  The capname for each capability is given in the table  column
239       entitled capname code in the capabilities section of terminfo(5).
240
241       These routines return special values to denote errors.
242
243       The tigetflag routine returns
244
245       -1     if capname is not a boolean capability, or
246
247       0      if it is canceled or absent from the terminal description.
248
249       The tigetnum routine returns
250
251       -2     if capname is not a numeric capability, or
252
253       -1     if it is canceled or absent from the terminal description.
254
255       The tigetstr routine returns
256
257       (char *)-1
258              if capname is not a string capability, or
259
260       0      if it is canceled or absent from the terminal description.
261
262   Terminal Capability Names
263       These null-terminated arrays contain
264
265       ·   the short terminfo names (“codes”),
266
267       ·   the termcap names (“names”, and
268
269       ·   the long terminfo names (“fnames”)
270
271       for each of the predefined terminfo variables:
272
273              const char *boolnames[], *boolcodes[], *boolfnames[]
274              const char *numnames[], *numcodes[], *numfnames[]
275              const char *strnames[], *strcodes[], *strfnames[]
276

RETURN VALUE

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

PORTABILITY

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

SEE ALSO

397       curses(3X),   curs_initscr(3X),   curs_kernel(3X),    curs_termcap(3X),
398       curs_variables(3X), term_variables(3X), putc(3), terminfo(5)
399
400
401
402                                                             curs_terminfo(3X)
Impressum