ncurses 5.9 - patch 20130720
[ncurses.git] / man / curs_terminfo.3x
1 .\"***************************************************************************
2 .\" Copyright (c) 1999-2011,2013 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 .\"                                                                          *
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.43 2013/07/20 19:29:59 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
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
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
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 \fIhc\fP (\fIhardcopy\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 \fIgn\fP (\fIgeneric\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.  The \fIstr\fR must be a terminfo string
253 variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or
254 \fBtgoto\fR.  \fIaffcnt\fR is the number of lines affected, or 1 if
255 not applicable.  \fIputc\fR is a \fBputchar\fR-like routine to which
256 the characters are passed, one at a time.
257 .PP
258 The \fBputp\fR routine calls \fBtputs(\fR\fIstr\fR\fB, 1, putchar)\fR.
259 Note that the output of \fBputp\fR always goes to \fBstdout\fR, not to
260 the \fIfildes\fR specified in \fBsetupterm\fR.
261 .PP
262 The \fBvidputs\fR routine displays the string on the terminal in the
263 video attribute mode \fIattrs\fR, which is any combination of the
264 attributes listed in \fBcurses\fR(3X).  The characters are passed to
265 the \fBputchar\fR-like routine \fIputc\fR.
266 .PP
267 The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except
268 that it outputs through \fBputchar\fR.
269 .PP
270 The \fBvid_attr\fR and \fBvid_puts\fR routines correspond to vidattr and vidputs,
271 respectively.
272 They use a set of arguments for representing the video attributes plus color,
273 i.e.,
274 one of type attr_t for the attributes and one of short for
275 the color_pair number.
276 The \fBvid_attr\fR and \fBvid_puts\fR routines
277 are designed to use the attribute constants with the \fIWA_\fR prefix.
278 The opts argument is reserved for future use.
279 Currently, applications must provide a null pointer for that argument.
280 .PP
281 The \fBmvcur\fR routine provides low-level cursor motion.  It takes
282 effect immediately (rather than at the next refresh).
283 .\" ***************************************************************************
284 .SS Terminal Capability Functions
285 .PP
286 The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return
287 the value of the capability corresponding to the \fBterminfo\fR
288 \fIcapname\fR passed to them, such as \fBxenl\fR.
289 The \fIcapname\fR for each capability is given in the table column entitled
290 \fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n).
291 .PP
292 These routines return special values to denote errors.
293 .PP
294 The \fBtigetflag\fR routine returns
295 .TP
296 \fB\-1\fR
297 if \fIcapname\fR is not a boolean capability,
298 or
299 .TP
300 \fB0\fR
301 if it is canceled or absent from the terminal description.
302 .PP
303 The \fBtigetnum\fR routine returns
304 .TP
305 \fB\-2\fR
306 if \fIcapname\fR is not a numeric capability, or
307 .TP
308 \fB\-1\fR
309 if it is canceled or absent from the terminal description.
310 .PP
311 The \fBtigetstr\fR routine returns
312 .TP
313 \fB(char *)\-1\fR
314 if \fIcapname\fR is not a string capability,
315 or
316 .TP
317 \fB0\fR
318 if it is canceled or absent from the terminal description.
319 .\" ***************************************************************************
320 .SS Terminal Capability Names
321 These null-terminated arrays contain
322 the short terminfo names ("codes"),
323 the \fBtermcap\fR names, and the long terminfo names ("fnames")
324 for each of the predefined \fBterminfo\fR variables:
325 .RS
326 \fBchar *boolnames[]\fR, \fB*boolcodes[]\fR, \fB*boolfnames[]\fR
327 .sp
328 \fBchar *numnames[]\fR, \fB*numcodes[]\fR, \fB*numfnames[]\fR
329 .sp
330 \fBchar *strnames[]\fR, \fB*strcodes[]\fR, \fB*strfnames[]\fR
331 .RE
333 Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
334 (SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
335 completion, unless otherwise noted in the preceding routine descriptions.
336 .PP
337 Routines that return pointers always return \fBNULL\fR on error.
338 .PP
339 X/Open defines no error conditions.
340 In this implementation
341 .RS 5
342 .TP 5
343 \fBdel_curterm\fP
344 returns an error
345 if its terminal parameter is null.
346 .TP 5
347 \fBputp\fP
348 calls \fBtputs\fP, returning the same error-codes.
349 .TP 5
350 \fBrestartterm\fP
351 returns an error
352 if the associated call to \fBsetupterm\fP returns an error.
353 .TP 5
354 \fBsetupterm\fP
355 returns an error
356 if it cannot allocate enough memory, or
357 create the initial windows (stdscr, curscr, newscr).
358 Other error conditions are documented above.
359 .TP 5
360 \fBtputs\fP
361 returns an error if the string parameter is null.
362 It does not detect I/O errors:
363 X/Open states that \fBtputs\fP ignores the return value
364 of the output function \fIputc\fP.
365 .RE
367 X/Open notes that \fBvidattr\fR and \fBvidputs\fR may be macros.
368 .PP
369 The function \fBsetterm\fR is not described by X/Open and must
370 be considered non-portable.
371 All other functions are as described by X/Open.
372 .PP
373 \fBsetupterm\fP copies the terminal name to the array \fBttytype\fP.
374 This is not part of X/Open Curses, but is assumed by some applications.
375 .PP
376 If configured to use the terminal-driver,
377 e.g., for the MinGW port,
378 .bP
379 \fBsetupterm\fP interprets a missing/empty TERM variable as the
380 special value \*(``unknown\*(''.
381 .bP
382 \fBsetupterm\fP allows explicit use of the
383 the windows console driver by checking if $TERM is set to
384 \*(``#win32con\*('' or an abbreviation of that string.
385 .PP
386 Older versions of \fBncurses\fP assumed that the file descriptor passed to
387 \fBsetupterm\fP from \fBinitscr\fP or \fBnewterm\fP uses buffered I/O,
388 and would write to the corresponding stream.
389 In addition to the limitation that the terminal was left in block-buffered
390 mode on exit (like SystemV curses),
391 it was problematic because \fBncurses\fP
392 did not allow a reliable way to cleanup on receiving SIGTSTP.
393 The current version uses output buffers managed directly by \fBncurses\fP.
394 Some of the low-level functions described in this manual page write
395 to the standard output.
396 They are not signal-safe.
397 The high-level functions in \fBncurses\fP use
398 alternate versions of these functions
399 using the more reliable buffering scheme.
400 .PP
401 In System V Release 4, \fBset_curterm\fR has an \fBint\fR return type and
402 returns \fBOK\fR or \fBERR\fR.  We have chosen to implement the X/Open Curses
403 semantics.
404 .PP
405 In System V Release 4, the third argument of \fBtputs\fR has the type
406 \fBint (*putc)(char)\fR.
407 .PP
408 At least one implementation of X/Open Curses (Solaris) returns a value
409 other than OK/ERR from \fBtputs\fP.
410 That returns the length of the string, and does no error-checking.
411 .PP
412 X/Open Curses prototypes \fBtparm\fR with a fixed number of parameters,
413 rather than a variable argument list.
414 This implementation uses a variable argument list, but can be
415 configured to use the fixed-parameter list.
416 Portable applications should provide 9 parameters after the format;
417 zeroes are fine for this purpose.
418 .PP
419 In response to comments by Thomas E. Dickey,
420 X/Open Curses Issue 7 proposed the \fBtiparm\fP function in mid-2009.
421 .PP
422 X/Open notes that after calling \fBmvcur\fR, the curses state may not match the
423 actual terminal state, and that an application should touch and refresh
424 the window before resuming normal curses calls.
425 Both \fBncurses\fP and System V Release 4 curses implement \fBmvcur\fR using
426 the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR.
427 So though it is documented as a terminfo function,
428 \fBmvcur\fR is really a curses function which is not well specified.
429 .PP
430 X/Open states that the old location must be given for \fBmvcur\fP.
431 This implementation allows the caller to use \-1's for the old ordinates.
432 In that case, the old location is unknown.
433 .PP
434 Other implementions may not declare the capability name arrays.
435 Some provide them without declaring them.
436 X/Open does not specify them.
437 .PP
438 Extended terminal capability names, e.g., as defined by \fB@TIC@\ \-x\fP,
439 are not stored in the arrays described here.
441 \fBcurses\fR(3X),
442 \fBcurs_initscr\fR(3X),
443 \fBcurs_kernel\fR(3X),
444 \fBcurs_termcap\fR(3X),
445 \fBcurs_variables\fR(3X),
446 \fBterm_variables\fR(3X),
447 \fBputc\fR(3),
448 \fBterminfo\fR(\*n)