Commit | Line | Data |
---|---|---|
15637ed4 RG |
1 | .\" Copyright (c) 1980, 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
19 | .\" | |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
32 | .\" @(#)termcap.3 6.6 (Berkeley) 4/19/91 | |
33 | .\" | |
34 | .Dd April 19, 1991 | |
35 | .Dt TERMCAP 3 | |
36 | .Os BSD 4 | |
37 | .Sh NAME | |
38 | .Nm tgetent , | |
39 | .Nm tgetnum , | |
40 | .Nm tgetflag , | |
41 | .Nm tgetstr , | |
42 | .Nm tgoto , | |
43 | .Nm tputs | |
44 | .Nd terminal independent operation routines | |
45 | .Sh SYNOPSIS | |
46 | .Vt char PC; | |
47 | .Vt char *BC; | |
48 | .Vt char *UP; | |
49 | .Vt short ospeed; | |
50 | .Fn tgetent "char *bp" "char *name" | |
51 | .Fn tgetnum "char *id" | |
52 | .Fn tgetflag "char *id" | |
53 | .Ft char * | |
54 | .Fn tgetstr "char *id" "char *area" | |
55 | .Ft char * | |
56 | .Fn tgoto "char *cm" destcol destline | |
57 | .Fn tputs "register char *cp" "int affcnt" "int (*outc)()" | |
58 | .Sh DESCRIPTION | |
59 | These functions extract and use capabilities from a terminal capability data | |
60 | base, usually | |
61 | .Pa /usr/share/misc/termcap , | |
62 | the format of which is described in | |
63 | .Xr termcap 5 . | |
64 | These are low level routines; | |
65 | see | |
66 | .Xr curses 3 | |
67 | for a higher level package. | |
68 | .Pp | |
69 | The | |
70 | .Fn tgetent | |
71 | function | |
72 | extracts the entry for terminal | |
73 | .Fa name | |
74 | into the buffer at | |
75 | .Fa bp . | |
76 | The | |
77 | .Fa bp | |
78 | argument | |
79 | should be a character buffer of size | |
80 | 1024 and must be retained through all subsequent calls to | |
81 | .Fn tgetnum , | |
82 | .Fn tgetflag , | |
83 | and | |
84 | .Fn tgetstr . | |
85 | The | |
86 | .Fn tgetent | |
87 | function | |
88 | returns \-1 if none of the | |
89 | .Nm termcap | |
90 | data base files could be opened, | |
91 | 0 if the terminal name given does not have an entry, | |
92 | and 1 if all goes well. | |
93 | It will look in the environment for a | |
94 | .Ev TERMCAP | |
95 | variable. | |
96 | If found, and the value does not begin with a slash, | |
97 | and the terminal type | |
98 | .Fa name | |
99 | is the same as the environment string | |
100 | .Ev TERM , | |
101 | the | |
102 | .Ev TERMCAP | |
103 | string is used instead of reading a | |
104 | .Nm termcap | |
105 | file. | |
106 | If it does begin with a slash, the string is used as a path name | |
107 | of the | |
108 | .Nm termcap | |
109 | file to search. | |
110 | If | |
111 | .Ev TERMCAP | |
112 | does not begin with a slash and | |
113 | .Fa name | |
114 | is different from | |
115 | .Ev TERM , | |
116 | .Fn tgetent | |
117 | searches the files | |
118 | .Pa $HOME/.termcap | |
119 | and | |
120 | .Pa /usr/share/misc/termcap , | |
121 | in that order, unless the environment variable | |
122 | .Ev TERMPATH | |
123 | exists, | |
124 | in which case it specifies a list of file pathnames | |
125 | (separated by spaces or colons) to be searched instead. | |
126 | Whenever multiple files are searched and a | |
127 | .Sy tc | |
128 | field occurs in the requested entry, the entry it names must be found | |
129 | in the same file or one of the succeeding files. | |
130 | This can speed up entry into programs that call | |
131 | .Fn tgetent , | |
132 | as well as help debug new terminal descriptions | |
133 | or make one for your terminal if you can't write the file | |
134 | .Pa /usr/share/misc/termcap . | |
135 | .Pp | |
136 | The | |
137 | .Fn tgetnum | |
138 | function | |
139 | gets the numeric value of capability | |
140 | .Fa id , | |
141 | returning \-1 if is not given for the terminal. | |
142 | The | |
143 | .Fn tgetflag | |
144 | function | |
145 | returns 1 if the specified capability is present in | |
146 | the terminal's entry, 0 if it is not. | |
147 | The | |
148 | .Fn tgetstr | |
149 | function | |
150 | returns the string value of the capability | |
151 | .Fa id , | |
152 | places it in the buffer at | |
153 | .Fa area , | |
154 | and advances the | |
155 | .Fa area | |
156 | pointer. | |
157 | It decodes the abbreviations for this field described in | |
158 | .Xr termcap 5 , | |
159 | except for cursor addressing and padding information. | |
160 | The | |
161 | .Fn tgetstr | |
162 | function | |
163 | returns | |
164 | .Dv NULL | |
165 | if the capability was not found. | |
166 | .Pp | |
167 | The | |
168 | .Fn tgoto | |
169 | function | |
170 | returns a cursor addressing string decoded from | |
171 | .Fa cm | |
172 | to go to column | |
173 | .Fa destcol | |
174 | in line | |
175 | .Fa destline . | |
176 | It uses the external variables | |
177 | .Va UP | |
178 | (from the | |
179 | .Sy up | |
180 | capability) | |
181 | and | |
182 | .Va BC | |
183 | (if | |
184 | .Sy bc | |
185 | is given rather than | |
186 | .Sy bs ) | |
187 | if necessary to avoid placing | |
188 | .Sy \en , | |
189 | .Sy ^D | |
190 | or | |
191 | .Sy ^@ | |
192 | in | |
193 | the returned string. | |
194 | (Programs which call | |
195 | .Fn tgoto | |
196 | should be sure to turn off the | |
197 | .Dv XTABS | |
198 | bit(s), | |
199 | since | |
200 | .Fn tgoto | |
201 | may now output a tab. | |
202 | Note that programs using termcap should in general turn off | |
203 | .Dv XTABS | |
204 | anyway since some terminals use control-I for other functions, | |
205 | such as nondestructive space.) | |
206 | If a | |
207 | .Sy % | |
208 | sequence is given which is not understood, then | |
209 | .Fn tgoto | |
210 | returns | |
211 | .Pq Dv OOPS . | |
212 | .Pp | |
213 | The | |
214 | .Fn tputs | |
215 | function | |
216 | decodes the leading padding information of the string | |
217 | .Fa cp ; | |
218 | .Fa affcnt | |
219 | gives the number of lines affected by the operation, or 1 if this is | |
220 | not applicable, | |
221 | .Fa outc | |
222 | is a routine which is called with each character in turn. | |
223 | The external variable | |
224 | .Va ospeed | |
225 | should contain the output speed of the terminal as encoded by | |
226 | .Xr stty 3 . | |
227 | The external variable | |
228 | .Va PC | |
229 | should contain a pad character to be used (from the | |
230 | .SY pc | |
231 | capability) | |
232 | if a null | |
233 | .Pq Sy ^@ | |
234 | is inappropriate. | |
235 | .Sh FILES | |
236 | .Bl -tag -width /usr/share/misc/termcap -compact | |
237 | .It Pa /usr/lib/libtermcap.a | |
238 | .Fl l Ar ltermcap | |
239 | library (also known as | |
240 | .Fl l Ar ltermlib ) | |
241 | .It Pa /usr/share/misc/termcap | |
242 | standard terminal capability data base | |
243 | .It Pa $HOME/.termcap | |
244 | user's terminal capability data base | |
245 | .El | |
246 | .Sh SEE ALSO | |
247 | .Xr ex 1 , | |
248 | .Xr curses 3 , | |
249 | .Xr termcap 5 | |
250 | .Sh HISTORY | |
251 | The | |
252 | .Nm | |
253 | functions appeared in | |
254 | .Bx 4.0 . |