Debian Codegraph @

upstream/debian-unstable/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.60 2025/11/12 01:01:01 tom Exp $
32 .TH user_caps 5 2025-11-11 "ncurses 6.6" "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 \%\fIterm\%info\fP capability format
51 .SH SYNOPSIS
52 .B infocmp \-x
53 .PP
54 .B tic \-x
55 .SH DESCRIPTION
56 .SS Background
57 Prior to
58 .I \%ncurses
59 5.0 (1999),
60 .I \%term\%info
61 databases used a
62 .I "fixed repertoire"
63 of terminal capabilities designed
64 for the SVr2 terminal database in 1984,
65 added to in stages through SVr4 (1989),
66 and standardized in X/Open Curses starting in 1995.
67 .\" That date is a surmise based on the capability list appearing in
68 .\" Issue 4, Version 2 (1996). That list is not in man page format in
69 .\" the standard, so lacks a "HISTORY" section. However, `tigetstr()`
70 .\" and `tputs()` are identified in the same document as new to Issue 4,
71 .\" so GBR conjectures that the list came in at the same time.
72 .\"
73 .\" TED: the list is reflected in term.h, seen in examples from AIX 3 and 4,
74 .\" HP-UX 9, OSF/1, Solaris 2.4, dating from 1992-1994 -- all before 1996.
75 .\" The AIX 4 file has copyright dates starting in 1984;
76 .\" the Solaris file cites 1988 (the others have no copyright comments).
77 .\" Those term.h files note in a comment that it is generated by a script with
78 .\" a data file, i.e.,
79 .\" term.h - this file is automatically made from caps and maketerm.ex.
80 .\" illumos-gate has related source, with a "caps" file having AT&T copyright
81 .\" for 1988, and UCB copyright for 1982, 1986, 1988. That 1982 is interesting
82 .\" (hinting that something may have been in the initial releases of System V)
83 .\" but the first release with tic appears to be SVr2 in 1984.
84 .PP
85 Most such additions to this fixed repertoire
86 suppelmented the tables of Boolean,
87 numeric,
88 and string capabilities.
89 Rather than changing the meaning of an existing capability,
90 a new name was added.
91 The
92 .I \%term\%info
93 database uses a binary format;
94 binary compatibility was ensured
95 by using a header
96 that counted the number of items in the tables
97 for each type of capability.
98 Because each
99 .I curses
100 vendor extended the standard capability lists in distinct ways,
101 a library could be programmed to recognize only compiled
102 .I \%term\%info
103 entries that it was prepared to interpret.
104 Standardization was incomplete.
105 .bP
106 X/Open Curses describes only the
107 .I source
108 format,
109 not its
110 .I binary
111 representation on disk.
112 .IP
113 Library developers rely upon SVr4 documentation
114 and reverse engineering of compiled
115 .I \%term\%info
116 files to match the binary format.
117 .bP
118 Lacking a standard for the binary format,
119 most implementations copy the SVr2 binary format,
120 which uses 16-bit signed integers,
121 and is limited to 4096-byte entries.
122 .IP
123 The SVr2 format cannot represent very large numeric capability values,
124 nor can it represent large numbers of key definitions,
125 as are required to distinguish multiple modifier keys used
126 in combination with a function key.
127 .bP
128 The tables of capability names differ between implementations.
129 .IP
130 Although they
131 .I may
132 provide all of the standard capability names,
133 each arranges its table entries differently
134 because some features were added as needed,
135 while others were added
136 \(em out of order \(em
137 for X/Open Curses conformance.
138 .IP
139 While
140 .IR ncurses 's
141 capability repertoire is closest to that of Solaris,
142 the set of capabilities supported by
143 each vendor's
144 .I \%term\%info
145 database differs
146 from the list published by X/Open Curses.
147 .I \%ncurses
148 can be configured
149 with tables that match the terminal databases
150 for AIX,
151 HP-UX,
152 or OSF/1,
153 rather than the default Solaris-like configuration.
154 .bP
155 In SVr4
156 .I curses
157 and
158 .IR \%ncurses ","
159 the terminal database is defined at compile time
160 by interpolating a text file
161 that lists the different terminal capabilities.
162 .IP
163 In principle,
164 the text file can be extended,
165 but doing so requires recompiling and reinstalling the library.
166 The text file used by
167 .I \%ncurses
168 for terminal capabilities includes details of extensions
169 to X/Open Curses
170 made by various systems.
171 For example,
172 .I \%ncurses
173 supports the following nonstandard capabilities in each configuration.
174 .RS 8
175 .TP 5
176 .B memory_lock
177 .RB ( meml )
178 lock memory above cursor
179 .TP 5
180 .B memory_unlock
181 .RB ( memu )
182 unlock memory
183 .TP 5
184 .B box_chars_1
185 .RB ( box1 )
186 box characters primary set
187 .RE
188 .IP
189 The memory lock/unlock capabilities were included because they were used
190 in the X11R6 terminal description for \fIxterm\fP(1).
191 .B \%tic
192 uses the
193 .B box1
194 capability to cope with terminal descriptions written for AIX.
195 .PP
196 During the 1990s,
197 some application developers were reluctant to use
198 .I \%term\%info
199 in spite of its performance
200 (and other)
201 advantages over
202 .IR termcap "."
203 .bP
204 The fixed repertoire prevented users from adding support
205 for terminal features unanticipated by X/Open Curses
206 (or required them to reuse existing capabilities as a workaround).
207 .bP
208 The limitation to 16-bit signed integers was also mentioned.
209 Because
210 .I termcap
211 stores everything as a string,
212 it could represent larger numbers.
213 .PP
214 Although
215 .IR termcap 's
216 extensibility was rarely used
217 \(em the claimant was never an implementor
218 who had actually exercised it \(em
219 the criticism had a point.
220 .I \%ncurses
221 5.0 provided a way to detect nonstandard capabilities,
222 to determine their type,
223 and to optionally store and retrieve them
224 in a way that did not interfere with other applications.
225 .I ncurses
226 terms these
227 .I "user-defined capabilities"
228 because no modifications
229 to the standard capability list are needed.
230 .PP
231 The
232 .I \%ncurses
233 utilities
234 .B \%tic
235 and
236 .B \%infocmp
237 have a command-line option \*(``\-x\*(''
238 to control whether the nonstandard capabilities
239 are stored or retrieved.
240 .I \%ncurses
241 provides \fBuse_extended_names\fP(3NCURSES) to programs for the same purpose.
242 .PP
243 When compiling a terminal database, if \*(``\-x\*('' is used,
244 .B \%tic
245 stores a user-defined capability
246 if the capability name is not standard.
247 .PP
248 Because
249 .I \%ncurses
250 provides a
251 .I termcap
252 library interface,
253 these user-defined capabilities may be visible to
254 .I termcap
255 applications.
256 .bP
257 The
258 .I termcap
259 interface
260 (like all implementations of
261 .IR termcap )
262 restricts capability names to two characters.
263 .IP
264 When the capability is simple enough for use in a
265 .I termcap
266 application,
267 it is provided as a two-character name.
268 .bP
269 Other user-defined capabilities employ features not usable in
270 .IR termcap ","
271 such as parameterized strings that use more than two parameters
272 or require more powerful expressions than
273 .I termcap
274 supports.
275 Such capabilities should,
276 in the
277 .I \%term\%info
278 database,
279 have names at least three characters in length.
280 .bP
281 Some terminals can send distinct strings for special keys (cursor-,
282 keypad- or function-keys) depending on modifier keys (shift, control, etc.).
283 While
284 .I \%term\%info
285 and
286 .I termcap
287 define a set of sixty function key names,
288 to which a series of keys can be assigned,
289 that is insufficient for more than a dozen keys multiplied by more than
290 a couple of modifier combinations.
291 The
292 .I \%ncurses
293 database uses a convention based on \fIxterm\fP(1)
294 to provide extended special-key names.
295 .IP
296 Fitting that into
297 .IR termcap 's
298 limitation of 2-character names
299 would be pointless.
300 These extended keys are available only with
301 .IR \%term\%info "."
302 .SS "Recognized Capabilities"
303 The
304 .I \%ncurses
305 library employs user-definable capabilities.
306 While the
307 .I \%term\%info
308 database may have other extensions,
309 .I \%ncurses
310 makes explicit checks for the following.
311 .RS 3
312 .TP 3
313 .B AX
314 (Boolean)
315 asserts that the terminal interprets SGR 39 and SGR 49
316 by resetting the foreground and background colors,
317 respectively,
318 to the default.
319 .IP
320 \fBscreen\fP(1)
321 recognizes this capability as well.
322 .TP 3
323 .B E3
324 (string)
325 tells an application how to clear the terminal's scrollback buffer.
326 When present,
327 the \fBclear\fP(1) program sends this before clearing the terminal.
328 .IP
329 The command
330 .RB \*(`` "tput clear" \*(''
331 does the same thing.
332 .TP 3
333 .B NQ
334 (Boolean)
335 suppresses a consistency check in
336 .B \%tic
337 for the
338 .I \%ncurses
339 string capabilities
340 .B user6
341 .RB ( u6 )
342 through
343 .B user9
344 .RB ( u9 ),
345 which tell an application how to query the terminal's cursor position
346 and its device attributes.
347 .TP 3
348 .B RGB
349 (Boolean,
350 numeric,
351 or
352 string)
353 asserts that the
354 .B \%set_a_foreground
355 .RB ( setaf )
356 and
357 .B \%set_a_background
358 .RB ( setab )
359 capabilities employ
360 .IR "direct colors" ","
361 using an RGB (red/green/blue) convention.
362 This capability allows \fBcolor_content\fP(3NCURSES)
363 to return appropriate values
364 without requiring the application
365 to initialize colors using \fBinit_color\fP(3NCURSES).
366 .IP
367 The capability type determines the values
368 .I \%ncurses
369 sees.
370 .RS 3
371 .TP 3
372 Boolean
373 implies that the number of bits for red,
374 green,
375 and blue are the same.
376 Starting with the value of the capability
377 .B max_colors
378 .RB \%( colors ;
379 .I termcap:
380 .BR co ),
381 .I \%ncurses
382 adds two,
383 divides the sum by three,
384 and assigns the result to red,
385 green,
386 and blue,
387 in that order.
388 .IP
389 If the number of bits needed for the number of colors
390 is not a multiple of three,
391 the blue (and green) color channels lose in comparison to red.
392 .TP 3
393 numeric
394 tells
395 .I \%ncurses
396 what result to add to red,
397 green,
398 and blue.
399 If
400 .I \%ncurses
401 runs out of bits,
402 blue (and green) lose just as in the Boolean case.
403 .TP 3
404 string
405 specify the quantity of bits used for
406 red,
407 green,
408 and blue color channels
409 as a slash-separated list of decimal integers.
410 .RE
411 .IP
412 Because there are several RGB encodings in use,
413 applications that make assumptions
414 about the number of bits per color channel
415 are unlikely to work reliably.
416 As a trivial case,
417 one could define
418 .B RGB#1
419 to represent the standard eight ANSI\ X3.64/ECMA-48/ISO\ 6429 colors
420 using one bit per color channel.
421 .TP 3
422 .B U8
423 (numeric)
424 asserts whether
425 .I \%ncurses
426 must use Unicode values for line-drawing characters,
427 and that it should ignore the alternate character set (ACS) capabilities
428 when the locale uses UTF-8 encoding.
429 See the discussion of
430 .B \%NCURSES_NO_UTF8_ACS
431 in section \*(``ENVIRONMENT\*('' of \fB\%ncurses\fP(3NCURSES).
432 .IP
433 Set this capability to a nonzero value to enable it.
434 .TP 3
435 .B XM
436 (string)
437 override
438 .IR \%ncurses 's
439 built-in string that directs \fIxterm\fP(1)
440 to enable or disable mouse mode.
441 .IP
442 .I \%ncurses
443 sends a character sequence to the terminal to initialize mouse mode,
444 and when the user clicks the mouse buttons or
445 (in certain modes)
446 moves the mouse,
447 handles the characters sent back by the terminal
448 to tell the application what was done with the mouse.
449 .IP
450 The mouse protocol is enabled
451 when the
452 .I \fImask\fP
453 argument to the \fBmousemask\fP(3NCURSES) function is nonzero.
454 By default,
455 .I \%ncurses
456 handles the responses for the X11
457 .I xterm
458 mouse protocol.
459 It also knows about the SGR\ 1006
460 .I xterm
461 mouse protocol,
462 but must to be told to look for it specifically.
463 .I \%ncurses
464 is not be able to guess which of the two modes is used,
465 because the responses are enough alike that only confusion would result.
466 .IP
467 The
468 .B XM
469 capability has a single numeric parameter.
470 If nonzero,
471 the mouse protocol should be enabled.
472 If zero,
473 the mouse protocol should be disabled.
474 .I \%ncurses
475 inspects this capability if it is present,
476 to see whether the 1006 protocol is used.
477 If so,
478 it expects the responses to use the SGR\ 1006
479 .I xterm
480 mouse protocol.
481 .IP
482 The
483 .I xterm
484 mouse protocol is used by other terminal emulators.
485 The terminal database uses building blocks for the various
486 .I xterm
487 mouse protocols usable in customized terminal descriptions.
488 .IP
489 The terminal database building blocks for this mouse feature
490 also have an experimental capability,
491 .BR xm ","
492 that describes the mouse response.
493 No known interpreter uses this information,
494 which could make mouse support completely data-driven.
495 .IP
496 .B xm
497 shows the format of the mouse responses.
498 In this experimental capability,
499 the parameters are as follows.
500 .RS 5
501 .TP 5
502 .I p1
503 y-ordinate
504 .TP 5
505 .I p2
506 x-ordinate
507 .TP 5
508 .I p3
509 button
510 .TP 5
511 .I p4
512 state, e.g., pressed or released
513 .TP 5
514 .I p5
515 y-ordinate starting region
516 .TP 5
517 .I p6
518 x-ordinate starting region
519 .TP 5
520 .I p7
521 y-ordinate ending region
522 .TP 5
523 .I p8
524 x-ordinate ending region
525 .RE
526 .IP
527 Here are examples from the terminal database for the most commonly used
528 .I xterm
529 mouse protocols.
530 .IP
531 .EX
532 .nf
533 xterm+x11mouse|X11 xterm mouse protocol,
534 kmous=\eE[M, XM=\eE[?1000%?%p1%{1}%=%th%el%;,
535 xm=\eE[M
536 %?%p4%t%p3%e%{3}%;%'\ '%+%c
537 %p2%'!'%+%c
538 %p1%'!'%+%c,
539 .IP
540 xterm+sm+1006|xterm SGR-mouse,
541 kmous=\eE[<, XM=\eE[?1006;1000%?%p1%{1}%=%th%el%;,
542 xm=\eE[<%i%p3%d;
543 %p1%d;
544 %p2%d;
545 %?%p4%tM%em%;,
546 .fi
547 .EE
548 .
549 .SS "Extended Key Definitions"
550 Several terminals provide the ability to send distinct strings for
551 combinations of modified special keys.
552 There is no standard for what those keys can send.
553 .PP
554 Since 1999, \fIxterm\fP(1) has supported
555 \fIshift\fP, \fIcontrol\fP, \fIalt\fP, and \fImeta\fP modifiers which produce
556 distinct special-key strings.
557 In a terminal description,
558 \fI\%ncurses\fP has no special knowledge of the modifiers used.
559 Applications can use the \fInaming convention\fP established for
560 \fIxterm\fP
561 to find these special keys in the terminal description.
562 .PP
563 Starting with the
564 .I curses
565 convention that capability codes describing the input generated by a
566 terminal's key caps begin with \*(``k\*('',
567 and that shifted special keys use uppercase letters in their names,
568 .IR \%ncurses 's
569 terminal database defines the following names and codes to which a
570 suffix is added.
571 .PP
572 .RS 5
573 .TS
574 Lb Lb
575 Lb Lx.
576 Code Description
577 _
578 kDC shifted kdch1 (delete character)
579 .\" kDC is a standard capability; see X/Open Curses Issue 7, p. 345.
580 kDN shifted kcud1 (cursor down)
581 kEND shifted kend (end)
582 kHOM shifted khome (home)
583 kLFT shifted kcub1 (cursor back)
584 kNXT shifted knext (next)
585 kPRV shifted kprev (previous)
586 kRIT shifted kcuf1 (cursor forward)
587 kUP shifted kcuu1 (cursor up)
588 .TE
589 .RE
590 .PP
591 Keycap nomenclature on the Unix systems for which
592 .I curses
593 was developed differs from today's ubiquitous descendants of the IBM
594 PC/AT keyboard layout.
595 In the foregoing,
596 interpret \*(``backward\*('' as \*(``left\*('',
597 \*(``forward\*('' as \*(``right\*('',
598 \*(``next\*('' as \*(``page down\*('',
599 and
600 \*(``prev(ious)\*('' as \*(``page up\*(''.
601 .PP
602 These are the suffixes used to denote the modifiers:
603 .PP
604 .RS 5
605 .TS
606 tab(/);
607 Lb Lb
608 L L .
609 Value/Description
610 _
611 2/Shift
612 3/Alt
613 4/Shift + Alt
614 5/Control
615 6/Shift + Control
616 7/Alt + Control
617 8/Shift + Alt + Control
618 9/Meta
619 10/Meta + Shift
620 11/Meta + Alt
621 12/Meta + Alt + Shift
622 13/Meta + Ctrl
623 14/Meta + Ctrl + Shift
624 15/Meta + Ctrl + Alt
625 16/Meta + Ctrl + Alt + Shift
626 .TE
627 .RE
628 .PP
629 .I ncurses
630 defines no capabilities for modified F-keys;
631 terminal descriptions can refer to
632 .I names
633 that
634 .I \%ncurses
635 allocates at runtime to
636 .IR "key codes" "."
637 To use these keys in an \fI\%ncurses\fP program,
638 an application could do this:
639 .bP
640 using a list of extended key \fInames\fP,
641 ask \fBtigetstr\fP(3NCURSES) for their values, and
642 .bP
643 given the list of values,
644 ask \fBkey_defined\fP(3NCURSES) for the \fIkey-code\fP which
645 would be returned for those keys by \fBwgetch\fP(3NCURSES).
646 .\"
647 .SH PORTABILITY
648 The \*(``\-x\*('' extension feature of
649 .B \%tic
650 and
651 .B \%infocmp
652 has been adopted in NetBSD
653 .IR curses "."
654 That implementation stores user-defined capabilities,
655 but makes no use of these capabilities itself.
656 .\"
657 .SH AUTHORS
658 Thomas E. Dickey
659 .br
660 beginning with
661 .I \%ncurses
662 5.0 (1999)
663 .\"
664 .SH SEE ALSO
665 \fB\%infocmp\fP(1),
666 \fB\%tic\fP(1)
667 .PP
668 In the source form of the terminal database,
669 .IR \%terminfo.src ","
670 the section \*(``NCURSES USER-DEFINABLE CAPABILITIES\*(''.
671 summarizes commonly-used user-defined capabilities
672 employed in the terminal descriptions.
673 Some of those features are mentioned in \fB\%screen\fP(1) or
674 \fBtmux\fP(1).
675 .PP
676 .I "XTerm Control Sequences"
677 provides further information on the \fI\%xterm\fP(1) features
678 that are used in these extended capabilities.