ncurses 6.0 - patch 20170401
[ncurses.git] / man / curs_terminfo.3x
1 .\"***************************************************************************
2 .\" Copyright (c) 1999-2016,2017 Free Software Foundation, Inc.              *
3 .\"                                                                          *
4 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
5 .\" copy of this software and associated documentation files (the            *
6 .\" "Software"), to deal in the Software without restriction, including      *
7 .\" without limitation the rights to use, copy, modify, merge, publish,      *
8 .\" distribute, distribute with modifications, sublicense, and/or sell       *
9 .\" copies of the Software, and to permit persons to whom the Software is    *
10 .\" furnished to do so, subject to the following conditions:                 *
11 .\"                                                                          *
12 .\" The above copyright notice and this permission notice shall be included  *
13 .\" in all copies or substantial portions of the Software.                   *
14 .\"                                                                          *
15 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
16 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
17 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
18 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
19 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
20 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
21 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
22 .\"                                                                          *
23 .\" Except as contained in this notice, the name(s) of the above copyright   *
24 .\" holders shall not be used in advertising or otherwise to promote the     *
25 .\" sale, use or other dealings in this Software without prior written       *
26 .\" authorization.                                                           *
27 .\"***************************************************************************
28 .\"
29 .\" $Id: curs_terminfo.3x,v 1.55 2017/03/31 15:16:15 tom Exp $
30 .TH curs_terminfo 3X ""
31 .ie \n(.g .ds `` \(lq
32 .el       .ds `` ``
33 .ie \n(.g .ds '' \(rq
34 .el       .ds '' ''
35 .de bP
36 .IP \(bu 4
37 ..
38 .ds n 5
39 .na
40 .hy 0
41 .SH NAME
42 \fBdel_curterm\fR,
43 \fBmvcur\fR,
44 \fBputp\fR,
45 \fBrestartterm\fR,
46 \fBset_curterm\fR,
47 \fBsetterm\fR,
48 \fBsetupterm\fR,
49 \fBtigetflag\fR,
50 \fBtigetnum\fR,
51 \fBtigetstr\fR,
52 \fBtiparm\fR,
53 \fBtparm\fR,
54 \fBtputs\fR,
55 \fBvid_attr\fR,
56 \fBvid_puts\fR,
57 \fBvidattr\fR,
58 \fBvidputs\fR \- \fBcurses\fR interfaces to terminfo database
59 .ad
60 .hy
61 .SH SYNOPSIS
62 .nf
63 \fB#include <curses.h>\fR
64 .br
65 \fB#include <term.h>\fR
66 .sp
67 \fBTERMINAL *cur_term;\fR
68 .sp
69 \fBconst char * const boolnames[];\fP
70 \fBconst char * const boolcodes[];\fP
71 \fBconst char * const boolfnames[];\fP
72 \fBconst char * const numnames[];\fP
73 \fBconst char * const numcodes[];\fP
74 \fBconst char * const numfnames[];\fP
75 \fBconst char * const strnames[];\fP
76 \fBconst char * const strcodes[];\fP
77 \fBconst char * const strfnames[];\fP
78 .sp
79 \fBint setupterm(const char *\fR\fIterm\fR\fB, int \fR\fIfiledes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
80 .br
81 \fBint setterm(const char *\fR\fIterm\fR\fB);\fR
82 .br
83 \fBTERMINAL *set_curterm(TERMINAL *\fR\fInterm\fR\fB);\fR
84 .br
85 \fBint del_curterm(TERMINAL *\fR\fIoterm\fR\fB);\fR
86 .br
87 \fBint restartterm(const char *\fR\fIterm\fR\fB, int \fR\fIfiledes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
88 .sp
89 \fBchar *tparm(const char *\fR\fIstr\fR\fB, ...);\fR
90 .br
91 \fBint tputs(const char *\fR\fIstr\fR\fB, int \fR\fIaffcnt\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
92 .br
93 \fBint putp(const char *\fR\fIstr\fR\fB);\fR
94 .sp
95 \fBint vidputs(chtype \fR\fIattrs\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
96 .br
97 \fBint vidattr(chtype \fR\fIattrs\fR\fB);\fR
98 .br
99 \fBint vid_puts(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
100 .br
101 \fBint vid_attr(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB);\fR
102 .sp
103 \fBint mvcur(int \fR\fIoldrow\fR\fB, int \fR\fIoldcol\fR\fB, int \fR\fInewrow\fR, int \fR\fInewcol\fR\fB);\fR
104 .sp
105 \fBint tigetflag(const char *\fR\fIcapname\fR\fB);\fR
106 .br
107 \fBint tigetnum(const char *\fR\fIcapname\fR\fB);\fR
108 .br
109 \fBchar *tigetstr(const char *\fR\fIcapname\fR\fB);\fR
110 .sp
111 \fBchar *tiparm(const char *\fR\fIstr\fR\fB, ...);\fR
112 .br
113 .fi
114 .SH DESCRIPTION
115 These low-level routines must be called by programs that have to deal
116 directly with the \fBterminfo\fR database to handle certain terminal
117 capabilities, such as programming function keys.  For all other
118 functionality, \fBcurses\fR routines are more suitable and their use is
119 recommended.
120 .SS Initialization
121 .PP
122 Initially, \fBsetupterm\fR should be called.
123 The high-level curses functions \fBinitscr\fR and
124 \fBnewterm\fR call \fBsetupterm\fP to initialize the
125 low-level set of terminal-dependent variables
126 [listed in \fBterminfo\fR(\*n)].
127 .PP
128 Applications can use the
129 terminal capabilities either directly (via header definitions),
130 or by special functions.
131 The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this
132 order) to get the definitions for these strings, numbers, and flags.
133 .PP
134 The \fBterminfo\fR variables
135 \fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR as
136 follows:
137 .bP
138 If \fBuse_env(FALSE)\fR has been called, values for
139 \fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used.
140 .bP
141 Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR
142 exist, their values are used.  If these environment variables do not
143 exist and the program is running in a window, the current window size
144 is used.  Otherwise, if the environment variables do not exist, the
145 values for \fBlines\fR and \fBcolumns\fR specified in the
146 \fBterminfo\fR database are used.
147 .PP
148 Parameterized strings should be passed through \fBtparm\fR to instantiate them. 
149 All \fBterminfo\fR strings [including the output of \fBtparm\fR] should be printed
150 with \fBtputs\fR or \fBputp\fR.
151 Call \fBreset_shell_mode\fR to restore the
152 tty modes before exiting [see \fBcurs_kernel\fR(3X)].
153 .PP
154 Programs which use
155 cursor addressing should
156 .bP
157 output \fBenter_ca_mode\fR upon startup and
158 .bP
159 output \fBexit_ca_mode\fR before exiting.
160 .PP
161 Programs which execute shell subprocesses should
162 .bP
163 call \fBreset_shell_mode\fR and
164 output \fBexit_ca_mode\fR before the shell
165 is called and
166 .bP
167 output \fBenter_ca_mode\fR and
168 call \fBreset_prog_mode\fR after returning from the shell.
169 .PP
170 The \fBsetupterm\fR routine reads in the \fBterminfo\fR database,
171 initializing the \fBterminfo\fR structures, but does not set up the
172 output virtualization structures used by \fBcurses\fR.
173 These are its parameters:
174 .RS 3
175 .TP 5
176 \fIterm\fP
177 is the terminal type, a character string.
178 If \fIterm\fR is null, the environment variable \fBTERM\fR is used.
179 .TP 5
180 \fIfiledes\fP
181 is the file descriptor used for all output.
182 .TP 5
183 \fIerrret\fP
184 points to an optional location where an error status can be returned to
185 the caller.
186 If \fIerrret\fR is not null,
187 then \fBsetupterm\fR returns \fBOK\fR or
188 \fBERR\fR and stores a status value in the integer pointed to by
189 \fIerrret\fR.
190 A return value of \fBOK\fR combined with status of \fB1\fR in \fIerrret\fR
191 is normal.
192 .IP
193 If \fBERR\fR is returned, examine \fIerrret\fR:
194 .RS
195 .TP 5
196 .B 1
197 means that the terminal is hardcopy, cannot be used for curses applications.
198 .IP
199 \fBsetupterm\fP determines if the entry is a hardcopy type by
200 checking the \fBhc\fP (\fBhardcopy\fP) capability.
201 .TP 5
202 .B 0
203 means that the terminal could not be found,
204 or that it is a generic type,
205 having too little information for curses applications to run.
206 .IP
207 \fBsetupterm\fP determines if the entry is a generic type by
208 checking the \fBgn\fP (\fBgeneric\fP) capability.
209 .TP 5
210 .B \-1
211 means that the \fBterminfo\fR database could not be found.
212 .RE
213 .IP
214 If \fIerrret\fR is
215 null, \fBsetupterm\fR prints an error message upon finding an error
216 and exits.  Thus, the simplest call is:
217 .sp
218       \fBsetupterm((char *)0, 1, (int *)0);\fR,
219 .sp
220 which uses all the defaults and sends the output to \fBstdout\fR.
221 .RE
222 .PP
223 The \fBsetterm\fR routine was replaced by \fBsetupterm\fR.  The call:
224 .sp
225       \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR
226 .sp
227 provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR.
228 The \fBsetterm\fR routine is provided for BSD compatibility, and
229 is not recommended for new programs.
230 .\" ***************************************************************************
231 .SS The Terminal State
232 .PP
233 The \fBsetupterm\fR routine stores its information about the terminal
234 in a \fBTERMINAL\fP structure pointed to by the global variable \fBcur_term\fP.
235 If it detects an error,
236 or decides that the terminal is unsuitable (hardcopy or generic),
237 it discards this information,
238 making it not available to applications.
239 .PP
240 If \fBsetupterm\fP is called repeatedly for the same terminal type,
241 it will reuse the information.
242 It maintains only one copy of a given terminal's capabilities in memory.
243 If it is called for different terminal types,
244 \fBsetupterm\fP allocates new storage for each set of terminal capabilities.
245 .PP
246 The \fBset_curterm\fR routine sets \fBcur_term\fR to
247 \fInterm\fR, and makes all of the \fBterminfo\fR boolean, numeric, and
248 string variables use the values from \fInterm\fR.
249 It returns the old value of \fBcur_term\fR.
250 .PP
251 The \fBdel_curterm\fR routine frees the space pointed to by
252 \fIoterm\fR and makes it available for further use.  If \fIoterm\fR is
253 the same as \fBcur_term\fR, references to any of the \fBterminfo\fR
254 boolean, numeric, and string variables thereafter may refer to invalid
255 memory locations until another \fBsetupterm\fR has been called.
256 .PP
257 The \fBrestartterm\fR routine is similar to \fBsetupterm\fR and \fBinitscr\fR,
258 except that it is called after restoring memory to a previous state (for
259 example, when reloading a game saved as a core image dump).
260 \fBrestartterm\fP assumes that the windows and the input and output options
261 are the same as when memory was saved,
262 but the terminal type and baud rate may be different.
263 Accordingly, \fBrestartterm\fP saves various tty state bits,
264 calls \fBsetupterm\fP, and then restores the bits.
265 .\" ***************************************************************************
266 .SS Formatting Output
267 .PP
268 The \fBtparm\fR routine instantiates the string \fIstr\fR with
269 parameters \fIpi\fR.  A pointer is returned to the result of \fIstr\fR
270 with the parameters applied.
271 Application developers should keep in mind these quirks of the interface:
272 .bP
273 Although \fBtparm\fP's actual parameters may be integers or strings,
274 the prototype expects \fBlong\fP (integer) values.
275 .bP
276 Aside from the \fBset_attributes\fP (\fBsgr\fP) capability,
277 most terminal capabilities require no more than one or two parameters.
278 .PP
279 \fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI<stdarg.h>\fP
280 rather than a fixed-parameter list.
281 Its numeric parameters are integers (int) rather than longs.
282 .\" ***************************************************************************
283 .SS Output Functions
284 .PP
285 The \fBtputs\fR routine applies padding information to the string
286 \fIstr\fR and outputs it:
287 .bP
288 The \fIstr\fR must be a terminfo string
289 variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or
290 \fBtgoto\fR.
291 .bP
292 \fIaffcnt\fR is the number of lines affected, or 1 if
293 not applicable.
294 .bP
295 \fIputc\fR is a \fBputchar\fR-like routine to which
296 the characters are passed, one at a time.
297 .PP
298 The \fBputp\fR routine calls \fBtputs(\fR\fIstr\fR\fB, 1, putchar)\fR.
299 The output of \fBputp\fR always goes to \fBstdout\fR, rather than
300 the \fIfiledes\fR specified in \fBsetupterm\fR.
301 .PP
302 The \fBvidputs\fR routine displays the string on the terminal in the
303 video attribute mode \fIattrs\fR, which is any combination of the
304 attributes listed in \fBcurses\fR(3X).  The characters are passed to
305 the \fBputchar\fR-like routine \fIputc\fR.
306 .PP
307 The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except
308 that it outputs through \fBputchar\fR.
309 .PP
310 The \fBvid_attr\fR and \fBvid_puts\fR routines correspond to vidattr and vidputs,
311 respectively.
312 They use a set of arguments for representing the video attributes plus color,
313 i.e.,
314 .bP
315 \fIattrs\fP of type \fBattr_t\fP for the attributes and
316 .bP
317 \fIpair\fP of type \fBshort\fP for the color-pair number.
318 .PP
319 The \fBvid_attr\fR and \fBvid_puts\fR routines
320 are designed to use the attribute constants with the \fIWA_\fR prefix.
321 .PP
322 X/Open Curses reserves the \fIopts\fP argument for future use,
323 saying that applications must provide a null pointer for that argument.
324 As an extension,
325 this implementation allows \fIopts\fP to be used as a pointer to \fBint\fP,
326 which overrides the \fIpair\fP (\fBshort\fP) argument.
327 .PP
328 The \fBmvcur\fR routine provides low-level cursor motion.  It takes
329 effect immediately (rather than at the next refresh).
330 .\" ***************************************************************************
331 .SS Terminal Capability Functions
332 .PP
333 The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return
334 the value of the capability corresponding to the \fBterminfo\fR
335 \fIcapname\fR passed to them, such as \fBxenl\fR.
336 The \fIcapname\fR for each capability is given in the table column entitled
337 \fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n).
338 .PP
339 These routines return special values to denote errors.
340 .PP
341 The \fBtigetflag\fR routine returns
342 .TP
343 \fB\-1\fR
344 if \fIcapname\fR is not a boolean capability,
345 or
346 .TP
347 \fB0\fR
348 if it is canceled or absent from the terminal description.
349 .PP
350 The \fBtigetnum\fR routine returns
351 .TP
352 \fB\-2\fR
353 if \fIcapname\fR is not a numeric capability, or
354 .TP
355 \fB\-1\fR
356 if it is canceled or absent from the terminal description.
357 .PP
358 The \fBtigetstr\fR routine returns
359 .TP
360 \fB(char *)\-1\fR
361 if \fIcapname\fR is not a string capability,
362 or
363 .TP
364 \fB0\fR
365 if it is canceled or absent from the terminal description.
366 .\" ***************************************************************************
367 .SS Terminal Capability Names
368 .PP
369 These null-terminated arrays contain
370 .bP
371 the short terminfo names (\*(``codes\*(''),
372 .bP
373 the \fBtermcap\fR names (\*(``names\*('', and
374 .bP
375 the long terminfo names (\*(``fnames\*('')
376 .PP
377 for each of the predefined \fBterminfo\fR variables:
378 .sp
379 .RS
380 \fBconst char *boolnames[]\fR, \fB*boolcodes[]\fR, \fB*boolfnames[]\fR
381 .br
382 \fBconst char *numnames[]\fR, \fB*numcodes[]\fR, \fB*numfnames[]\fR
383 .br
384 \fBconst char *strnames[]\fR, \fB*strcodes[]\fR, \fB*strfnames[]\fR
385 .RE
386 .SH RETURN VALUE
387 Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
388 (SVr4 only specifies \*(``an integer value other than \fBERR\fR\*('') upon successful
389 completion, unless otherwise noted in the preceding routine descriptions.
390 .PP
391 Routines that return pointers always return \fBNULL\fR on error.
392 .PP
393 X/Open defines no error conditions.
394 In this implementation
395 .RS 3
396 .TP 5
397 \fBdel_curterm\fP
398 returns an error
399 if its terminal parameter is null.
400 .TP 5
401 \fBputp\fP
402 calls \fBtputs\fP, returning the same error-codes.
403 .TP 5
404 \fBrestartterm\fP
405 returns an error
406 if the associated call to \fBsetupterm\fP returns an error.
407 .TP 5
408 \fBsetupterm\fP
409 returns an error
410 if it cannot allocate enough memory, or
411 create the initial windows (stdscr, curscr, newscr).
412 Other error conditions are documented above.
413 .TP 5
414 \fBtputs\fP
415 returns an error if the string parameter is null.
416 It does not detect I/O errors:
417 X/Open states that \fBtputs\fP ignores the return value
418 of the output function \fIputc\fP.
419 .RE
420 .SH PORTABILITY
421 .SS Legacy functions
422 .PP
423 X/Open notes that \fBvidattr\fR and \fBvidputs\fR may be macros.
424 .PP
425 The function \fBsetterm\fR is not described by X/Open and must
426 be considered non-portable.
427 All other functions are as described by X/Open.
428 .SS Legacy data
429 .PP
430 \fBsetupterm\fP copies the terminal name to the array \fBttytype\fP.
431 This is not part of X/Open Curses, but is assumed by some applications.
432 .PP
433 Other implementions may not declare the capability name arrays.
434 Some provide them without declaring them.
435 X/Open does not specify them.
436 .PP
437 Extended terminal capability names, e.g., as defined by \fB@TIC@\ \-x\fP,
438 are not stored in the arrays described here.
439 .SS Output buffering
440 .PP
441 Older versions of \fBncurses\fP assumed that the file descriptor passed to
442 \fBsetupterm\fP from \fBinitscr\fP or \fBnewterm\fP uses buffered I/O,
443 and would write to the corresponding stream.
444 In addition to the limitation that the terminal was left in block-buffered
445 mode on exit (like System V curses),
446 it was problematic because \fBncurses\fP
447 did not allow a reliable way to cleanup on receiving SIGTSTP.
448 .PP
449 The current version (ncurses6)
450 uses output buffers managed directly by \fBncurses\fP.
451 Some of the low-level functions described in this manual page write
452 to the standard output.
453 They are not signal-safe.
454 The high-level functions in \fBncurses\fP use
455 alternate versions of these functions
456 using the more reliable buffering scheme.
457 .SS Function prototypes
458 .PP
459 The X/Open Curses prototypes are based on the SVr4 curses header declarations,
460 which were defined at the same time the C language was first standardized in
461 the late 1980s.
462 .bP
463 X/Open Curses uses \fBconst\fP less effectively than a later design might,
464 in some cases applying it needlessly to values are already constant,
465 and in most cases overlooking parameters which normally would use \fBconst\fP.
466 Using constant parameters for functions which do not use \fBconst\fP
467 may prevent the program from compiling.
468 On the other hand, \fIwritable strings\fP are an obsolescent feature.
469 .IP
470 As an extension, this implementation can be configured to change the
471 function prototypes to use the \fBconst\fP keyword.
472 The ncurses ABI 6 enables this feature by default.
473 .bP
474 X/Open Curses prototypes \fBtparm\fR with a fixed number of parameters,
475 rather than a variable argument list.
476 .IP
477 This implementation uses a variable argument list, but can be
478 configured to use the fixed-parameter list.
479 Portable applications should provide 9 parameters after the format;
480 zeroes are fine for this purpose.
481 .IP
482 In response to review comments by Thomas E. Dickey,
483 X/Open Curses Issue 7 proposed the \fBtiparm\fP function in mid-2009.
484 .SS Special TERM treatment
485 .PP
486 If configured to use the terminal-driver,
487 e.g., for the MinGW port,
488 .bP
489 \fBsetupterm\fP interprets a missing/empty TERM variable as the
490 special value \*(``unknown\*(''.
491 .bP
492 \fBsetupterm\fP allows explicit use of the
493 the windows console driver by checking if $TERM is set to
494 \*(``#win32con\*('' or an abbreviation of that string.
495 .SS Other portability issues
496 .PP
497 In System V Release 4, \fBset_curterm\fR has an \fBint\fR return type and
498 returns \fBOK\fR or \fBERR\fR.  We have chosen to implement the X/Open Curses
499 semantics.
500 .PP
501 In System V Release 4, the third argument of \fBtputs\fR has the type
502 \fBint (*putc)(char)\fR.
503 .PP
504 At least one implementation of X/Open Curses (Solaris) returns a value
505 other than OK/ERR from \fBtputs\fP.
506 That returns the length of the string, and does no error-checking.
507 .PP
508 X/Open notes that after calling \fBmvcur\fR, the curses state may not match the
509 actual terminal state, and that an application should touch and refresh
510 the window before resuming normal curses calls.
511 Both \fBncurses\fP and System V Release 4 curses implement \fBmvcur\fR using
512 the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR.
513 So though it is documented as a terminfo function,
514 \fBmvcur\fR is really a curses function which is not well specified.
515 .PP
516 X/Open states that the old location must be given for \fBmvcur\fP.
517 This implementation allows the caller to use \-1's for the old ordinates.
518 In that case, the old location is unknown.
519 .SH SEE ALSO
520 \fBcurses\fR(3X),
521 \fBcurs_initscr\fR(3X),
522 \fBcurs_kernel\fR(3X),
523 \fBcurs_termcap\fR(3X),
524 \fBcurs_variables\fR(3X),
525 \fBterm_variables\fR(3X),
526 \fBputc\fR(3),
527 \fBterminfo\fR(\*n)