Annotation of src/lib/libterm/termcap.3, Revision 1.32
1.32 ! kleink 1: .\" $NetBSD: termcap.3,v 1.31 2005/05/15 21:11:13 christos Exp $
1.4 cgd 2: .\"
3: .\" Copyright (c) 1980, 1991, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 cgd 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.
1.29 agc 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 cgd 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: .\"
1.4 cgd 30: .\" @(#)termcap.3 8.2 (Berkeley) 12/11/93
1.1 cgd 31: .\"
1.32 ! kleink 32: .Dd December 17, 2006
1.1 cgd 33: .Dt TERMCAP 3
1.11 garbled 34: .Os
1.1 cgd 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
1.9 perry 43: .Sh LIBRARY
44: .Lb libtermcap
1.1 cgd 45: .Sh SYNOPSIS
1.28 wiz 46: .In termcap.h
1.1 cgd 47: .Vt char PC;
48: .Vt char *BC;
49: .Vt char *UP;
50: .Vt short ospeed;
1.13 blymn 51: .Vt struct tinfo *info;
1.8 lukem 52: .Ft int
1.26 pooka 53: .Fn tgetent "char *bp" "const char *name"
1.8 lukem 54: .Ft int
1.26 pooka 55: .Fn tgetnum "const char *id"
1.8 lukem 56: .Ft int
1.26 pooka 57: .Fn tgetflag "const char *id"
1.1 cgd 58: .Ft char *
1.26 pooka 59: .Fn tgetstr "const char *id" "char **area"
1.1 cgd 60: .Ft char *
1.26 pooka 61: .Fn tgoto "const char *cm" "int destcol" "int destline"
1.5 pk 62: .Ft void
1.26 pooka 63: .Fn tputs "const char *cp" "int affcnt" "int (*outc)(int)"
1.13 blymn 64: .Ft int
1.26 pooka 65: .Fn t_getent "struct tinfo **info" "const char *name"
1.13 blymn 66: .Ft int
1.26 pooka 67: .Fn t_getnum "struct tinfo *info" "const char *id"
1.13 blymn 68: .Ft int
1.26 pooka 69: .Fn t_getflag "struct tinfo *info" "const char *id"
1.13 blymn 70: .Ft char *
1.26 pooka 71: .Fn t_getstr "struct tinfo *info" "const char *id" "char **area" "size_t *limit"
1.19 blymn 72: .Ft char *
1.26 pooka 73: .Fn t_agetstr "struct tinfo *info" "const char *id"
1.13 blymn 74: .Ft int
1.17 blymn 75: .Fn t_getterm "struct tinfo *info" "char **area" "size_t *limit"
76: .Ft int
1.26 pooka 77: .Fn t_goto "struct tinfo *info" "const char *id" "int destcol" "int destline" "char *buffer" "size_t limit"
1.13 blymn 78: .Ft int
1.26 pooka 79: .Fn t_puts "struct tinfo *info" "const char *cp" "int affcnt" "void (*outc)(char, void *)" "void *args"
1.13 blymn 80: .Ft void
1.26 pooka 81: .Fn t_freent "struct tinfo *info"
1.20 blymn 82: .Ft int
83: .Fn t_setinfo "struct tinfo **info" "const char *entry"
1.31 christos 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"
1.1 cgd 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.
1.18 blymn 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
1.23 wiz 128: for a description of this capability),
1.1 cgd 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
1.27 wiz 137: file.
138: If the value does contain the ZZ capability then the
1.18 blymn 139: .Ev TERM
1.23 wiz 140: environment string is used to read
1.18 blymn 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.
1.23 wiz 145: If
1.18 blymn 146: .Ev TERMCAP
147: does begin with a slash, the string is used as a path name
1.1 cgd 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 ,
1.4 cgd 182: returning \-1 if it is not given for the terminal.
1.1 cgd 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
1.32 ! kleink 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 ,
1.1 cgd 201: and advances the
1.32 ! kleink 202: .Fa *area
! 203: pointer past the copy of the string.
1.1 cgd 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
1.10 fair 277: .Sy pc
1.1 cgd 278: capability)
279: if a null
280: .Pq Sy ^@
281: is inappropriate.
1.13 blymn 282: .Pp
283: The
284: .Fn t_getent
285: function operates in a similar manner to the
286: .Fn tgetent
1.23 wiz 287: function excepting that the
1.13 blymn 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
1.27 wiz 296: entry.
297: This pointer can then be passed to calls of
1.13 blymn 298: .Fn t_getnum ,
1.23 wiz 299: .Fn t_getflag
1.13 blymn 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 .
1.20 blymn 307: .Pp
1.23 wiz 308: The functions
1.20 blymn 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
1.23 wiz 321: performs the same function as
1.20 blymn 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 .
1.23 wiz 328: The
1.20 blymn 329: .Fa limit
1.23 wiz 330: argument is updated by the
1.20 blymn 331: .Fn t_getstr
332: call to give the number of characters that remain available in
333: .Fa area .
1.23 wiz 334: If the t_getstr call fails then
1.27 wiz 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
1.20 blymn 339: .Fa id ,
1.27 wiz 340: .Er E2BIG
341: indicates the retrieved entry would have overflowed
1.20 blymn 342: .Fa area .
1.23 wiz 343: If t_getstr is called with
1.20 blymn 344: .Fa area
1.27 wiz 345: being
346: .Dv NULL
347: then the size required to hold the capability string will be returned in
1.20 blymn 348: .Fa limit
349: so the caller can allocate enough storage to hold the capability.
350: .Pp
1.19 blymn 351: The function
352: .Fn t_agetstr
1.23 wiz 353: performs the same function as
1.19 blymn 354: .Fn t_getstr
1.27 wiz 355: except it handles memory allocation automatically.
356: The memory that
1.19 blymn 357: .Fn t_agetstr
1.22 christos 358: allocates will be freed when
359: .Fn t_freent
360: is called.
1.20 blymn 361: .Pp
362: The function
1.17 blymn 363: .Fn t_getterm
364: returns a copy of the termcap name string of the termcap entry
1.23 wiz 365: associated with
1.17 blymn 366: .Fa info
367: in the buffer pointed to by
368: .Fa area .
369: .Fn t_getterm
1.27 wiz 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
1.17 blymn 374: .Fa info
1.27 wiz 375: is malformed or
376: .Er E2BIG
377: if the size of the name exceeds the size specified by
1.17 blymn 378: .Fa limit .
1.23 wiz 379: If
1.17 blymn 380: .Fa area
1.27 wiz 381: is
382: .Dv NULL
383: then the size required to hold the terminal name will be returned in
1.17 blymn 384: .Fa limit
1.27 wiz 385: allowing sufficient storage to be allocated.
386: If
1.17 blymn 387: .Fa limit
1.27 wiz 388: is
389: .Dv NULL
390: then no bounds checking will be performed.
1.13 blymn 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
1.23 wiz 414: then
1.13 blymn 415: .Fn t_goto
1.27 wiz 416: will return \-1 and set errno to
417: .Er E2BIG .
1.13 blymn 418: The function
419: .Fn t_puts
420: is similar to the
421: .Fn tputs
1.23 wiz 422: function excepting that
1.13 blymn 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
1.27 wiz 428: attribute for the terminal.
1.31 christos 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.
1.27 wiz 434: The
1.13 blymn 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
1.27 wiz 440: string.
441: The
1.13 blymn 442: .Fa outc
1.27 wiz 443: function will be called with two parameters.
444: The first is the character
1.13 blymn 445: to be printed and the second is an optional argument that was passed to
446: .Fn t_puts
1.23 wiz 447: in the
1.13 blymn 448: .Fa args
1.27 wiz 449: argument.
450: The interpretation of the contents of
1.13 blymn 451: .Fa args
1.21 christos 452: is dependent solely on the implementation of
1.25 wiz 453: .Fa outc .
1.20 blymn 454: .Pp
455: The
456: .Fn t_setinfo
457: function allows the termcap entry contained in the
458: .Fa entry
1.30 simonb 459: string to be inserted into the
1.20 blymn 460: .Fa info
1.27 wiz 461: structure.
462: Memory sufficient to hold the contents of
1.20 blymn 463: .Fa entry
1.27 wiz 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
1.20 blymn 468: .Fa entry
469: is assumed to be a valid termcap entry.
1.13 blymn 470: .Pp
1.23 wiz 471: NOTE: A special capability of
1.13 blymn 472: .Fa ZZ
1.27 wiz 473: is added to the end of the termcap entry retrieved.
474: The number that follows this entry is the address of the buffer allocated
475: to hold the full termcap entry.
476: The caller may retrieve the pointer to the extended buffer by performing a
1.13 blymn 477: .Fn tgetstr
478: to retrieve the
479: .Fa ZZ
1.23 wiz 480: capability, the string is the output of a
1.13 blymn 481: .Fn printf
482: %p and may be converted back to a pointer using
483: .Fn sscanf
1.27 wiz 484: or similar.
485: The ZZ capability is only necessary if the caller wishes to
1.13 blymn 486: directly manipulate the termcap entry, all the termcap function calls
487: automatically use the extended buffer to retrieve terminal capabilities.
1.1 cgd 488: .Sh FILES
489: .Bl -tag -width /usr/share/misc/termcap -compact
490: .It Pa /usr/lib/libtermcap.a
1.7 lukem 491: .Fl l Ar termcap
1.1 cgd 492: library (also known as
1.7 lukem 493: .Fl l Ar termlib )
1.1 cgd 494: .It Pa /usr/share/misc/termcap
495: standard terminal capability data base
496: .It Pa $HOME/.termcap
497: user's terminal capability data base
498: .El
499: .Sh SEE ALSO
500: .Xr ex 1 ,
501: .Xr curses 3 ,
502: .Xr termcap 5
503: .Sh HISTORY
504: The
1.21 christos 505: .Nm termcap
506: t_*() functions appeared in
507: .Nx 1.5 .
1.23 wiz 508: The rest of the
1.8 lukem 509: .Nm termcap
1.12 simonb 510: functions appeared in
1.1 cgd 511: .Bx 4.0 .
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to termcap.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libterm