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