Debian Codegraph @

upstream/debian-trixie/man5/user_caps.5

raw
1 '\" t
2 .\"***************************************************************************
3 .\" Copyright 2018-2023,2024 Thomas E. Dickey *
4 .\" Copyright 2017 Free Software Foundation, Inc. *
5 .\" *
6 .\" Permission is hereby granted, free of charge, to any person obtaining a *
7 .\" copy of this software and associated documentation files (the *
8 .\" "Software"), to deal in the Software without restriction, including *
9 .\" without limitation the rights to use, copy, modify, merge, publish, *
10 .\" distribute, distribute with modifications, sublicense, and/or sell *
11 .\" copies of the Software, and to permit persons to whom the Software is *
12 .\" furnished to do so, subject to the following conditions: *
13 .\" *
14 .\" The above copyright notice and this permission notice shall be included *
15 .\" in all copies or substantial portions of the Software. *
16 .\" *
17 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 .\" *
25 .\" Except as contained in this notice, the name(s) of the above copyright *
26 .\" holders shall not be used in advertising or otherwise to promote the *
27 .\" sale, use or other dealings in this Software without prior written *
28 .\" authorization. *
29 .\"***************************************************************************
30 .\"
31 .\" $Id: user_caps.5,v 1.51 2024/06/08 21:01:53 tom Exp $
32 .TH user_caps 5 2024-06-08 "ncurses 6.5" "File formats"
33 .ie \n(.g \{\
34 .ds `` \(lq
35 .ds '' \(rq
36 .\}
37 .el \{\
38 .ie t .ds `` ``
39 .el .ds `` ""
40 .ie t .ds '' ''
41 .el .ds '' ""
42 .\}
43 .
44 .de bP
45 .ie n .IP \(bu 4
46 .el .IP \(bu 2
47 ..
48 .SH NAME
49 user_caps \-
50 user-defined \fIterminfo\fR capability format
51 .SH SYNOPSIS
52 .B infocmp \-x
53 .PP
54 .B tic \-x
55 .SH DESCRIPTION
56 .SS Background
57 Before \fI\%ncurses\fP 5.0,
58 terminfo databases used a \fIfixed repertoire\fP of terminal
59 capabilities designed for the SVr2 terminal database in 1984,
60 and extended in stages through SVr4 (1989),
61 and standardized in X/Open Curses starting in 1995.
62 .\" That date is a surmise based on the capability list appearing in
63 .\" Issue 4, Version 2 (1996). That list is not in man page format in
64 .\" the standard, so lacks a "HISTORY" section. However, `tigetstr()`
65 .\" and `tputs()` are identified in the same document as new to Issue 4,
66 .\" so GBR conjectures that the list came in at the same time.
67 .PP
68 Most of the \fIextensions\fP in this fixed repertoire were additions
69 to the tables of Boolean, numeric and string capabilities.
70 Rather than change the meaning of an existing capability, a new name was added.
71 The terminfo database uses a binary format; binary compatibility was
72 ensured by using a header which gave the number of items in the
73 tables for each type of capability.
74 The standardization was incomplete:
75 .bP
76 The \fIbinary format\fP itself is not described
77 in the X/Open Curses documentation.
78 Only the \fIsource format\fP is described.
79 .IP
80 Library developers rely upon the SVr4 documentation,
81 and reverse-engineering the compiled terminfo files to match the binary format.
82 .bP
83 Lacking a standard for the binary format, most implementations
84 copy the SVr2 binary format, which uses 16-bit signed integers,
85 and is limited to 4096-byte entries.
86 .IP
87 The format cannot represent very large numeric capabilities,
88 nor can it represent large numbers of special keyboard definitions.
89 .bP
90 The tables of capability names differ between implementations.
91 .IP
92 Although they \fImay\fP provide all of the standard capability names,
93 the position in the tables differs because some features were added as needed,
94 while others were added (out of order) to comply with X/Open Curses.
95 .IP
96 While \fI\%ncurses\fP' repertoire of predefined capabilities is closest
97 to Solaris,
98 Solaris's terminfo database has a few differences from
99 the list published by X/Open Curses.
100 For example,
101 \fI\%ncurses\fP can be configured with tables which match the terminal
102 databases for AIX, HP-UX or OSF/1,
103 rather than the default Solaris-like configuration.
104 .bP
105 In SVr4 curses and \fI\%ncurses\fP,
106 the terminal database is defined at compile-time using a text file
107 which lists the different terminal capabilities.
108 .IP
109 In principle, the text-file can be extended,
110 but doing this requires recompiling and reinstalling the library.
111 The text-file used in \fI\%ncurses\fP for terminal capabilities includes
112 details for various systems past the documented X/Open Curses features.
113 For example, \fI\%ncurses\fP supports these capabilities in each configuration:
114 .RS 8
115 .TP 5
116 memory_lock
117 (meml)
118 lock memory above cursor
119 .TP 5
120 memory_unlock
121 (memu)
122 unlock memory
123 .TP 5
124 box_chars_1
125 (box1)
126 box characters primary set
127 .RE
128 .IP
129 The memory lock/unlock capabilities were included because they were used
130 in the X11R6 terminal description for \fBxterm\fP(1).
131 The \fIbox1\fP capability is used in tic to help with terminal descriptions
132 written for AIX.
133 .PP
134 During the 1990s, some users were reluctant to use terminfo
135 in spite of its performance advantages over termcap:
136 .bP
137 The fixed repertoire prevented users from adding features
138 for unanticipated terminal improvements
139 (or required them to reuse existing capabilities as a workaround).
140 .bP
141 The limitation to 16-bit signed integers was also mentioned.
142 Because termcap stores everything as a string,
143 it could represent larger numbers.
144 .PP
145 Although termcap's extensibility was rarely used
146 (it was never the \fIspeaker\fP who had actually used the feature),
147 the criticism had a point.
148 \fI\%ncurses\fP 5.0 provided a way to detect nonstandard capabilities,
149 determine their
150 type and optionally store and retrieve them in a way which did not interfere
151 with other applications.
152 These are referred to as \fIuser-defined capabilities\fP because no
153 modifications to the toolset's predefined capability names are needed.
154 .PP
155 The \fI\%ncurses\fP utilities \fBtic\fP and \fBinfocmp\fP have a
156 command-line option \*(``\-x\*('' to control whether the nonstandard
157 capabilities are stored or retrieved.
158 A library function \fBuse_extended_names\fP
159 is provided for the same purpose.
160 .PP
161 When compiling a terminal database, if \*(``\-x\*('' is set,
162 \fBtic\fP will store a user-defined capability if the capability name is not
163 one of the predefined names.
164 .PP
165 Because \fI\%ncurses\fP provides a termcap library interface,
166 these user-defined capabilities may be visible to termcap applications:
167 .bP
168 The termcap interface (like all implementations of termcap)
169 requires that the capability names are 2-characters.
170 .IP
171 When the capability is simple enough for use in a termcap application,
172 it is provided as a 2-character name.
173 .bP
174 There are other
175 user-defined capabilities which refer to features not usable in termcap,
176 e.g., parameterized strings that use more than two parameters
177 or use more than the trivial expression support provided by termcap.
178 For these, the terminfo database should have only capability names with
179 3 or more characters.
180 .bP
181 Some terminals can send distinct strings for special keys (cursor-,
182 keypad- or function-keys) depending on modifier keys (shift, control, etc.).
183 While terminfo and termcap have a set of 60 predefined function-key names,
184 to which a series of keys can be assigned,
185 that is insufficient for more than a dozen keys multiplied by more than
186 a couple of modifier combinations.
187 The \fI\%ncurses\fP database uses a convention based on \fBxterm\fP(1)
188 to provide extended special-key names.
189 .IP
190 Fitting that into termcap's limitation of 2-character names
191 would be pointless.
192 These extended keys are available only with terminfo.
193 .SS "Recognized Capabilities"
194 The \fI\%ncurses\fP library uses the user-definable capabilities.
195 While the terminfo database may have other extensions,
196 \fI\%ncurses\fP makes explicit checks for these:
197 .RS 3
198 .TP 3
199 AX
200 \fIBoolean\fP, asserts that the terminal interprets SGR 39 and SGR 49
201 by resetting the foreground and background color, respectively, to the default.
202 .IP
203 This is a feature recognized by the \fBscreen\fP program as well.
204 .TP 3
205 E3
206 \fIstring\fP, tells how to clear the terminal's scrollback buffer.
207 When present, the \fB\%clear\fP(1) program sends this before clearing
208 the terminal.
209 .IP
210 The command \*(``\fBtput clear\fP\*('' does the same thing.
211 .TP 3
212 NQ
213 \fIBoolean\fP,
214 used to suppress a consistency check in tic for the \fI\%ncurses\fP
215 capabilities
216 in user6 through user9 (u6, u7, u8 and u9)
217 which tell how to query the terminal's cursor position
218 and its device attributes.
219 .TP 3
220 RGB
221 \fIBoolean\fP, \fInumber\fP \fBor\fP \fIstring\fP,
222 used to assert that the
223 \fBset_a_foreground\fP and
224 \fBset_a_background\fP capabilities correspond to \fIdirect colors\fP,
225 using an RGB (red/green/blue) convention.
226 This capability allows the \fBcolor_content\fP function to
227 return appropriate values without requiring the application
228 to initialize colors using \fBinit_color\fP.
229 .IP
230 The capability type determines the values which \fI\%ncurses\fP sees:
231 .RS 3
232 .TP 3
233 \fIBoolean\fP
234 implies that the number of bits for red, green and blue are the same.
235 Using the maximum number of colors,
236 \fI\%ncurses\fP adds two,
237 divides that sum by three,
238 and assigns the result to red,
239 green and blue in that order.
240 .IP
241 If the number of bits needed for the number of colors is not a multiple
242 of three, the blue (and green) components lose in comparison to red.
243 .TP 3
244 \fInumber\fP
245 tells \fI\%ncurses\fP what result to add to red, green and blue.
246 If \fI\%ncurses\fP runs out of bits,
247 blue (and green) lose just as in the \fIBoolean\fP case.
248 .TP 3
249 \fIstring\fP
250 explicitly list the number of bits used for red, green and blue components
251 as a slash-separated list of decimal integers.
252 .RE
253 .IP
254 Because there are several RGB encodings in use,
255 applications which make assumptions about the number of bits per color
256 are unlikely to work reliably.
257 As a trivial case, for example, one could define \fBRGB#1\fP
258 to represent the standard eight ANSI colors, i.e., one bit per color.
259 .TP 3
260 U8
261 \fInumber\fP,
262 asserts that \fI\%ncurses\fP must use Unicode values for line-drawing
263 characters,
264 and that it should ignore the alternate character set capabilities
265 when the locale uses UTF-8 encoding.
266 For more information, see the discussion of
267 \fBNCURSES_NO_UTF8_ACS\fP in \fB\%ncurses\fP(3NCURSES).
268 .IP
269 Set this capability to a nonzero value to enable it.
270 .TP 3
271 XM
272 \fIstring\fP,
273 override \fI\%ncurses\fP's built-in string which
274 enables/disables \fBxterm\fP(1) mouse mode.
275 .IP
276 \fI\%ncurses\fP sends a character sequence to the terminal to initialize mouse mode,
277 and when the user clicks the mouse buttons or (in certain modes) moves the
278 mouse, handles the characters sent back by the terminal to tell it what
279 was done with the mouse.
280 .IP
281 The mouse protocol is enabled when
282 the \fImask\fP passed in the \fBmousemask\fP function is nonzero.
283 By default,
284 \fI\%ncurses\fP handles the responses for the X11 xterm mouse protocol.
285 It also knows about the \fISGR 1006\fP xterm mouse protocol,
286 but must to be told to look for this specifically.
287 It will not be able to guess which mode is used,
288 because the responses are enough alike that only confusion would result.
289 .IP
290 The \fBXM\fP capability has a single parameter.
291 If nonzero, the mouse protocol should be enabled.
292 If zero, the mouse protocol should be disabled.
293 \fI\%ncurses\fP inspects this capability if it is present,
294 to see whether the 1006 protocol is used.
295 If so, it expects the responses to use the \fISGR 1006\fP xterm mouse protocol.
296 .IP
297 The xterm mouse protocol is used by other terminal emulators.
298 The terminal database uses building-blocks for the various xterm mouse
299 protocols which can be used in customized terminal descriptions.
300 .IP
301 The terminal database building blocks for this mouse
302 feature also have an experimental capability \fIxm\fP.
303 The \*(``xm\*('' capability describes the mouse response.
304 Currently there is no interpreter which would use this
305 information to make the mouse support completely data-driven.
306 .IP
307 \fIxm\fP shows the format of the mouse responses.
308 In this experimental capability, the parameters are
309 .RS 5
310 .TP 5
311 .I p1
312 y-ordinate
313 .TP 5
314 .I p2
315 x-ordinate
316 .TP 5
317 .I p3
318 button
319 .TP 5
320 .I p4
321 state, e.g., pressed or released
322 .TP 5
323 .I p5
324 y-ordinate starting region
325 .TP 5
326 .I p6
327 x-ordinate starting region
328 .TP 5
329 .I p7
330 y-ordinate ending region
331 .TP 5
332 .I p8
333 x-ordinate ending region
334 .RE
335 .IP
336 Here are examples from the terminal database for the most commonly used
337 xterm mouse protocols:
338 .IP
339 .nf
340 xterm+x11mouse|X11 xterm mouse protocol,
341 kmous=\eE[M, XM=\eE[?1000%?%p1%{1}%=%th%el%;,
342 xm=\eE[M
343 %?%p4%t%p3%e%{3}%;%'\ '%+%c
344 %p2%'!'%+%c
345 %p1%'!'%+%c,
346
347 xterm+sm+1006|xterm SGR-mouse,
348 kmous=\eE[<, XM=\eE[?1006;1000%?%p1%{1}%=%th%el%;,
349 xm=\eE[<%i%p3%d;
350 %p1%d;
351 %p2%d;
352 %?%p4%tM%em%;,
353 .fi
354 .
355 .SS "Extended Key Definitions"
356 Several terminals provide the ability to send distinct strings for
357 combinations of modified special keys.
358 There is no standard for what those keys can send.
359 .PP
360 Since 1999, \fBxterm\fP(1) has supported
361 \fIshift\fP, \fIcontrol\fP, \fIalt\fP, and \fImeta\fP modifiers which produce
362 distinct special-key strings.
363 In a terminal description,
364 \fI\%ncurses\fP has no special knowledge of the modifiers used.
365 Applications can use the \fInaming convention\fP established for \fBxterm\fP
366 to find these special keys in the terminal description.
367 .PP
368 Starting with the
369 .I curses
370 convention that capability codes describing the input generated by a
371 terminal's key caps begin with \*(``k\*('',
372 and that shifted special keys use uppercase letters in their names,
373 .IR \%ncurses 's
374 terminal database defines the following names and codes to which a
375 suffix is added.
376 .PP
377 .RS 5
378 .TS
379 Lb Lb
380 Lb Lx.
381 Code Description
382 _
383 kDC shifted kdch1 (delete character)
384 .\" kDC is a standard capability; see X/Open Curses Issue 7, p. 345.
385 kDN shifted kcud1 (cursor down)
386 kEND shifted kend (end)
387 kHOM shifted khome (home)
388 kLFT shifted kcub1 (cursor back)
389 kNXT shifted knext (next)
390 kPRV shifted kprev (previous)
391 kRIT shifted kcuf1 (cursor forward)
392 kUP shifted kcuu1 (cursor up)
393 .TE
394 .RE
395 .PP
396 Keycap nomenclature on the Unix systems for which
397 .I curses
398 was developed differs from today's ubiquitous descendants of the IBM
399 PC/AT keyboard layout.
400 In the foregoing,
401 interpret \*(``backward\*('' as \*(``left\*('',
402 \*(``forward\*('' as \*(``right\*('',
403 \*(``next\*('' as \*(``page down\*('',
404 and
405 \*(``prev(ious)\*('' as \*(``page up\*(''.
406 .PP
407 These are the suffixes used to denote the modifiers:
408 .PP
409 .RS 5
410 .TS
411 tab(/) ;
412 l l .
413 \fBValue\fP/\fBDescription\fP
414 _
415 2/Shift
416 3/Alt
417 4/Shift + Alt
418 5/Control
419 6/Shift + Control
420 7/Alt + Control
421 8/Shift + Alt + Control
422 9/Meta
423 10/Meta + Shift
424 11/Meta + Alt
425 12/Meta + Alt + Shift
426 13/Meta + Ctrl
427 14/Meta + Ctrl + Shift
428 15/Meta + Ctrl + Alt
429 16/Meta + Ctrl + Alt + Shift
430 .TE
431 .RE
432 .PP
433 None of these are predefined; terminal descriptions can refer to \fInames\fP
434 which \fI\%ncurses\fP will allocate at runtime to \fIkey-codes\fP.
435 To use these keys in an \fI\%ncurses\fP program,
436 an application could do this:
437 .bP
438 using a list of extended key \fInames\fP,
439 ask \fB\%tigetstr\fP(3NCURSES) for their values, and
440 .bP
441 given the list of values,
442 ask \fB\%key_defined\fP(3NCURSES) for the \fIkey-code\fP which
443 would be returned for those keys by \fB\%wgetch\fP(3NCURSES).
444 .\"
445 .SH PORTABILITY
446 The \*(``\-x\*('' extension feature of \fBtic\fP and \fBinfocmp\fP
447 has been adopted in NetBSD curses.
448 That implementation stores user-defined capabilities,
449 but makes no use of these capabilities itself.
450 .\"
451 .SH AUTHORS
452 Thomas E. Dickey
453 .br
454 beginning with \fI\%ncurses\fP 5.0 (1999)
455 .\"
456 .SH SEE ALSO
457 \fB\%infocmp\fP(1),
458 \fB\%tic\fP(1)
459 .PP
460 The terminal database section
461 .I "NCURSES USER-DEFINABLE CAPABILITIES"
462 summarizes commonly-used user-defined capabilities
463 which are used in the terminal descriptions.
464 Some of those features are mentioned in \fB\%screen\fP(1) or
465 \fBtmux\fP(1).
466 .PP
467 .I "XTerm Control Sequences"
468 provides further information on the \fB\%xterm\fP(1) features
469 that are used in these extended capabilities.