| blob | b93947622e3dda12cd952c55f98a1a44aaf8cce9 |
1 .\" $NetBSD: termcap.3,v 1.34 2009/03/03 07:37:48 wiz Exp $
2 .\"
3 .\" Copyright (c) 1980, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)termcap.3 8.2 (Berkeley) 12/11/93
31 .\"
32 .Dd June 13, 2009
33 .Dt TERMCAP 3
34 .Os
35 .Sh NAME
36 .Nm tgetent ,
37 .Nm tgetnum ,
38 .Nm tgetflag ,
39 .Nm tgetstr ,
40 .Nm tgoto ,
41 .Nm tputs
42 .Nd terminal independent operation routines
43 .Sh LIBRARY
44 .Lb libtermcap
45 .Sh SYNOPSIS
46 .In termcap.h
47 .Vt char PC;
48 .Vt char *BC;
49 .Vt char *UP;
50 .Vt short ospeed;
51 .Vt struct tinfo *info;
52 .Ft int
53 .Fn tgetent "char *bp" "const char *name"
54 .Ft int
55 .Fn tgetnum "const char *id"
56 .Ft int
57 .Fn tgetflag "const char *id"
58 .Ft char *
59 .Fn tgetstr "const char *id" "char **area"
60 .Ft char *
61 .Fn tgoto "const char *cm" "int destcol" "int destline"
62 .Ft int
63 .Fn tputs "const char *cp" "int affcnt" "int (*outc)(int)"
64 .Ft int
65 .Fn t_getent "struct tinfo **info" "const char *name"
66 .Ft int
67 .Fn t_getnum "struct tinfo *info" "const char *id"
68 .Ft int
69 .Fn t_getflag "struct tinfo *info" "const char *id"
70 .Ft char *
71 .Fn t_getstr "struct tinfo *info" "const char *id" "char **area" "size_t *limit"
72 .Ft char *
73 .Fn t_agetstr "struct tinfo *info" "const char *id"
74 .Ft int
75 .Fn t_getterm "struct tinfo *info" "char **area" "size_t *limit"
76 .Ft int
77 .Fn t_goto "struct tinfo *info" "const char *id" "int destcol" "int destline" "char *buffer" "size_t limit"
78 .Ft int
79 .Fn t_puts "struct tinfo *info" "const char *cp" "int affcnt" "void (*outc)(char, void *)" "void *args"
80 .Ft void
81 .Fn t_freent "struct tinfo *info"
82 .Ft int
83 .Fn t_setinfo "struct tinfo **info" "const char *entry"
84 .In wchar.h
85 .Ft int
86 .Fn t_putws "struct tinfo *info" "const wchar_t *cp" "int affcnt" "void (*outc)(wchar_t, void *)" "void *args"
87 .Sh DESCRIPTION
88 These functions extract and use capabilities from a terminal capability data
89 base, usually
90 .Pa /usr/share/misc/termcap ,
91 the format of which is described in
92 .Xr termcap 5 .
93 These are low level routines;
94 see
95 .Xr curses 3
96 for a higher level package.
97 .Pp
98 The
99 .Fn tgetent
100 function
101 extracts the entry for terminal
102 .Fa name
103 into the buffer at
104 .Fa bp .
105 The
106 .Fa bp
107 argument
108 should be a character buffer of size
109 1024 and must be retained through all subsequent calls to
110 .Fn tgetnum ,
111 .Fn tgetflag ,
112 and
113 .Fn tgetstr .
114 The
115 .Fn tgetent
116 function
117 returns \-1 if none of the
118 .Nm termcap
119 data base files could be opened,
120 0 if the terminal name given does not have an entry,
121 and 1 if all goes well.
122 It will look in the environment for a
123 .Ev TERMCAP
124 variable.
125 If found, and the value does not begin with a slash, the value does
126 not contain the ZZ capability (see
127 .Em NOTES
128 for a description of this capability),
129 and the terminal type
130 .Fa name
131 is the same as the environment string
132 .Ev TERM ,
133 the
134 .Ev TERMCAP
135 string is used instead of reading a
136 .Nm termcap
137 file.
138 If the value does contain the ZZ capability then the
139 .Ev TERM
140 environment string is used to read
141 .Nm termcap ,
142 if the read fails for any reason the value of
143 .Ev TERMCAP
144 will be used despite it containing ZZ.
145 If
146 .Ev TERMCAP
147 does begin with a slash, the string is used as a path name
148 of the
149 .Nm termcap
150 file to search.
151 If
152 .Ev TERMCAP
153 does not begin with a slash and
154 .Fa name
155 is different from
156 .Ev TERM ,
157 .Fn tgetent
158 searches the files
159 .Pa $HOME/.termcap
160 and
161 .Pa /usr/share/misc/termcap ,
162 in that order, unless the environment variable
163 .Ev TERMPATH
164 exists,
165 in which case it specifies a list of file pathnames
166 (separated by spaces or colons) to be searched instead.
167 Whenever multiple files are searched and a
168 .Sy tc
169 field occurs in the requested entry, the entry it names must be found
170 in the same file or one of the succeeding files.
171 This can speed up entry into programs that call
172 .Fn tgetent ,
173 as well as help debug new terminal descriptions
174 or make one for your terminal if you can't write the file
175 .Pa /usr/share/misc/termcap .
176 .Pp
177 The
178 .Fn tgetnum
179 function
180 gets the numeric value of capability
181 .Fa id ,
182 returning \-1 if it is not given for the terminal.
183 The
184 .Fn tgetflag
185 function
186 returns 1 if the specified capability is present in
187 the terminal's entry, 0 if it is not.
188 The
189 .Fn tgetstr
190 function
191 returns the string value of the capability
192 .Fa id ;
193 if
194 .Fa area
195 does not point to
196 .Dv NULL
197 and does not point to a pointer to
198 .Dv NULL ,
199 it copies the string value into the buffer pointed to by
200 .Fa *area ,
201 and advances the
202 .Fa *area
203 pointer past the copy of the string.
204 It decodes the abbreviations for this field described in
205 .Xr termcap 5 ,
206 except for cursor addressing and padding information.
207 The
208 .Fn tgetstr
209 function
210 returns
211 .Dv NULL
212 if the capability was not found.
213 .Pp
214 The
215 .Fn tgoto
216 function
217 returns a cursor addressing string decoded from
218 .Fa cm
219 to go to column
220 .Fa destcol
221 in line
222 .Fa destline .
223 It uses the external variables
224 .Va UP
225 (from the
226 .Sy up
227 capability)
228 and
229 .Va BC
230 (if
231 .Sy bc
232 is given rather than
233 .Sy bs )
234 if necessary to avoid placing
235 .Sy \en ,
236 .Sy ^D
237 or
238 .Sy ^@
239 in
240 the returned string.
241 (Programs which call
242 .Fn tgoto
243 should be sure to turn off the
244 .Dv XTABS
245 bit(s),
246 since
247 .Fn tgoto
248 may now output a tab.
249 Note that programs using termcap should in general turn off
250 .Dv XTABS
251 anyway since some terminals use control-I for other functions,
252 such as nondestructive space.)
253 If a
254 .Sy %
255 sequence is given which is not understood, then
256 .Fn tgoto
257 returns
258 .Pq Dv OOPS .
259 .Pp
260 The
261 .Fn tputs
262 function
263 decodes the leading padding information of the string
264 .Fa cp ;
265 .Fa affcnt
266 gives the number of lines affected by the operation, or 1 if this is
267 not applicable,
268 .Fa outc
269 is a routine which is called with each character in turn.
270 The external variable
271 .Va ospeed
272 should contain the output speed of the terminal as encoded by
273 .Xr stty 3 .
274 The external variable
275 .Va PC
276 should contain a pad character to be used (from the
277 .Sy pc
278 capability)
279 if a null
280 .Pq Sy ^@
281 is inappropriate.
282 .Pp
283 The
284 .Fn t_getent
285 function operates in a similar manner to the
286 .Fn tgetent
287 function excepting that the
288 .Fa info
289 argument is a pointer to a pointer of the opaque type
290 .Va tinfo .
291 If the call to
292 .Fn t_getent
293 succeeds then the argument
294 .Fa info
295 will be updated with the address of an object that contains the termcap
296 entry.
297 This pointer can then be passed to calls of
298 .Fn t_getnum ,
299 .Fn t_getflag
300 and
301 .Fn t_getstr .
302 When the information pointed to by
303 .Fa info
304 is no longer required any storage associated with the object can be
305 released by calling
306 .Fn t_freent .
307 .Pp
308 The functions
309 .Fn t_getnum
310 and
311 .Fn t_getflag
312 operate in the same manner as
313 .Fn tgetnum
314 and
315 .Fn tgetflag
316 with the exception that the pointer to the termcap object is passed along
317 with the id of the capability required.
318 .Pp
319 The function
320 .Fn t_getstr
321 performs the same function as
322 .Fn tgetstr
323 but has a
324 .Fa limit
325 parameter that gives the number of characters that can be inserted in to
326 the array pointed to by
327 .Fa area .
328 The
329 .Fa limit
330 argument is updated by the
331 .Fn t_getstr
332 call to give the number of characters that remain available in
333 .Fa area .
334 If the t_getstr call fails then
335 .Dv NULL
336 will be returned and errno set to indicate the failure,
337 .Er ENOENT
338 indicates there was no termcap entry for the given
339 .Fa id ,
340 .Er E2BIG
341 indicates the retrieved entry would have overflowed
342 .Fa area .
343 If t_getstr is called with
344 .Fa area
345 being
346 .Dv NULL
347 then the size required to hold the capability string will be returned in
348 .Fa limit
349 so the caller can allocate enough storage to hold the capability.
350 .Pp
351 The function
352 .Fn t_agetstr
353 performs the same function as
354 .Fn t_getstr
355 except it handles memory allocation automatically.
356 The memory that
357 .Fn t_agetstr
358 allocates will be freed when
359 .Fn t_freent
360 is called.
361 .Pp
362 The function
363 .Fn t_getterm
364 returns a copy of the termcap name string of the termcap entry
365 associated with
366 .Fa info
367 in the buffer pointed to by
368 .Fa area .
369 .Fn t_getterm
370 returns 0 on success and \-1 on error.
371 On error errno will be set to
372 .Er EINVAL
373 if the termcap entry in
374 .Fa info
375 is malformed or
376 .Er E2BIG
377 if the size of the name exceeds the size specified by
378 .Fa limit .
379 If
380 .Fa area
381 is
382 .Dv NULL
383 then the size required to hold the terminal name will be returned in
384 .Fa limit
385 allowing sufficient storage to be allocated.
386 If
387 .Fa limit
388 is
389 .Dv NULL
390 then no bounds checking will be performed.
391 .Pp
392 The
393 .Fn t_goto
394 function is the same as the
395 .Fn tgoto
396 function excepting that the capabilities for
397 .Sy up
398 and
399 .Sy bc
400 are extracted from the
401 .Fa info
402 object and that the string formed by
403 .Fn t_goto
404 is placed in the
405 .Fa buffer
406 argument, the number of characters allowed to be placed in
407 .Fa buffer
408 is controlled by
409 .Fa limit .
410 If the expansion performed by
411 .Fn t_goto
412 would exceed the space in
413 .Fa buffer
414 then
415 .Fn t_goto
416 will return \-1 and set errno to
417 .Er E2BIG .
418 The function
419 .Fn t_puts
420 is similar to the
421 .Fn tputs
422 function excepting that
423 .Fa info
424 holds a pointer to the termcap object that was returned by a previous
425 .Fn t_getent
426 call, this object will be used to retrieve the
427 .Sy pc
428 attribute for the terminal.
429 The function
430 .Fn t_putws
431 is similar to
432 .Fn t_puts
433 but it operates on a string of wide characters.
434 The
435 .Fa outc
436 function is a pointer to a function that will be called by
437 .Fn t_puts
438 to output each character in the
439 .Fa cp
440 string.
441 The
442 .Fa outc
443 function will be called with two parameters.
444 The first is the character
445 to be printed and the second is an optional argument that was passed to
446 .Fn t_puts
447 in the
448 .Fa args
449 argument.
450 The interpretation of the contents of
451 .Fa args
452 is dependent solely on the implementation of
453 .Fa outc .
454 .Pp
455 The
456 .Fn t_setinfo
457 function allows the termcap entry contained in the
458 .Fa entry
459 string to be inserted into the
460 .Fa info
461 structure.
462 Memory sufficient to hold the contents of
463 .Fa entry
464 is automatically allocated.
465 This allows the programmer to provide a fail over terminal capability
466 string if fetching the termcap entry from the termcap database fails.
467 The format of the string
468 .Fa entry
469 is assumed to be a valid termcap entry.
470 .Pp
471 NOTE: For termcap entries that are larger than 1023 bytes a special
472 capability of
473 .Fa ZZ
474 is added to the end of the termcap entry retrieved.
475 The number that follows this entry is the address of the buffer allocated
476 to hold the full termcap entry.
477 The caller may retrieve the pointer to the extended buffer by performing a
478 .Fn tgetstr
479 to retrieve the
480 .Fa ZZ
481 capability, the string is the output of a
482 .Fn printf
483 %p and may be converted back to a pointer using
484 .Fn sscanf
485 or similar.
486 The ZZ capability is only necessary if the caller wishes to
487 directly manipulate the termcap entry, all the termcap function calls
488 automatically use the extended buffer to retrieve terminal capabilities.
489 .Sh FILES
490 .Bl -tag -width /usr/share/misc/termcap -compact
491 .It Pa /usr/lib/libtermcap.a
492 .Fl l Ar termcap
493 library (also known as
494 .Fl l Ar termlib )
495 .It Pa /usr/share/misc/termcap
496 standard terminal capability data base
497 .It Pa $HOME/.termcap
498 user's terminal capability data base
499 .El
500 .Sh SEE ALSO
501 .Xr ex 1 ,
502 .Xr curses 3 ,
503 .Xr termcap 5
504 .Sh HISTORY
505 The
506 .Nm termcap
507 t_*() functions appeared in
508 .Nx 1.5 .
509 The rest of the
510 .Nm termcap
511 functions appeared in
512 .Bx 4.0 .