d5c9bf68275baddcdde584601f7995ccbda17e4a
[ncurses.git] / man / curs_terminfo.3x
1 .\"***************************************************************************
2 .\" Copyright (c) 1999-2002,2003 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.18 2003/12/27 18:48:59 tom Exp $
30 .TH curs_terminfo 3X ""
31 .ds n 5
32 .SH NAME
33 \fBdel_curterm\fR,
34 \fBmvcur\fR,
35 \fBputp\fR,
36 \fBrestartterm\fR,
37 \fBset_curterm\fR,
38 \fBsetterm\fR,
39 \fBsetupterm\fR,
40 \fBtigetflag\fR,
41 \fBtigetnum\fR,
42 \fBtigetstr\fR,
43 \fBtparm\fR,
44 \fBtputs\fR,
45 \fBvid_attr\fR,
46 \fBvid_puts\fR,
47 \fBvidattr\fR,
48 \fBvidputs\fR - \fBcurses\fR interfaces to terminfo database
49 .SH SYNOPSIS
50 .nf
51 \fB#include <curses.h>\fR
52 .br
53 \fB#include <term.h>\fR
54 .PP
55 \fBint setupterm(char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
56 .br
57 \fBint setterm(char *\fR\fIterm\fR\fB);\fR
58 .br
59 \fBTERMINAL *set_curterm(TERMINAL *\fR\fInterm\fR\fB);\fR
60 .br
61 \fBint del_curterm(TERMINAL *\fR\fIoterm\fR\fB);\fR
62 .br
63 \fBint restartterm(const char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
64 .br
65 \fBchar *tparm(char *\fR\fIstr\fR\fB, ...);\fR
66 .br
67 \fBint tputs(const char *\fR\fIstr\fR\fB, int \fR\fIaffcnt\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
68 .br
69 \fBint putp(const char *\fR\fIstr\fR\fB);\fR
70 .br
71 \fBint vidputs(chtype \fR\fIattrs\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
72 .br
73 \fBint vidattr(chtype \fR\fIattrs\fR\fB);\fR
74 .br
75 \fBint vid_puts(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB, int (*\fR\fIputc\fR\fB)(char));\fR
76 .br
77 \fBint vid_attr(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB);\fR
78 .br
79 \fBint mvcur(int \fR\fIoldrow\fR\fB, int \fR\fIoldcol\fR\fB, int \fR\fInewrow\fR, int \fR\fInewcol\fR\fB);\fR
80 .br
81 \fBint tigetflag(char *\fR\fIcapname\fR\fB);\fR
82 .br
83 \fBint tigetnum(char *\fR\fIcapname\fR\fB);\fR
84 .br
85 \fBchar *tigetstr(char *\fR\fIcapname\fR\fB);\fR
86 .br
87 .fi
88 .SH DESCRIPTION
89 These low-level routines must be called by programs that have to deal
90 directly with the \fBterminfo\fR database to handle certain terminal
91 capabilities, such as programming function keys.  For all other
92 functionality, \fBcurses\fR routines are more suitable and their use is
93 recommended.
94 .PP
95 Initially, \fBsetupterm\fR should be called.  Note that
96 \fBsetupterm\fR is automatically called by \fBinitscr\fR and
97 \fBnewterm\fR.  This defines the set of terminal-dependent variables
98 [listed in \fBterminfo\fR(\*n)].  The \fBterminfo\fR variables
99 \fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR as
100 follows: If \fBuse_env(FALSE)\fR has been called, values for
101 \fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used.
102 Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR
103 exist, their values are used.  If these environment variables do not
104 exist and the program is running in a window, the current window size
105 is used.  Otherwise, if the environment variables do not exist, the
106 values for \fBlines\fR and \fBcolumns\fR specified in the
107 \fBterminfo\fR database are used.
108 .PP
109 The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this
110 order) to get the definitions for these strings, numbers, and flags.
111 Parameterized strings should be passed through \fBtparm\fR to instantiate them. 
112 All \fBterminfo\fR strings [including the output of \fBtparm\fR] should be printed
113 with \fBtputs\fR or \fBputp\fR.  Call the \fBreset_shell_mode\fR to restore the
114 tty modes before exiting [see \fBcurs_kernel\fR(3X)].  Programs which use
115 cursor addressing should output \fBenter_ca_mode\fR upon startup and should
116 output \fBexit_ca_mode\fR before exiting.  Programs desiring shell escapes
117 should call
118 .PP
119 \fBreset_shell_mode\fR and output \fBexit_ca_mode\fR before the shell
120 is called and should output \fBenter_ca_mode\fR and call
121 \fBreset_prog_mode\fR after returning from the shell.
122 .PP
123 The \fBsetupterm\fR routine reads in the \fBterminfo\fR database,
124 initializing the \fBterminfo\fR structures, but does not set up the
125 output virtualization structures used by \fBcurses\fR.  The terminal
126 type is the character string \fIterm\fR; if \fIterm\fR is null, the
127 environment variable \fBTERM\fR is used.
128 All output is to file descriptor \fBfildes\fR which is initialized for output.
129 If \fIerrret\fR is not null,
130 then \fBsetupterm\fR returns \fBOK\fR or
131 \fBERR\fR and stores a status value in the integer pointed to by
132 \fIerrret\fR.
133 A return value of \fBOK\fR combined with status of \fB1\fR in \fIerrret\fR
134 is normal.
135 If \fBERR\fR is returned, examine \fIerrret\fR:
136 .RS
137 .TP 5
138 .B 1
139 means that the terminal is hardcopy, cannot be used for curses applications.
140 .TP 5
141 .B 0
142 means that the terminal could not be found,
143 or that it is a generic type,
144 having too little information for curses applications to run.
145 .TP 5
146 .B -1
147 means that the \fBterminfo\fR database could not be found.
148 .RE
149 .PP
150 If \fIerrret\fR is
151 null, \fBsetupterm\fR prints an error message upon finding an error
152 and exits.  Thus, the simplest call is:
153
154       \fBsetupterm((char *)0, 1, (int *)0);\fR,
155
156 which uses all the defaults and sends the output to \fBstdout\fR.
157 .PP
158 The \fBsetterm\fR routine is being replaced by \fBsetupterm\fR.  The call:
159
160       \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR
161
162 provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR.
163 The \fBsetterm\fR routine is included here for BSD compatibility, and
164 is not recommended for new programs.
165 .PP
166 The \fBset_curterm\fR routine sets the variable \fBcur_term\fR to
167 \fInterm\fR, and makes all of the \fBterminfo\fR boolean, numeric, and
168 string variables use the values from \fInterm\fR.  It returns the old value
169 of \fBcur_term\fR.
170 .PP
171 The \fBdel_curterm\fR routine frees the space pointed to by
172 \fIoterm\fR and makes it available for further use.  If \fIoterm\fR is
173 the same as \fBcur_term\fR, references to any of the \fBterminfo\fR
174 boolean, numeric, and string variables thereafter may refer to invalid
175 memory locations until another \fBsetupterm\fR has been called.
176 .PP
177 The \fBrestartterm\fR routine is similar to \fBsetupterm\fR and \fBinitscr\fR,
178 except that it is called after restoring memory to a previous state (for
179 example, when reloading a game saved as a core image dump).  It assumes that
180 the windows and the input and output options are the same as when memory was
181 saved, but the terminal type and baud rate may be different.  Accordingly,
182 it saves various tty state bits, does a setupterm, and then restores the bits.
183 .PP
184 The \fBtparm\fR routine instantiates the string \fIstr\fR with
185 parameters \fIpi\fR.  A pointer is returned to the result of \fIstr\fR
186 with the parameters applied.
187 .PP
188 The \fBtputs\fR routine applies padding information to the string
189 \fIstr\fR and outputs it.  The \fIstr\fR must be a terminfo string
190 variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or
191 \fBtgoto\fR.  \fIaffcnt\fR is the number of lines affected, or 1 if
192 not applicable.  \fIputc\fR is a \fBputchar\fR-like routine to which
193 the characters are passed, one at a time.
194 .PP
195 The \fBputp\fR routine calls \fBtputs(\fR\fIstr\fR\fB, 1, putchar)\fR.
196 Note that the output of \fBputp\fR always goes to \fBstdout\fR, not to
197 the \fIfildes\fR specified in \fBsetupterm\fR.
198 .PP
199 The \fBvidputs\fR routine displays the string on the terminal in the
200 video attribute mode \fIattrs\fR, which is any combination of the
201 attributes listed in \fBcurses\fR(3X).  The characters are passed to
202 the \fBputchar\fR-like routine \fIputc\fR.
203 .PP
204 The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except
205 that it outputs through \fBputchar\fR.
206 .PP
207 The \fBvid_attr\fR and \fBvid_puts\fR routines correspond to vidattr and vidputs,
208 respectively.
209 They use a set of arguments for representing the video attributes plus color,
210 i.e.,
211 one of type attr_t for the attributes and one of short for
212 the color_pair number.
213 The \fBvid_attr\fR and \fBvid_puts\fR routines
214 are designed to use the attribute constants with the \fIWA_\fR prefix.
215 The opts argument is reserved for future use.
216 Currently, applications must provide a null pointer for that argument.
217 .PP
218 The \fBmvcur\fR routine provides low-level cursor motion.  It takes
219 effect immediately (rather than at the next refresh).
220 .PP
221 The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return
222 the value of the capability corresponding to the \fBterminfo\fR
223 \fIcapname\fR passed to them, such as \fBxenl\fR.
224 .PP
225 The \fBtigetflag\fR routine returns the value \fB-1\fR if
226 \fIcapname\fR is not a boolean capability,
227 or \fB0\fR if it is canceled or absent from the terminal description.
228 .PP
229 The \fBtigetnum\fR routine returns the value \fB-2\fR if
230 \fIcapname\fR is not a numeric capability,
231 or \fB-1\fR if it is canceled or absent from the terminal description.
232 .PP
233 The \fBtigetstr\fR routine returns the value \fB(char *)-1\fR
234 if \fIcapname\fR is not a string capability,
235 or \fB0\fR if it is canceled or absent from the terminal description.
236 .PP
237 The \fIcapname\fR for each capability is given in the table column entitled
238 \fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n).
239
240 \fBchar *boolnames\fR, \fB*boolcodes\fR, \fB*boolfnames\fR
241
242 \fBchar *numnames\fR, \fB*numcodes\fR, \fB*numfnames\fR
243
244 \fBchar *strnames\fR, \fB*strcodes\fR, \fB*strfnames\fR
245
246 These null-terminated arrays contain the \fIcapnames\fR, the
247 \fBtermcap\fR codes, and the full C names, for each of the
248 \fBterminfo\fR variables.
249 .SH RETURN VALUE
250 Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
251 (SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
252 completion, unless otherwise noted in the preceding routine descriptions.
253 .PP
254 Routines that return pointers always return \fBNULL\fR on error.
255 .SH NOTES
256 The \fBsetupterm\fR routine should be used in place of \fBsetterm\fR.
257 It may be useful when you want to test for terminal capabilities without
258 committing to the allocation of storage involved in \fBinitscr\fR.
259 .PP
260 Note that \fBvidattr\fR and \fBvidputs\fR may be macros.
261 .SH PORTABILITY
262 The function \fBsetterm\fR is not described in the XSI Curses standard and must
263 be considered non-portable.  All other functions are as described in the XSI
264 curses standard.
265 .PP
266 In System V Release 4, \fBset_curterm\fR has an \fBint\fR return type and
267 returns \fBOK\fR or \fBERR\fR.  We have chosen to implement the XSI Curses
268 semantics.
269 .PP
270 In System V Release 4, the third argument of \fBtputs\fR has the type
271 \fBint (*putc)(char)\fR.
272 .PP
273 The XSI Curses standard prototypes \fBtparm\fR with a fixed number of parameters,
274 rather than a variable argument list.
275 This implementation uses a variable argument list.
276 Portable applications should provide 9 parameters after the format;
277 zeroes are fine for this purpose.
278 .PP
279 XSI notes that after calling \fBmvcur\fR, the curses state may not match the
280 actual terminal state, and that an application should touch and refresh
281 the window before resuming normal curses calls.
282 Both ncurses and System V Release 4 curses implement \fBmvcur\fR using
283 the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR.
284 So though it is documented as a terminfo function,
285 \fBmvcur\fR is really a curses function which is not well specified.
286 .SH SEE ALSO
287 \fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_termcap\fR(3X),
288 \fBputc\fR(3S), \fBterminfo\fR(\*n)
289 .\"#
290 .\"# The following sets edit modes for GNU EMACS
291 .\"# Local Variables:
292 .\"# mode:nroff
293 .\"# fill-column:79
294 .\"# End: