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