Commit | Line | Data |
---|---|---|
d51a7d28 KB |
1 | .\" Copyright (c) 1980, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
80e966ee | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
80e966ee | 5 | .\" |
653ba8b6 | 6 | .\" @(#)termcap.3 8.2 (Berkeley) %G% |
4b8545f8 | 7 | .\" |
ae59e04c CL |
8 | .Dd |
9 | .Dt TERMCAP 3 | |
10 | .Os BSD 4 | |
11 | .Sh NAME | |
12 | .Nm tgetent , | |
13 | .Nm tgetnum , | |
14 | .Nm tgetflag , | |
15 | .Nm tgetstr , | |
16 | .Nm tgoto , | |
17 | .Nm tputs | |
18 | .Nd terminal independent operation routines | |
19 | .Sh SYNOPSIS | |
20 | .Vt char PC; | |
21 | .Vt char *BC; | |
22 | .Vt char *UP; | |
23 | .Vt short ospeed; | |
24 | .Fn tgetent "char *bp" "char *name" | |
25 | .Fn tgetnum "char *id" | |
26 | .Fn tgetflag "char *id" | |
27 | .Ft char * | |
1fdff90c | 28 | .Fn tgetstr "char *id" "char **area" |
ae59e04c CL |
29 | .Ft char * |
30 | .Fn tgoto "char *cm" destcol destline | |
31 | .Fn tputs "register char *cp" "int affcnt" "int (*outc)()" | |
32 | .Sh DESCRIPTION | |
6d1f0acf | 33 | These functions extract and use capabilities from a terminal capability data |
ae59e04c CL |
34 | base, usually |
35 | .Pa /usr/share/misc/termcap , | |
36 | the format of which is described in | |
37 | .Xr termcap 5 . | |
80e966ee KM |
38 | These are low level routines; |
39 | see | |
ae59e04c | 40 | .Xr curses 3 |
80e966ee | 41 | for a higher level package. |
ae59e04c CL |
42 | .Pp |
43 | The | |
44 | .Fn tgetent | |
45 | function | |
80e966ee | 46 | extracts the entry for terminal |
ae59e04c | 47 | .Fa name |
80e966ee | 48 | into the buffer at |
ae59e04c CL |
49 | .Fa bp . |
50 | The | |
51 | .Fa bp | |
52 | argument | |
80e966ee | 53 | should be a character buffer of size |
6d1f0acf | 54 | 1024 and must be retained through all subsequent calls to |
ae59e04c CL |
55 | .Fn tgetnum , |
56 | .Fn tgetflag , | |
80e966ee | 57 | and |
ae59e04c CL |
58 | .Fn tgetstr . |
59 | The | |
60 | .Fn tgetent | |
61 | function | |
62 | returns \-1 if none of the | |
63 | .Nm termcap | |
6d1f0acf JK |
64 | data base files could be opened, |
65 | 0 if the terminal name given does not have an entry, | |
80e966ee | 66 | and 1 if all goes well. |
ae59e04c CL |
67 | It will look in the environment for a |
68 | .Ev TERMCAP | |
69 | variable. | |
80e966ee KM |
70 | If found, and the value does not begin with a slash, |
71 | and the terminal type | |
ae59e04c CL |
72 | .Fa name |
73 | is the same as the environment string | |
74 | .Ev TERM , | |
75 | the | |
76 | .Ev TERMCAP | |
77 | string is used instead of reading a | |
78 | .Nm termcap | |
79 | file. | |
6d1f0acf | 80 | If it does begin with a slash, the string is used as a path name |
ae59e04c CL |
81 | of the |
82 | .Nm termcap | |
83 | file to search. | |
84 | If | |
85 | .Ev TERMCAP | |
86 | does not begin with a slash and | |
87 | .Fa name | |
88 | is different from | |
89 | .Ev TERM , | |
90 | .Fn tgetent | |
91 | searches the files | |
92 | .Pa $HOME/.termcap | |
93 | and | |
94 | .Pa /usr/share/misc/termcap , | |
95 | in that order, unless the environment variable | |
96 | .Ev TERMPATH | |
97 | exists, | |
6d1f0acf JK |
98 | in which case it specifies a list of file pathnames |
99 | (separated by spaces or colons) to be searched instead. | |
100 | Whenever multiple files are searched and a | |
ae59e04c | 101 | .Sy tc |
6d1f0acf JK |
102 | field occurs in the requested entry, the entry it names must be found |
103 | in the same file or one of the succeeding files. | |
80e966ee | 104 | This can speed up entry into programs that call |
ae59e04c | 105 | .Fn tgetent , |
6d1f0acf | 106 | as well as help debug new terminal descriptions |
ae59e04c CL |
107 | or make one for your terminal if you can't write the file |
108 | .Pa /usr/share/misc/termcap . | |
109 | .Pp | |
110 | The | |
111 | .Fn tgetnum | |
112 | function | |
80e966ee | 113 | gets the numeric value of capability |
ae59e04c | 114 | .Fa id , |
653ba8b6 | 115 | returning \-1 if it is not given for the terminal. |
ae59e04c CL |
116 | The |
117 | .Fn tgetflag | |
118 | function | |
80e966ee KM |
119 | returns 1 if the specified capability is present in |
120 | the terminal's entry, 0 if it is not. | |
ae59e04c CL |
121 | The |
122 | .Fn tgetstr | |
123 | function | |
1bb971f1 | 124 | returns the string value of the capability |
ae59e04c | 125 | .Fa id , |
1bb971f1 | 126 | places it in the buffer at |
ae59e04c | 127 | .Fa area , |
1bb971f1 | 128 | and advances the |
ae59e04c | 129 | .Fa area |
80e966ee KM |
130 | pointer. |
131 | It decodes the abbreviations for this field described in | |
ae59e04c | 132 | .Xr termcap 5 , |
80e966ee | 133 | except for cursor addressing and padding information. |
ae59e04c CL |
134 | The |
135 | .Fn tgetstr | |
136 | function | |
137 | returns | |
138 | .Dv NULL | |
139 | if the capability was not found. | |
140 | .Pp | |
141 | The | |
142 | .Fn tgoto | |
143 | function | |
80e966ee | 144 | returns a cursor addressing string decoded from |
ae59e04c | 145 | .Fa cm |
80e966ee | 146 | to go to column |
ae59e04c | 147 | .Fa destcol |
80e966ee | 148 | in line |
ae59e04c | 149 | .Fa destline . |
80e966ee | 150 | It uses the external variables |
ae59e04c CL |
151 | .Va UP |
152 | (from the | |
153 | .Sy up | |
154 | capability) | |
80e966ee | 155 | and |
ae59e04c CL |
156 | .Va BC |
157 | (if | |
158 | .Sy bc | |
159 | is given rather than | |
160 | .Sy bs ) | |
161 | if necessary to avoid placing | |
162 | .Sy \en , | |
163 | .Sy ^D | |
164 | or | |
165 | .Sy ^@ | |
166 | in | |
80e966ee | 167 | the returned string. |
ae59e04c CL |
168 | (Programs which call |
169 | .Fn tgoto | |
170 | should be sure to turn off the | |
171 | .Dv XTABS | |
172 | bit(s), | |
ff557bd1 | 173 | since |
ae59e04c | 174 | .Fn tgoto |
ff557bd1 | 175 | may now output a tab. |
ae59e04c CL |
176 | Note that programs using termcap should in general turn off |
177 | .Dv XTABS | |
6d1f0acf | 178 | anyway since some terminals use control-I for other functions, |
80e966ee | 179 | such as nondestructive space.) |
ae59e04c CL |
180 | If a |
181 | .Sy % | |
182 | sequence is given which is not understood, then | |
183 | .Fn tgoto | |
184 | returns | |
185 | .Pq Dv OOPS . | |
186 | .Pp | |
187 | The | |
188 | .Fn tputs | |
189 | function | |
80e966ee | 190 | decodes the leading padding information of the string |
ae59e04c CL |
191 | .Fa cp ; |
192 | .Fa affcnt | |
80e966ee KM |
193 | gives the number of lines affected by the operation, or 1 if this is |
194 | not applicable, | |
ae59e04c | 195 | .Fa outc |
80e966ee KM |
196 | is a routine which is called with each character in turn. |
197 | The external variable | |
ae59e04c | 198 | .Va ospeed |
80e966ee | 199 | should contain the output speed of the terminal as encoded by |
ae59e04c | 200 | .Xr stty 3 . |
80e966ee | 201 | The external variable |
ae59e04c CL |
202 | .Va PC |
203 | should contain a pad character to be used (from the | |
204 | .SY pc | |
205 | capability) | |
206 | if a null | |
207 | .Pq Sy ^@ | |
208 | is inappropriate. | |
209 | .Sh FILES | |
210 | .Bl -tag -width /usr/share/misc/termcap -compact | |
211 | .It Pa /usr/lib/libtermcap.a | |
212 | .Fl l Ar ltermcap | |
213 | library (also known as | |
214 | .Fl l Ar ltermlib ) | |
215 | .It Pa /usr/share/misc/termcap | |
216 | standard terminal capability data base | |
217 | .It Pa $HOME/.termcap | |
218 | user's terminal capability data base | |
219 | .El | |
220 | .Sh SEE ALSO | |
221 | .Xr ex 1 , | |
222 | .Xr curses 3 , | |
223 | .Xr termcap 5 | |
224 | .Sh HISTORY | |
225 | The | |
226 | .Nm | |
227 | functions appeared in | |
228 | .Bx 4.0 . |