Debian Codegraph @

upstream/mageia-cauldron/man5/user_caps.5

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