diff options
Diffstat (limited to 'upstream/opensuse-leap-15-6/man5/user_caps.5')
| -rw-r--r-- | upstream/opensuse-leap-15-6/man5/user_caps.5 | 313 |
1 files changed, 313 insertions, 0 deletions
diff --git a/upstream/opensuse-leap-15-6/man5/user_caps.5 b/upstream/opensuse-leap-15-6/man5/user_caps.5 new file mode 100644 index 00000000..592b35bc --- /dev/null +++ b/upstream/opensuse-leap-15-6/man5/user_caps.5 @@ -0,0 +1,313 @@ +.\"*************************************************************************** +.\" Copyright (c) 2017,2018 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: user_caps.5,v 1.7 2018/02/17 19:07:01 tom Exp $ +.TH user_caps 5 +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de NS +.ie n .sp +.el .sp .5 +.ie n .in +4 +.el .in +2 +.nf +.ft C \" Courier +.. +.de NE +.fi +.ft R +.in -4 +.. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +user_caps \- user-defined terminfo capabilities +.SH SYNOPSIS +.B tic -x, infocmp -x +.SH DESCRIPTION +.SS Background +.PP +Before ncurses 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. +.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: +.bP +The \fIbinary format\fP itself is not described +in the X/Open Curses documentation. +Only the \fIsource format\fP is described. +.IP +Library developers rely upon the SVr4 documentation, +and reverse-engineering the compiled terminfo 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, +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. +.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. +.IP +While ncurses' repertoire of predefined capabilities is closest to Solaris, +Solaris's terminfo database has a few differences from +the list published by X/Open Curses. +.PP +During the 1990s, some users were reluctant to use terminfo +in spite of its performance advantages over termcap: +.bP +The fixed repertoire prevented users from adding features +for unanticipated terminal improvements +(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, +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), +the criticism had a point. +ncurses 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. +.PP +The ncurses utilities \fBtic\fP and \fBinfocmp\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. +.PP +When compiling a terminal database, if \*(``\-x\*('' is set, +\fBtic\fP will store a user-defined capability if the capability name is not +one of the predefined names. +.PP +Because ncurses provides a termcap library interface, +these user-defined capabilities may be visible to termcap applications: +.bP +The termcap interface (like all implementations of termcap) +requires that the capability names are 2-characters. +.IP +When the capability is simple enough for use in a termcap application, +it is provided as a 2-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. +.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, +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 ncurses database uses a convention based on \fBxterm\fP to +provide extended special-key names. +.IP +Fitting that into termcap's limitation of 2-character names +would be pointless. +These extended keys are available only with terminfo. +.SS Recognized capabilities +.PP +The ncurses library uses the user-definable capabilities. +While the terminfo database may have other extensions, +ncurses makes explicit checks for these: +.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. +.IP +This is a feature recognized by the \fBscreen\fP program 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. +.IP +The command \*(``\fBtput clear\fP\*('' does the same thing. +.TP 3 +RGB +\fIboolean\fP, \fInumber\fP \fBor\fP \fIstring\fP, +to assert that the +\fBset_a_foreground\fP and +\fBset_a_background\fP capabilities correspond to \fIdirect colors\fP, +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. +.IP +The capability type determines the values which 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, +ncurses adds two, divides that sum by three, and assigns the result +to red, 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. +.TP 3 +\fInumber\fP +tells ncurses what result to add to red, green and blue. +If ncurses runs out of bits, +blue (and green) lose just as in the \fIboolean\fP case. +.TP 3 +\fIstring\fP +explicitly list the number of bits used for red, green and blue components +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 +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. +.TP 3 +U8 +\fInumber\fP, +asserts that ncurses must use Unicode values for line-drawing characters, +and that it should ignore the alternate character set capabilities +when the locale uses UTF-8 encoding. +For more information, see the discussion of +\fBNCURSES_NO_UTF8_ACS\fP in \fBncurses\fP(3X). +.IP +Set this capability to a nonzero value to enable it. +.TP 3 +XM +\fIstring\fP, +override ncurses's built-in string which +enables/disables \fBxterm\fP mouse mode. +. +.SS Extended key-definitions +.PP +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 has supported +\fIshift\fP, \fIcontrol\fP, \fIalt\fP, and \fImeta\fP modifiers which produce +distinct special-key strings. +In a terminal description, ncurses has no special knowledge of the +modifiers used. +Applications can use the \fInaming convention\fP established for \fBxterm\fP +to find these special keys in the terminal description. +.PP +Starting with the curses convention that \fIkey names\fP begin with \*(``k\*('' +and that shifted special keys are an uppercase name, +ncurses' terminal database defines these names to which a suffix is added: +.RS 5 +.TS +tab(/) ; +l l . +\fIName\fR/\fIDescription\fR +_ +kDC/special form of kdch1 (delete character) +kDN/special form of kcud1 (cursor down) +kEND/special form of kend (End) +kHOM/special form of khome (Home) +kLFT/special form of kcub1 (cursor-left or cursor-back) +kNXT/special form of knext (Next, or Page-Down) +kPRV/special form of kprev (Prev, or Page-Up) +kRIT/special form of kcuf1 (cursor-right, or cursor-forward) +kUP/special form of kcuu1 (cursor-up) +.TE +.RE +.PP +These are the suffixes used to denote the modifiers: +.RS 5 +.TS +tab(/) ; +l l . +\fIValue\fR/\fIDescription\fR +_ +2/Shift +3/Alt +4/Shift + Alt +5/Control +6/Shift + Control +7/Alt + Control +8/Shift + Alt + Control +9/Meta +10/Meta + Shift +11/Meta + Alt +12/Meta + Alt + Shift +13/Meta + Ctrl +14/Meta + Ctrl + Shift +15/Meta + Ctrl + Alt +16/Meta + Ctrl + Alt + Shift +.TE +.RE +.PP +None of these are predefined; terminal descriptions can refer to \fInames\fP +which ncurses will allocate at runtime to \fIkey-codes\fP. +To use these keys in an ncurses program, an application could do this: +.bP +using a list of extended key \fInames\fP, +ask \fBtigetstr\fP(3X) for their values, and +.bP +given the list of values, +ask \fBkey_defined\fP(3X) for the \fIkey-code\fP which +would be returned for those keys by \fBwgetch\fP(3X). +.PP +.SH PORTABILITY +.PP +The \*(``\-x\*('' extension feature of \fBtic\fP and \fBinfocmp\fP +has been adopted in NetBSD curses. +That implementation stores user-defined capabilities, +but makes no use of these capabilities itself. +.SH SEE ALSO +.PP +\fBtic\fR(1), +\fBinfocmp\fR(1). +.SH AUTHORS +.PP +Thomas E. Dickey +.br +beginning with ncurses 5.0 (1999) |