man/user_caps.5

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