| blob | d0827c7365cacdb9a84642f08d235e9296a29372 |
1 .\" $NetBSD: terminfo.5.in,v 1.19 2013/07/20 21:39:56 wiz Exp $
2 .\"
3 .\" Copyright (c) 2009, 2010, 2011, 2013 The NetBSD Foundation, Inc.
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 .\"
30 .Dd January 25, 2013
31 .Dt TERMINFO 5
32 .Os
33 .Sh NAME
34 .Nm terminfo
35 .Nd terminal capability definition
36 .Sh DESCRIPTION
37 .Nm
38 describes the capabilities of terminals, used by programs such as
39 .Xr vi 1 ,
40 .Xr rogue 6
41 and libraries such as
42 .Xr curses 3 .
43 The
44 .Nm
45 source described here needs to be compiled with
46 .Xr tic 1
47 to be of any use.
48 .Pp
49 Entries in
50 .Nm
51 consist of a number of comma separated fields.
52 White space after each comma is ignored.
53 Embedded commas must be escaped by using a backslash.
54 Lines beginning with
55 .Sq #
56 in the first column are treated as comments.
57 Blank lines are ignored.
58 .Pp
59 The header line must begin in column one and end with a comma.
60 Inside the header line are terminal name and aliases,
61 separated by vertical bars, the last one being the long
62 description of the terminal.
63 .Pp
64 Capability lines then follow, starting on column two and ending with a comma.
65 Each capability is listed by its name, followed by its value if applicable.
66 Booleans have no values, numeric values are prefixed by
67 .Sq #
68 and strings are prefixed by
69 .Sq = .
70 Numbers can range from 0 to 32767 and string values can be up to 1000
71 characters long.
72 This implementation supports strings upto 32767 characters long, including the
73 .Dv NUL
74 terminator.
75 .Pp
76 Some escapes are available for strings - both
77 .Sy \eE
78 and
79 .Sy \ee
80 map to the
81 .Dv ESC
82 character,
83 .Sy ^X
84 maps to a control-X for any appropriate X, and the sequences
85 .Sy \en ,
86 .Sy \er ,
87 .Sy \et ,
88 .Sy \eb
89 and
90 .Sy \ef
91 map to linefeed, return, tab, backspace, and formfeed respectively.
92 Any character can be escaped in octal, such as
93 .Sy \e072 .
94 If you need to encode a
95 .Dv NUL
96 character, it should be escaped as
97 .Sy \e200 .
98 .Pp
99 A delay in milliseconds may appear anywhere in a string capability,
100 prefixed with a dollar sign and enclosed by angled brackets, such as
101 .Sy $\*[Lt]5\*[Gt] .
102 .Ss String Parameters
103 String capabilities sometimes require parameters.
104 Normally this just involves replacing the parameter with a supplied
105 variable; however, there are cases where the variable needs to be manipulated
106 or used in conditional expressions.
107 A stack is also provided for simple pop and push operations.
108 .Pp
109 The below % encodings have the following meanings:
110 .Bl -tag -width %P[a-z]
111 .It Sy %%
112 outputs %
113 .It Sy %[[:]flags][width[.precision]][doxXs]
114 flags are
115 .Dq [-+#] .
116 Prefix with
117 .Sq \&:
118 to avoid interpreting
119 .Dq %-
120 as an operator.
121 .It Sy %c
122 pop a parameter and print the character representation of it.
123 .It Sy %s
124 pop a parameter and print the string representation of it.
125 .It Sy %p[1-9]
126 push the parameter [1-9].
127 .It Sy %P[a-z]
128 pop a parameter and push it to dynamic variable [a-z].
129 .It Sy %g[a-z]
130 push the dynamic variable [a-z].
131 .It Sy %P[A-Z]
132 pop a parameter and push it to static variable [a-z].
133 .It Sy %g[A-Z]
134 push the dynamic variable [A-Z].
135 .Pp
136 Static variables persist over
137 .Fn tparm
138 whereas dynamic variables do not.
139 .It Sy %'c'
140 char constant c.
141 .It Sy %{nn}
142 integer constant nn.
143 .It Sy %l
144 push the string length of the previously popped parameter.
145 .It Sy %+ Sy %- Sy %* Sy %/ Sy %m
146 arithmetic: pop two parameters and push the result.
147 .It Sy %& Sy %| Sy %^
148 bit operations: pop two parameters and push the result.
149 .It Sy %! Sy %~
150 unary operations: pop two parameters and push the result.
151 .It Sy %i
152 add 1 to parameters 1 and 2.
153 .It Sy %? Va expr Sy %t Ic then Sy %e Ic else Sy %;
154 If expr equates to zero then control passes to the optional else part.
155 .El
156 .Ss Boolean Capabilities
157 .Bl -column "enter_near_quality_letter" "setcolor" "TC" "desc"
158 .It Sy "Long name" Ta Sy "Code" Ta Sy "TC" Ta Sy "Description"
159 @BOOLCAPS@
160 .El
161 .Ss Numeric Capabilities
162 .Bl -column "enter_near_quality_letter" "setcolor" "TC" "Desc"
163 .It Sy "Long name" Ta Sy "Code" Ta Sy "TC" Ta Sy "Description"
164 @NUMCAPS@
165 .El
166 .Ss String Capabilities
167 .Bl -column "enter_near_quality_letter" "setcolor" "TC" "Desc"
168 .It Sy "Long name" Ta Sy "Code" Ta Sy "TC" Ta Sy "Description"
169 @STRCAPS@
170 .El
171 .Ss A Sample Entry
172 .Bd -literal
173 vt100\||dec vt100 (w/advanced video),
174 am, xenl, msgr, mc5i, xon,
175 cols#80, it#8, lines#24, vt#3,
176 acsc=``aaffggjjkkllmmnnooppqqrrssttuuvvwwxxyyzz{{||}}~~, bel=^G,
177 cr=^M, csr=\eE[%i%p1%d;%p2%dr, tbc=\eE[3g, clear=\eE[H\eE[J$\*[Lt]50\*[Gt],
178 el1=\eE[1K$\*[Lt]3\*[Gt], el=\eE[K$\*[Lt]3\*[Gt], ed=\eE[J$\*[Lt]50\*[Gt],
179 cup=\eE[%i%p1%d;%p2%dH$\*[Lt]5\*[Gt], cud1=^J, home=\eE[H, cub1=^H,
180 cuf1=\eE[C$\*[Lt]2\*[Gt], cuu1=\eE[A$\*[Lt]2\*[Gt], enacs=\eE(B\eE)0, smacs=^N,
181 smam=\eE[?7h, blink=\eE[5m$\*[Lt]2\*[Gt], bold=\eE[1m$\*[Lt]2\*[Gt], rev=\eE[7m$\*[Lt]2\*[Gt],
182 smso=\eE[7m$\*[Lt]2\*[Gt], smul=\eE[4m$\*[Lt]2\*[Gt], rmacs=^O, rmam=\eE[?7l,
183 sgr0=\eE[m017$\*[Lt]2\*[Gt], rmso=\eE[m$\*[Lt]2\*[Gt], rmul=\eE[m$\*[Lt]2\*[Gt], ka1=\eEOq,
184 ka3=\eEOs, kb2=\eEOr, kbs=^H, kc1=\eEOp, kc3=\eEOn, kcud1=\eEOB,
185 kent=\eEOM, kf0=\eEOy, kf1=\eEOP, kf2=\eEOQ, kf3=\eEOR, kf4=\eEOS,
186 kf5=\eEOt, kf6=\eEOu, kf7=\eEOv, kf8=\eEOl, kf9=\eEOw, kf10=\eEOx,
187 kcub1=\eEOD, kcuf1=\eEOC, kcuu1=\eEOA, rmkx=\eE[?1l\eE\*[Gt],
188 smkx=\eE[?1h\eE=, lf1=pf1, lf2=pf2, lf3=pf3, lf4=pf4,
189 cud=\eE[%p1%dB, cub=\eE[%p1%dD, cuf=\eE[%p1%dC, cuu=\eE[%p1%dA,
190 mc0=\eE[0i, mc4=\eE[4i, mc5=\eE[5i,
191 rs2=\eE\*[Gt]\eE[?3l\eE[?4l\eE[?5l\eE[?7h\eE[?8h, rc=\eE8, sc=\eE7,
192 ind=^J, ri=\eEM$\*[Lt]5\*[Gt],
193 sgr=\eE[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p1%p3%|%t;7%;%?%p4%t;5%;m%?%p9%t016%e017%;$\*[Lt]2\*[Gt],
194 hts=\eEH, ht=^I,
195 .Ed
196 .Ss Fetching Compiled Descriptions
197 This implementation uses hashed databases managed by
198 .Xr cdb 5
199 instead of directories.
200 To maintain compatability with other implementations,
201 .Pa .cdb
202 is appended to each file checked.
203 .Pp
204 If the environment variable
205 .Ev TERMINFO
206 is available, does not begin with
207 .Pq Sq / ,
208 can be compiled with the above rules and whose name matches
209 .Ev TERM
210 then it is used.
211 .Pp
212 If the environment variable
213 .Ev TERMCAP
214 is available and does not begin with a slash
215 .Pq Sq /
216 then it will be translated into
217 terminfo and compiled as above.
218 If its name matches
219 .Ev TERM
220 then it is used.
221 .Pp
222 If the environment variable
223 .Ev TERMINFO
224 is available and begins with a slash
225 .Pq Sq /
226 then only this file is searched.
227 Otherwise
228 .Nm
229 will first look for
230 .Pa $HOME/.terminfo ,
231 followed by
232 .Pa /usr/share/misc/terminfo
233 unless
234 .Ev TERMINFO_DIRS
235 is available.
236 If a matching description is not found then a small embedded database is
237 searched, which currently holds descriptions for ansi, dumb, vt100, vt220,
238 wsvt25, and xterm.
239 .Sh FILES
240 .Bl -tag -width /usr/share/misc/terminfo.cdb -compact
241 .It Pa $HOME/.terminfo.cdb
242 Database of terminal descriptions for personal use.
243 .It Pa /usr/share/misc/terminfo
244 File containing terminal descriptions.
245 .It Pa /usr/share/misc/terminfo.cdb
246 Database of terminal descriptions.
247 .El
248 .Sh SEE ALSO
249 .Xr infocmp 1 ,
250 .Xr tic 1 ,
251 .Xr tput 1 ,
252 .Xr curses 3 ,
253 .Xr cdb 5
254 .Sh STANDARDS
255 .Nm
256 complies with the
257 .St -xcurses4.2
258 standard.
259 .Pp
260 Extensions to the standard are noted in
261 .Xr tic 1 .
262 .Sh AUTHORS
263 .An Roy Marples Aq Mt roy@NetBSD.org