diff options
Diffstat (limited to 'man/user_caps.5')
| -rw-r--r-- | man/user_caps.5 | 584 |
1 files changed, 399 insertions, 185 deletions
diff --git a/man/user_caps.5 b/man/user_caps.5 index 219bbf5f9976..e4057737e9cb 100644 --- a/man/user_caps.5 +++ b/man/user_caps.5 @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" Copyright 2018-2024,2025 Thomas E. Dickey * .\" Copyright 2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: user_caps.5,v 1.49 2024/03/16 15:35:01 tom Exp $ -.TH user_caps 5 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats" +.\" $Id: user_caps.5,v 1.60 2025/11/12 01:01:01 tom Exp $ +.TH user_caps 5 2025-11-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -47,260 +47,456 @@ .. .SH NAME user_caps \- -user-defined \fIterminfo\fR capability format +user-defined \%\fIterm\%info\fP capability format .SH SYNOPSIS .B @INFOCMP@ \-x .PP .B @TIC@ \-x .SH DESCRIPTION .SS Background -Before \fI\%ncurses\fP 5.0, -terminfo databases used a \fIfixed repertoire\fP of terminal -capabilities designed for the SVr2 terminal database in 1984, -and extended in stages through SVr4 (1989), -and standardized in the Single Unix Specification beginning in 1995. +Prior to +.I \%ncurses +5.0 (1999), +.I \%term\%info +databases used a +.I "fixed repertoire" +of terminal capabilities designed +for the SVr2 terminal database in 1984, +added to in stages through SVr4 (1989), +and standardized in X/Open Curses starting in 1995. +.\" That date is a surmise based on the capability list appearing in +.\" Issue 4, Version 2 (1996). That list is not in man page format in +.\" the standard, so lacks a "HISTORY" section. However, `tigetstr()` +.\" and `tputs()` are identified in the same document as new to Issue 4, +.\" so GBR conjectures that the list came in at the same time. +.\" +.\" TED: the list is reflected in term.h, seen in examples from AIX 3 and 4, +.\" HP-UX 9, OSF/1, Solaris 2.4, dating from 1992-1994 -- all before 1996. +.\" The AIX 4 file has copyright dates starting in 1984; +.\" the Solaris file cites 1988 (the others have no copyright comments). +.\" Those term.h files note in a comment that it is generated by a script with +.\" a data file, i.e., +.\" term.h - this file is automatically made from caps and maketerm.ex. +.\" illumos-gate has related source, with a "caps" file having AT&T copyright +.\" for 1988, and UCB copyright for 1982, 1986, 1988. That 1982 is interesting +.\" (hinting that something may have been in the initial releases of System V) +.\" but the first release with tic appears to be SVr2 in 1984. .PP -Most of the \fIextensions\fP in this fixed repertoire were additions -to the tables of Boolean, numeric and string capabilities. -Rather than change the meaning of an existing capability, a new name was added. -The terminfo database uses a binary format; binary compatibility was -ensured by using a header which gave the number of items in the -tables for each type of capability. -The standardization was incomplete: +Most such additions to this fixed repertoire +suppelmented the tables of Boolean, +numeric, +and string capabilities. +Rather than changing the meaning of an existing capability, +a new name was added. +The +.I \%term\%info +database uses a binary format; +binary compatibility was ensured +by using a header +that counted the number of items in the tables +for each type of capability. +Because each +.I curses +vendor extended the standard capability lists in distinct ways, +a library could be programmed to recognize only compiled +.I \%term\%info +entries that it was prepared to interpret. +Standardization was incomplete. .bP -The \fIbinary format\fP itself is not described -in the X/Open Curses documentation. -Only the \fIsource format\fP is described. +X/Open Curses describes only the +.I source +format, +not its +.I binary +representation on disk. .IP -Library developers rely upon the SVr4 documentation, -and reverse-engineering the compiled terminfo files to match the binary format. +Library developers rely upon SVr4 documentation +and reverse engineering of compiled +.I \%term\%info +files to match the binary format. .bP -Lacking a standard for the binary format, most implementations -copy the SVr2 binary format, which uses 16-bit signed integers, +Lacking a standard for the binary format, +most implementations copy the SVr2 binary format, +which uses 16-bit signed integers, and is limited to 4096-byte entries. .IP -The format cannot represent very large numeric capabilities, -nor can it represent large numbers of special keyboard definitions. +The SVr2 format cannot represent very large numeric capability values, +nor can it represent large numbers of key definitions, +as are required to distinguish multiple modifier keys used +in combination with a function key. .bP The tables of capability names differ between implementations. .IP -Although they \fImay\fP provide all of the standard capability names, -the position in the tables differs because some features were added as needed, -while others were added (out of order) to comply with X/Open Curses. +Although they +.I may +provide all of the standard capability names, +each arranges its table entries differently +because some features were added as needed, +while others were added +\(em out of order \(em +for X/Open Curses conformance. .IP -While \fI\%ncurses\fP' repertoire of predefined capabilities is closest -to Solaris, -Solaris's terminfo database has a few differences from -the list published by X/Open Curses. -For example, -\fI\%ncurses\fP can be configured with tables which match the terminal -databases for AIX, HP-UX or OSF/1, +While +.IR ncurses 's +capability repertoire is closest to that of Solaris, +the set of capabilities supported by +each vendor's +.I \%term\%info +database differs +from the list published by X/Open Curses. +.I \%ncurses +can be configured +with tables that match the terminal databases +for AIX, +HP-UX, +or OSF/1, rather than the default Solaris-like configuration. .bP -In SVr4 curses and \fI\%ncurses\fP, -the terminal database is defined at compile-time using a text file -which lists the different terminal capabilities. +In SVr4 +.I curses +and +.IR \%ncurses "," +the terminal database is defined at compile time +by interpolating a text file +that lists the different terminal capabilities. .IP -In principle, the text-file can be extended, -but doing this requires recompiling and reinstalling the library. -The text-file used in \fI\%ncurses\fP for terminal capabilities includes -details for various systems past the documented X/Open Curses features. -For example, \fI\%ncurses\fP supports these capabilities in each configuration: +In principle, +the text file can be extended, +but doing so requires recompiling and reinstalling the library. +The text file used by +.I \%ncurses +for terminal capabilities includes details of extensions +to X/Open Curses +made by various systems. +For example, +.I \%ncurses +supports the following nonstandard capabilities in each configuration. .RS 8 .TP 5 -memory_lock -(meml) +.B memory_lock +.RB ( meml ) lock memory above cursor .TP 5 -memory_unlock -(memu) +.B memory_unlock +.RB ( memu ) unlock memory .TP 5 -box_chars_1 -(box1) +.B box_chars_1 +.RB ( box1 ) box characters primary set .RE .IP The memory lock/unlock capabilities were included because they were used -in the X11R6 terminal description for \fBxterm\fP(1). -The \fIbox1\fP capability is used in @TIC@ to help with terminal descriptions -written for AIX. +in the X11R6 terminal description for \fIxterm\fP(1). +.B \%@TIC@ +uses the +.B box1 +capability to cope with terminal descriptions written for AIX. .PP -During the 1990s, some users were reluctant to use terminfo -in spite of its performance advantages over termcap: +During the 1990s, +some application developers were reluctant to use +.I \%term\%info +in spite of its performance +(and other) +advantages over +.IR termcap "." .bP -The fixed repertoire prevented users from adding features -for unanticipated terminal improvements +The fixed repertoire prevented users from adding support +for terminal features unanticipated by X/Open Curses (or required them to reuse existing capabilities as a workaround). .bP The limitation to 16-bit signed integers was also mentioned. -Because termcap stores everything as a string, +Because +.I termcap +stores everything as a string, it could represent larger numbers. .PP -Although termcap's extensibility was rarely used -(it was never the \fIspeaker\fP who had actually used the feature), +Although +.IR termcap 's +extensibility was rarely used +\(em the claimant was never an implementor +who had actually exercised it \(em the criticism had a point. -\fI\%ncurses\fP 5.0 provided a way to detect nonstandard capabilities, -determine their -type and optionally store and retrieve them in a way which did not interfere -with other applications. -These are referred to as \fIuser-defined capabilities\fP because no -modifications to the toolset's predefined capability names are needed. +.I \%ncurses +5.0 provided a way to detect nonstandard capabilities, +to determine their type, +and to optionally store and retrieve them +in a way that did not interfere with other applications. +.I ncurses +terms these +.I "user-defined capabilities" +because no modifications +to the standard capability list are needed. .PP -The \fI\%ncurses\fP utilities \fB@TIC@\fP and \fB@INFOCMP@\fP have a -command-line option \*(``\-x\*('' to control whether the nonstandard -capabilities are stored or retrieved. -A library function \fBuse_extended_names\fP -is provided for the same purpose. +The +.I \%ncurses +utilities +.B \%@TIC@ +and +.B \%@INFOCMP@ +have a command-line option \*(``\-x\*('' +to control whether the nonstandard capabilities +are stored or retrieved. +.I \%ncurses +provides \fBuse_extended_names\fP(3X) to programs for the same purpose. .PP -When compiling a terminal database, if \*(``\-x\*('' is set, -\fB@TIC@\fP will store a user-defined capability if the capability name is not -one of the predefined names. +When compiling a terminal database, if \*(``\-x\*('' is used, +.B \%@TIC@ +stores a user-defined capability +if the capability name is not standard. .PP -Because \fI\%ncurses\fP provides a termcap library interface, -these user-defined capabilities may be visible to termcap applications: +Because +.I \%ncurses +provides a +.I termcap +library interface, +these user-defined capabilities may be visible to +.I termcap +applications. .bP -The termcap interface (like all implementations of termcap) -requires that the capability names are 2-characters. +The +.I termcap +interface +(like all implementations of +.IR termcap ) +restricts capability names to two characters. .IP -When the capability is simple enough for use in a termcap application, -it is provided as a 2-character name. +When the capability is simple enough for use in a +.I termcap +application, +it is provided as a two-character name. .bP -There are other -user-defined capabilities which refer to features not usable in termcap, -e.g., parameterized strings that use more than two parameters -or use more than the trivial expression support provided by termcap. -For these, the terminfo database should have only capability names with -3 or more characters. +Other user-defined capabilities employ features not usable in +.IR termcap "," +such as parameterized strings that use more than two parameters +or require more powerful expressions than +.I termcap +supports. +Such capabilities should, +in the +.I \%term\%info +database, +have names at least three characters in length. .bP Some terminals can send distinct strings for special keys (cursor-, keypad- or function-keys) depending on modifier keys (shift, control, etc.). -While terminfo and termcap have a set of 60 predefined function-key names, +While +.I \%term\%info +and +.I termcap +define a set of sixty function key names, to which a series of keys can be assigned, that is insufficient for more than a dozen keys multiplied by more than a couple of modifier combinations. -The \fI\%ncurses\fP database uses a convention based on \fBxterm\fP(1) +The +.I \%ncurses +database uses a convention based on \fIxterm\fP(1) to provide extended special-key names. .IP -Fitting that into termcap's limitation of 2-character names +Fitting that into +.IR termcap 's +limitation of 2-character names would be pointless. -These extended keys are available only with terminfo. +These extended keys are available only with +.IR \%term\%info "." .SS "Recognized Capabilities" -The \fI\%ncurses\fP library uses the user-definable capabilities. -While the terminfo database may have other extensions, -\fI\%ncurses\fP makes explicit checks for these: +The +.I \%ncurses +library employs user-definable capabilities. +While the +.I \%term\%info +database may have other extensions, +.I \%ncurses +makes explicit checks for the following. .RS 3 .TP 3 -AX -\fIBoolean\fP, asserts that the terminal interprets SGR 39 and SGR 49 -by resetting the foreground and background color, respectively, to the default. +.B AX +(Boolean) +asserts that the terminal interprets SGR 39 and SGR 49 +by resetting the foreground and background colors, +respectively, +to the default. .IP -This is a feature recognized by the \fBscreen\fP program as well. +\fBscreen\fP(1) +recognizes this capability as well. .TP 3 -E3 -\fIstring\fP, tells how to clear the terminal's scrollback buffer. -When present, the \fBclear\fP(1) program sends this before clearing -the terminal. +.B E3 +(string) +tells an application how to clear the terminal's scrollback buffer. +When present, +the \fBclear\fP(1) program sends this before clearing the terminal. .IP -The command \*(``\fBtput clear\fP\*('' does the same thing. +The command +.RB \*(`` "tput clear" \*('' +does the same thing. .TP 3 -NQ -\fIBoolean\fP, -used to suppress a consistency check in @TIC@ for the \fI\%ncurses\fP -capabilities -in user6 through user9 (u6, u7, u8 and u9) -which tell how to query the terminal's cursor position +.B NQ +(Boolean) +suppresses a consistency check in +.B \%@TIC@ +for the +.I \%ncurses +string capabilities +.B user6 +.RB ( u6 ) +through +.B user9 +.RB ( u9 ), +which tell an application how to query the terminal's cursor position and its device attributes. .TP 3 -RGB -\fIBoolean\fP, \fInumber\fP \fBor\fP \fIstring\fP, -used to assert that the -\fBset_a_foreground\fP and -\fBset_a_background\fP capabilities correspond to \fIdirect colors\fP, +.B RGB +(Boolean, +numeric, +or +string) +asserts that the +.B \%set_a_foreground +.RB ( setaf ) +and +.B \%set_a_background +.RB ( setab ) +capabilities employ +.IR "direct colors" "," using an RGB (red/green/blue) convention. -This capability allows the \fBcolor_content\fP function to -return appropriate values without requiring the application -to initialize colors using \fBinit_color\fP. +This capability allows \fBcolor_content\fP(3X) +to return appropriate values +without requiring the application +to initialize colors using \fBinit_color\fP(3X). .IP -The capability type determines the values which \fI\%ncurses\fP sees: +The capability type determines the values +.I \%ncurses +sees. .RS 3 .TP 3 -\fIBoolean\fP -implies that the number of bits for red, green and blue are the same. -Using the maximum number of colors, -\fI\%ncurses\fP adds two, -divides that sum by three, +Boolean +implies that the number of bits for red, +green, +and blue are the same. +Starting with the value of the capability +.B max_colors +.RB \%( colors ; +.I termcap: +.BR co ), +.I \%ncurses +adds two, +divides the sum by three, and assigns the result to red, -green and blue in that order. +green, +and blue, +in that order. .IP -If the number of bits needed for the number of colors is not a multiple -of three, the blue (and green) components lose in comparison to red. +If the number of bits needed for the number of colors +is not a multiple of three, +the blue (and green) color channels lose in comparison to red. .TP 3 -\fInumber\fP -tells \fI\%ncurses\fP what result to add to red, green and blue. -If \fI\%ncurses\fP runs out of bits, -blue (and green) lose just as in the \fIBoolean\fP case. +numeric +tells +.I \%ncurses +what result to add to red, +green, +and blue. +If +.I \%ncurses +runs out of bits, +blue (and green) lose just as in the Boolean case. .TP 3 -\fIstring\fP -explicitly list the number of bits used for red, green and blue components +string +specify the quantity of bits used for +red, +green, +and blue color channels as a slash-separated list of decimal integers. .RE .IP Because there are several RGB encodings in use, -applications which make assumptions about the number of bits per color +applications that make assumptions +about the number of bits per color channel are unlikely to work reliably. -As a trivial case, for example, one could define \fBRGB#1\fP -to represent the standard eight ANSI colors, i.e., one bit per color. +As a trivial case, +one could define +.B RGB#1 +to represent the standard eight ANSI\ X3.64/ECMA-48/ISO\ 6429 colors +using one bit per color channel. .TP 3 -U8 -\fInumber\fP, -asserts that \fI\%ncurses\fP must use Unicode values for line-drawing -characters, -and that it should ignore the alternate character set capabilities +.B U8 +(numeric) +asserts whether +.I \%ncurses +must use Unicode values for line-drawing characters, +and that it should ignore the alternate character set (ACS) capabilities when the locale uses UTF-8 encoding. -For more information, see the discussion of -\fBNCURSES_NO_UTF8_ACS\fP in \fB\%ncurses\fP(3X). +See the discussion of +.B \%NCURSES_NO_UTF8_ACS +in section \*(``ENVIRONMENT\*('' of \fB\%ncurses\fP(3X). .IP Set this capability to a nonzero value to enable it. .TP 3 -XM -\fIstring\fP, -override \fI\%ncurses\fP's built-in string which -enables/disables \fBxterm\fP(1) mouse mode. +.B XM +(string) +override +.IR \%ncurses 's +built-in string that directs \fIxterm\fP(1) +to enable or disable mouse mode. .IP -\fI\%ncurses\fP sends a character sequence to the terminal to initialize mouse mode, -and when the user clicks the mouse buttons or (in certain modes) moves the -mouse, handles the characters sent back by the terminal to tell it what -was done with the mouse. +.I \%ncurses +sends a character sequence to the terminal to initialize mouse mode, +and when the user clicks the mouse buttons or +(in certain modes) +moves the mouse, +handles the characters sent back by the terminal +to tell the application what was done with the mouse. .IP -The mouse protocol is enabled when -the \fImask\fP passed in the \fBmousemask\fP function is nonzero. +The mouse protocol is enabled +when the +.I \fImask\fP +argument to the \fBmousemask\fP(3X) function is nonzero. By default, -\fI\%ncurses\fP handles the responses for the X11 xterm mouse protocol. -It also knows about the \fISGR 1006\fP xterm mouse protocol, -but must to be told to look for this specifically. -It will not be able to guess which mode is used, +.I \%ncurses +handles the responses for the X11 +.I xterm +mouse protocol. +It also knows about the SGR\ 1006 +.I xterm +mouse protocol, +but must to be told to look for it specifically. +.I \%ncurses +is not be able to guess which of the two modes is used, because the responses are enough alike that only confusion would result. .IP -The \fBXM\fP capability has a single parameter. -If nonzero, the mouse protocol should be enabled. -If zero, the mouse protocol should be disabled. -\fI\%ncurses\fP inspects this capability if it is present, +The +.B XM +capability has a single numeric parameter. +If nonzero, +the mouse protocol should be enabled. +If zero, +the mouse protocol should be disabled. +.I \%ncurses +inspects this capability if it is present, to see whether the 1006 protocol is used. -If so, it expects the responses to use the \fISGR 1006\fP xterm mouse protocol. +If so, +it expects the responses to use the SGR\ 1006 +.I xterm +mouse protocol. .IP -The xterm mouse protocol is used by other terminal emulators. -The terminal database uses building-blocks for the various xterm mouse -protocols which can be used in customized terminal descriptions. +The +.I xterm +mouse protocol is used by other terminal emulators. +The terminal database uses building blocks for the various +.I xterm +mouse protocols usable in customized terminal descriptions. .IP -The terminal database building blocks for this mouse -feature also have an experimental capability \fIxm\fP. -The \*(``xm\*('' capability describes the mouse response. -Currently there is no interpreter which would use this -information to make the mouse support completely data-driven. +The terminal database building blocks for this mouse feature +also have an experimental capability, +.BR xm "," +that describes the mouse response. +No known interpreter uses this information, +which could make mouse support completely data-driven. .IP -\fIxm\fP shows the format of the mouse responses. -In this experimental capability, the parameters are +.B xm +shows the format of the mouse responses. +In this experimental capability, +the parameters are as follows. .RS 5 .TP 5 .I p1 @@ -329,8 +525,10 @@ x-ordinate ending region .RE .IP Here are examples from the terminal database for the most commonly used -xterm mouse protocols: +.I xterm +mouse protocols. .IP +.EX .nf xterm+x11mouse|X11 xterm mouse protocol, kmous=\eE[M, XM=\eE[?1000%?%p1%{1}%=%th%el%;, @@ -338,7 +536,7 @@ xterm mouse protocols: %?%p4%t%p3%e%{3}%;%'\ '%+%c %p2%'!'%+%c %p1%'!'%+%c, - +.IP xterm+sm+1006|xterm SGR-mouse, kmous=\eE[<, XM=\eE[?1006;1000%?%p1%{1}%=%th%el%;, xm=\eE[<%i%p3%d; @@ -346,18 +544,20 @@ xterm mouse protocols: %p2%d; %?%p4%tM%em%;, .fi +.EE . .SS "Extended Key Definitions" Several terminals provide the ability to send distinct strings for combinations of modified special keys. There is no standard for what those keys can send. .PP -Since 1999, \fBxterm\fP(1) has supported +Since 1999, \fIxterm\fP(1) has supported \fIshift\fP, \fIcontrol\fP, \fIalt\fP, and \fImeta\fP modifiers which produce distinct special-key strings. In a terminal description, \fI\%ncurses\fP has no special knowledge of the modifiers used. -Applications can use the \fInaming convention\fP established for \fBxterm\fP +Applications can use the \fInaming convention\fP established for +\fIxterm\fP to find these special keys in the terminal description. .PP Starting with the @@ -403,9 +603,10 @@ These are the suffixes used to denote the modifiers: .PP .RS 5 .TS -tab(/) ; -l l . -\fBValue\fP/\fBDescription\fP +tab(/); +Lb Lb +L L . +Value/Description _ 2/Shift 3/Alt @@ -425,8 +626,14 @@ _ .TE .RE .PP -None of these are predefined; terminal descriptions can refer to \fInames\fP -which \fI\%ncurses\fP will allocate at runtime to \fIkey-codes\fP. +.I ncurses +defines no capabilities for modified F-keys; +terminal descriptions can refer to +.I names +that +.I \%ncurses +allocates at runtime to +.IR "key codes" "." To use these keys in an \fI\%ncurses\fP program, an application could do this: .bP @@ -438,27 +645,34 @@ ask \fBkey_defined\fP(3X) for the \fIkey-code\fP which would be returned for those keys by \fBwgetch\fP(3X). .\" .SH PORTABILITY -The \*(``\-x\*('' extension feature of \fB@TIC@\fP and \fB@INFOCMP@\fP -has been adopted in NetBSD curses. +The \*(``\-x\*('' extension feature of +.B \%@TIC@ +and +.B \%@INFOCMP@ +has been adopted in NetBSD +.IR curses "." That implementation stores user-defined capabilities, but makes no use of these capabilities itself. .\" .SH AUTHORS Thomas E. Dickey .br -beginning with \fI\%ncurses\fP 5.0 (1999) +beginning with +.I \%ncurses +5.0 (1999) .\" .SH SEE ALSO \fB\%@INFOCMP@\fP(1M), \fB\%@TIC@\fP(1M) .PP -The terminal database section -.I "NCURSES USER-DEFINABLE CAPABILITIES" +In the source form of the terminal database, +.IR \%terminfo.src "," +the section \*(``NCURSES USER-DEFINABLE CAPABILITIES\*(''. summarizes commonly-used user-defined capabilities -which are used in the terminal descriptions. +employed in the terminal descriptions. Some of those features are mentioned in \fB\%screen\fP(1) or \fBtmux\fP(1). .PP .I "XTerm Control Sequences" -provides further information on the \fB\%xterm\fP(1) features +provides further information on the \fI\%xterm\fP(1) features that are used in these extended capabilities. |