1user_caps(5)                  File Formats Manual                 user_caps(5)
2
3
4

NAME

6       user_caps - user-defined terminfo capabilities
7

SYNOPSIS

9       tic -x, infocmp -x
10

DESCRIPTION

12   Background
13       Before  ncurses 5.0, terminfo databases used a fixed repertoire of ter‐
14       minal capabilities designed for the SVr2 terminal database in 1984, and
15       extended  in stages through SVr4 (1989), and standardized in the Single
16       Unix Specification beginning in 1995.
17
18       Most of the extensions in this fixed repertoire were additions  to  the
19       tables of boolean, numeric and string capabilities.  Rather than change
20       the meaning of an existing capability, a new name was added.  The  ter‐
21       minfo  database  uses a binary format; binary compatibility was ensured
22       by using a header which gave the number of items in the tables for each
23       type of capability.  The standardization was incomplete:
24
25       •   The binary format itself is not described in the X/Open Curses doc‐
26           umentation.  Only the source format is described.
27
28           Library developers rely upon the SVr4 documentation,  and  reverse-
29           engineering the compiled terminfo files to match the binary format.
30
31       •   Lacking a standard for the binary format, most implementations copy
32           the SVr2 binary format, which uses 16-bit signed integers,  and  is
33           limited to 4096-byte entries.
34
35           The  format  cannot  represent very large numeric capabilities, nor
36           can it represent large numbers of special keyboard definitions.
37
38       •   The tables of capability names differ between implementations.
39
40           Although they may provide all of the standard capability names, the
41           position  in the tables differs because some features were added as
42           needed, while others were added  (out  of  order)  to  comply  with
43           X/Open Curses.
44
45           While  ncurses' repertoire of predefined capabilities is closest to
46           Solaris, Solaris's terminfo database has a few differences from the
47           list  published by X/Open Curses.  For example, ncurses can be con‐
48           figured with tables which match the terminal databases for AIX, HP-
49           UX or OSF/1, rather than the default Solaris-like configuration.
50
51       •   In  SVr4  curses  and  ncurses, the terminal database is defined at
52           compile-time using a text file which lists the  different  terminal
53           capabilities.
54
55           In  principle,  the  text-file  can be extended, but doing this re‐
56           quires recompiling and reinstalling  the  library.   The  text-file
57           used in ncurses for terminal capabilities includes details for var‐
58           ious systems past the documented X/Open Curses features.  For exam‐
59           ple, ncurses supports these capabilities in each configuration:
60
61               memory_lock
62                    (meml) lock memory above cursor
63
64               memory_unlock
65                    (memu) unlock memory
66
67               box_chars_1
68                    (box1) box characters primary set
69
70           The memory lock/unlock capabilities were included because they were
71           used in the X11R6 terminal description for xterm(1).  The box1  ca‐
72           pability  is used in tic to help with terminal descriptions written
73           for AIX.
74
75       During the 1990s, some users were reluctant to use terminfo in spite of
76       its performance advantages over termcap:
77
78       •   The fixed repertoire prevented users from adding features for unan‐
79           ticipated terminal improvements (or required them to reuse existing
80           capabilities as a workaround).
81
82       •   The  limitation  to 16-bit signed integers was also mentioned.  Be‐
83           cause termcap stores everything as a  string,  it  could  represent
84           larger numbers.
85
86       Although  termcap's  extensibility  was  rarely  used (it was never the
87       speaker who had actually used the feature), the criticism had a  point.
88       ncurses  5.0  provided a way to detect nonstandard capabilities, deter‐
89       mine their type and optionally store and retrieve them in a  way  which
90       did  not  interfere  with other applications.  These are referred to as
91       user-defined capabilities because no  modifications  to  the  toolset's
92       predefined capability names are needed.
93
94       The  ncurses  utilities tic and infocmp have a command-line option “-x”
95       to control whether the  nonstandard  capabilities  are  stored  or  re‐
96       trieved.   A  library  function  use_extended_names is provided for the
97       same purpose.
98
99       When compiling a terminal database, if “-x” is set, tic  will  store  a
100       user-defined capability if the capability name is not one of the prede‐
101       fined names.
102
103       Because ncurses provides a termcap library  interface,  these  user-de‐
104       fined capabilities may be visible to termcap applications:
105
106       •   The  termcap  interface  (like  all implementations of termcap) re‐
107           quires that the capability names are 2-characters.
108
109           When the capability is simple enough for use in a termcap  applica‐
110           tion, it is provided as a 2-character name.
111
112       •   There  are  other user-defined capabilities which refer to features
113           not usable in termcap, e.g., parameterized strings  that  use  more
114           than two parameters or use more than the trivial expression support
115           provided by termcap.  For these, the terminfo database should  have
116           only capability names with 3 or more characters.
117
118       •   Some terminals can send distinct strings for special keys (cursor-,
119           keypad- or function-keys) depending on modifier keys  (shift,  con‐
120           trol,  etc.).   While  terminfo and termcap have a set of 60 prede‐
121           fined function-key names, to which a series  of  keys  can  be  as‐
122           signed,  that is insufficient for more than a dozen keys multiplied
123           by more than a couple of modifier combinations.  The ncurses  data‐
124           base  uses  a convention based on xterm(1) to provide extended spe‐
125           cial-key names.
126
127           Fitting that into termcap's limitation of 2-character  names  would
128           be  pointless.   These  extended  keys are available only with ter‐
129           minfo.
130
131   Recognized capabilities
132       The ncurses library uses the user-definable  capabilities.   While  the
133       terminfo  database  may  have  other extensions, ncurses makes explicit
134       checks for these:
135
136          AX boolean, asserts that the terminal interprets SGR 39 and  SGR  49
137             by  resetting  the foreground and background color, respectively,
138             to the default.
139
140             This is a feature recognized by the screen program as well.
141
142          E3 string, tells how to  clear  the  terminal's  scrollback  buffer.
143             When present, the clear(1) program sends this before clearing the
144             terminal.
145
146             The command “tput clear” does the same thing.
147
148          RGB
149             boolean, number or string, to assert  that  the  set_a_foreground
150             and  set_a_background  capabilities  correspond to direct colors,
151             using an RGB (red/green/blue) convention.  This capability allows
152             the  color_content  function to return appropriate values without
153             requiring the application to initialize colors using init_color.
154
155             The capability type determines the values which ncurses sees:
156
157             boolean
158                implies that the number of bits for red, green  and  blue  are
159                the  same.   Using  the maximum number of colors, ncurses adds
160                two, divides that sum by three, and assigns the result to red,
161                green and blue in that order.
162
163                If the number of bits needed for the number of colors is not a
164                multiple of three, the blue (and  green)  components  lose  in
165                comparison to red.
166
167             number
168                tells  ncurses  what result to add to red, green and blue.  If
169                ncurses runs out of bits, blue (and green) lose just as in the
170                boolean case.
171
172             string
173                explicitly  list  the  number  of bits used for red, green and
174                blue components as a slash-separated list of decimal integers.
175
176             Because there are several  RGB  encodings  in  use,  applications
177             which make assumptions about the number of bits per color are un‐
178             likely to work reliably.  As a trivial  case,  for  example,  one
179             could  define  RGB#1 to represent the standard eight ANSI colors,
180             i.e., one bit per color.
181
182          U8 number, asserts that ncurses must use Unicode  values  for  line-
183             drawing characters, and that it should ignore the alternate char‐
184             acter set capabilities when the locale uses UTF-8 encoding.   For
185             more  information,  see  the discussion of NCURSES_NO_UTF8_ACS in
186             ncurses(3X).
187
188             Set this capability to a nonzero value to enable it.
189
190          XM string, override ncurses's built-in string which enables/disables
191             xterm(1) mouse mode.
192
193             ncurses  sends a character sequence to the terminal to initialize
194             mouse mode, and when the user clicks the  mouse  buttons  or  (in
195             certain  modes) moves the mouse, handles the characters sent back
196             by the terminal to tell it what was done with the mouse.
197
198             The mouse protocol is enabled when the mask passed in the  mouse‐
199             mask  function  is  nonzero.  By default, ncurses handles the re‐
200             sponses for the X11 xterm mouse protocol.  It  also  knows  about
201             the  SGR  1006  xterm mouse protocol, but must to be told to look
202             for this specifically.  It will not be able to guess  which  mode
203             is  used, because the responses are enough alike that only confu‐
204             sion would result.
205
206             The XM capability has a single parameter.  If nonzero, the  mouse
207             protocol  should  be enabled.  If zero, the mouse protocol should
208             be disabled.  ncurses inspects this capability if it is  present,
209             to  see whether the 1006 protocol is used.  If so, it expects the
210             responses to use the SGR 1006 xterm mouse protocol.
211
212             The xterm mouse protocol is used  by  other  terminal  emulators.
213             The  terminal database uses building-blocks for the various xterm
214             mouse protocols which can be used in customized terminal descrip‐
215             tions.
216
217             The terminal database building blocks for this mouse feature also
218             have an experimental capability  xm.   The  “xm”  capability  de‐
219             scribes  the  mouse  response.  Currently there is no interpreter
220             which would use this information to make the mouse  support  com‐
221             pletely data-driven.
222
223             xm shows the format of the mouse responses.  In this experimental
224             capability, the parameters are
225
226               p1   y-ordinate
227
228               p2   x-ordinate
229
230               p3   button
231
232               p4   state, e.g., pressed or released
233
234               p5   y-ordinate starting region
235
236               p6   x-ordinate starting region
237
238               p7   y-ordinate ending region
239
240               p8   x-ordinate ending region
241
242             Here are examples from the terminal database for  the  most  com‐
243             monly used xterm mouse protocols:
244
245               xterm+x11mouse|X11 xterm mouse protocol,
246                       kmous=\E[M, XM=\E[?1000%?%p1%{1}%=%th%el%;,
247                       xm=\E[M
248                          %?%p4%t%p3%e%{3}%;%' '%+%c
249                          %p2%'!'%+%c
250                          %p1%'!'%+%c,
251
252               xterm+sm+1006|xterm SGR-mouse,
253                       kmous=\E[<, XM=\E[?1006;1000%?%p1%{1}%=%th%el%;,
254                       xm=\E[<%i%p3%d;
255                          %p1%d;
256                          %p2%d;
257                          %?%p4%tM%em%;,
258
259   Extended key-definitions
260       Several terminals provide the ability to send distinct strings for com‐
261       binations of modified special keys.  There  is  no  standard  for  what
262       those keys can send.
263
264       Since  1999, xterm(1) has supported shift, control, alt, and meta modi‐
265       fiers which produce distinct special-key strings.  In  a  terminal  de‐
266       scription, ncurses has no special knowledge of the modifiers used.  Ap‐
267       plications can use the naming convention established for xterm to  find
268       these special keys in the terminal description.
269
270       Starting  with  the curses convention that key names begin with “k” and
271       that shifted special keys are  an  uppercase  name,  ncurses'  terminal
272       database defines these names to which a suffix is added:
273
274            Name   Description
275            ───────────────────────────────────────────────────────────────
276            kDC    special form of kdch1 (delete character)
277            kDN    special form of kcud1 (cursor down)
278            kEND   special form of kend (End)
279            kHOM   special form of khome (Home)
280            kLFT   special form of kcub1 (cursor-left or cursor-back)
281            kNXT   special form of knext (Next, or Page-Down)
282            kPRV   special form of kprev (Prev, or Page-Up)
283            kRIT   special form of kcuf1 (cursor-right, or cursor-forward)
284            kUP    special form of kcuu1 (cursor-up)
285
286       These are the suffixes used to denote the modifiers:
287
288            Value   Description
289            ──────────────────────────────────
290            2       Shift
291            3       Alt
292            4       Shift + Alt
293            5       Control
294            6       Shift + Control
295            7       Alt + Control
296            8       Shift + Alt + Control
297            9       Meta
298            10      Meta + Shift
299            11      Meta + Alt
300            12      Meta + Alt + Shift
301            13      Meta + Ctrl
302            14      Meta + Ctrl + Shift
303            15      Meta + Ctrl + Alt
304            16      Meta + Ctrl + Alt + Shift
305
306       None  of these are predefined; terminal descriptions can refer to names
307       which ncurses will allocate at runtime to key-codes.  To use these keys
308       in an ncurses program, an application could do this:
309
310       •   using a list of extended key names, ask tigetstr(3X) for their val‐
311           ues, and
312
313       •   given the list of values,  ask  key_defined(3X)  for  the  key-code
314           which would be returned for those keys by wgetch(3X).
315

PORTABILITY

317       The  “-x” extension feature of tic and infocmp has been adopted in Net‐
318       BSD curses.  That implementation stores user-defined capabilities,  but
319       makes no use of these capabilities itself.
320

SEE ALSO

322       infocmp(1M), tic(1M).
323
324       The  terminal database section NCURSES USER-DEFINABLE CAPABILITIES sum‐
325       marizes commonly-used user-defined capabilities which are used  in  the
326       terminal  descriptions.   Some  of  those  features  are  mentioned  in
327       screen(1) or tmux(1).
328
329       XTerm Control Sequences provides further information  on  the  xterm(1)
330       features which are used in these extended capabilities.
331

AUTHORS

333       Thomas E. Dickey
334       beginning with ncurses 5.0 (1999)
335
336
337
338                                                                  user_caps(5)
Impressum