Annotation of src/lib/libterminfo/terminfo.3, Revision 1.6
1.6 ! roy 1: .\" $NetBSD: terminfo.3,v 1.5 2011/10/02 19:24:25 roy Exp $
1.1 roy 2: .\"
1.5 roy 3: .\" Copyright (c) 2009, 2011 The NetBSD Foundation, Inc.
1.1 roy 4: .\" All rights reserved.
5: .\"
6: .\" This code is derived from software contributed to The NetBSD Foundation
7: .\" by Roy Marples.
8: .\"
9: .\" Redistribution and use in source and binary forms, with or without
10: .\" modification, are permitted provided that the following conditions
11: .\" are met:
12: .\" 1. Redistributions of source code must retain the above copyright
13: .\" notice, this list of conditions and the following disclaimer.
14: .\" 2. Redistributions in binary form must reproduce the above copyright
15: .\" notice, this list of conditions and the following disclaimer in the
16: .\" documentation and/or other materials provided with the distribution.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28: .\" POSSIBILITY OF SUCH DAMAGE.
29: .\"
1.6 ! roy 30: .Dd October 3, 2011
1.1 roy 31: .Dt TERMINFO 3
32: .Os
33: .Sh NAME
34: .Nm setupterm ,
35: .Nm set_curterm ,
36: .Nm del_curterm ,
1.5 roy 37: .Nm termname ,
1.1 roy 38: .Nm tigetflag ,
39: .Nm tigetnum ,
40: .Nm tigetstr ,
41: .Nm tparm ,
42: .Nm tputs ,
43: .Nm putp
44: .Nd terminal independent operation routines
45: .Sh LIBRARY
46: .Lb libterminfo
47: .Sh SYNOPSIS
48: .In term.h
1.3 snj 49: .Vt char PC ;
50: .Vt short ospeed ;
51: .Vt TERMINAL *cur_term ;
1.1 roy 52: .Ft int
53: .Fn setupterm "const char *name" "int fildes" "int *errret"
54: .Ft TERMINAL *
55: .Fn set_curterm "TERMINAL *term"
56: .Ft int
57: .Fn del_curterm "TERMINAL *term"
1.5 roy 58: .Ft char *
59: .Fn termname "void"
1.1 roy 60: .Ft int
61: .Fn tigetnum "const char *id"
62: .Ft int
63: .Fn tigetflag "const char *id"
64: .Ft char *
65: .Fn tigetstr "const char *id"
66: .Ft char *
67: .Fn tparm "const char *cm" "long p1" "long p2" "long p3" "long p4" "long p5" "long p6" "long p7" "long p8" "long p9"
68: .Ft int
69: .Fn tputs "const char *cp" "int affcnt" "int (*outc)(int)"
70: .Ft int
71: .Fn putp "const char *cp"
72: .Ft int
73: .Fn ti_setupterm "TERMINAL **" "const char *name" "int fildes" "int *error"
74: .Ft int
75: .Fn ti_getflag "const TERMINAL *" "const char *id"
76: .Ft int
77: .Fn ti_getnum "const TERMINAL *" "const char *id"
78: .Ft const char *
79: .Fn ti_getstr "const TERMINAL *" "const char *id"
80: .Ft char *
1.6 ! roy 81: .Fn tiparm "const char *cm" "..."
1.1 roy 82: .Ft char *
1.6 ! roy 83: .Fn ti_tiparm "TERMINAL *" "const char *cm" "..."
1.1 roy 84: .Ft int
85: .Fn ti_puts "const TERMINAL *term" "const char *str" "int affcnt" "int (*outc)(int, void *)"
86: .Ft int
87: .Fn ti_putp "const TERMINAL *term" "const char *str"
88: .Sh DESCRIPTION
1.3 snj 89: These functions extract and use capabilities from a terminal capability
90: database, usually
1.1 roy 91: .Pa /usr/share/misc/terminfo ,
92: the format of which is described in
93: .Xr terminfo 5 .
94: These are low level routines;
95: see
96: .Xr curses 3
97: for a higher level package.
98: .Pp
99: The
100: .Fn setupterm
101: function extracts the entry for terminal
102: .Fa name
103: and then calls
104: .Fn set_curterm
105: to set
1.2 wiz 106: .Va cur_term
107: to it.
1.1 roy 108: If
109: .Fa name
110: is
111: .Dv NULL
112: then it is replaced by the environment variable
1.4 wiz 113: .Ev TERM .
1.1 roy 114: The
115: .Fn setupterm
1.4 wiz 116: function returns 0 on success and \-1 on error.
1.1 roy 117: .Va errret
118: is set to \-1 if the
119: .Nm terminfo
120: database could not be opened,
1.3 snj 121: 0 if the terminal could not be found in the database, and
1.1 roy 122: 1 if all went well.
123: .Pp
124: The
125: .Fn set_curterm
126: function sets the variable
127: .Va cur_term
128: to
129: .Va nterm
130: and makes all of the
131: .Nm terminfo
132: boolean, numeric and string variables use the values from
133: .Va nterm .
134: The global variables
135: .Va PC
136: and
137: .Va ospeed
138: are then set.
139: The old value of
140: .Va cur_term
141: is returned.
142: The
143: .Fn del_curterm
144: function frees space pointed to by
1.2 wiz 145: .Va oterm .
1.1 roy 146: .Pp
147: The
1.5 roy 148: .Fn termname
149: function returns the name of
150: .Va cur_term .
151: .Pp
152: The
1.1 roy 153: .Fn tigetflag
154: function gets the boolean value of capability
155: .Va id ,
156: returning \-1 if it is not a valid capability.
157: The
158: .Fn tigetnum
159: function gets the numeric value of the capability
160: .Va id ,
161: returning \-2 if it is not a valid capability.
162: The
163: .Fn tigetstr
164: function returns the string value of the capability
165: .Va id ,
166: returning (char *)-1 if it is not a valid capability.
167: .Pp
168: The
169: .Fn tparm
170: function returns a string decoded from
171: .Va cm
172: with the parameters
173: .Va p1
1.3 snj 174: \&...
1.1 roy 175: .Va p9
176: applied.
1.3 snj 177: Some capabilities require string parameters and only platforms that can fit
1.4 wiz 178: a
179: .Vt char *
180: pointer inside a
181: .Vt long
182: can use them.
1.1 roy 183: The string encoding and parameter application is described in
184: .Xr terminfo 5 .
185: .Pp
186: The
187: .Fn tputs
188: function applies padding information to the string
189: .Va cp ;
190: .Va affcnt
191: gives the number of lines affected by the operation,
1.3 snj 192: or 1 if this is not applicable;
1.1 roy 193: .Va outc
194: is a function which is called by each character in turn.
195: The external variable
196: .Va ospeed
197: controls how many padding characters are sent in relation to the terminal
198: speed.
199: The
200: .Fn putp
201: function calls tputs(str, 1, putchar).
202: The output from
203: .Fn putp
204: always goes to stdout.
205: .Ss NetBSD Extensions To Terminfo
206: The
1.6 ! roy 207: .Fn tiparm
1.1 roy 208: function allows variadic parameters instead of 9 fixed longs.
1.6 ! roy 209: Numeric parameters must be integers (int) instead of longs.
1.4 wiz 210: String parameters can be used even if the platform cannot fit a
211: .Vt char *
212: into a
213: .Vt long .
1.1 roy 214: .Pp
215: The
216: .Fn ti_*
1.3 snj 217: functions correspond to the standard
1.1 roy 218: .Fn t*
219: functions but take an additional
220: .Ft TERMINAL *
221: parameter so that the terminal can be specified instead of assuming
222: .Va cur_term .
223: These functions use private variables to the
224: .Ft TERMINAL
225: instead of the global variables, such as
226: .Va PC
227: and
228: .Va ospeed .
229: .Sh SEE ALSO
230: .Xr ex 1 ,
231: .Xr curses 3 ,
232: .Xr terminfo 5
233: .Sh AUTHORS
234: .An Roy Marples Aq roy@NetBSD.org
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to terminfo.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libterminfo