# user_caps 5 2025-11-11 ncurses 6.5 File formats

    user_caps(5)                     File formats                     user_caps(5)

## NAME

           user_caps - user-defined terminfo capability format

## SYNOPSIS

           infocmp -x

           tic -x

## DESCRIPTION

### Background

           Prior to ncurses 5.0 (1999), terminfo databases used a 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.

           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  terminfo
           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 curses vendor extended the standard
           capability lists in distinct ways, a library  could  be  programmed  to
           recognize  only  compiled  terminfo  entries  that  it  was prepared to
           interpret.  Standardization was incomplete.

           o   X/Open Curses describes only the  source  format,  not  its  binary
               representation on disk.

               Library   developers  rely  upon  SVr4  documentation  and  reverse
               engineering of compiled terminfo files to match the binary format.

           o   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.

               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.

           o   The tables of capability names differ between implementations.

               Although they 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 -- out  of  order  --
               for X/Open Curses conformance.

               While  ncurses's  capability  repertoire  is  closest  to  that  of
               Solaris, the set of capabilities supported by each  vendor's  term-
               info  database  differs  from  the list published by X/Open Curses.
               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.

           o   In SVr4 curses and ncurses, the terminal  database  is  defined  at
               compile  time by interpolating a text file that lists the different
               terminal capabilities.

               In principle, the text file can be extended, but doing so  requires
               recompiling  and  reinstalling  the library.  The text file used by
               ncurses for terminal capabilities includes details of extensions to
               X/Open Curses  made  by  various  systems.   For  example,  ncurses
               supports   the   following   nonstandard   capabilities   in   each
               configuration.

                   memory_lock
                        (meml) lock memory above cursor

                   memory_unlock
                        (memu) unlock memory

                   box_chars_1
                        (box1) box characters primary set

               The memory lock/unlock capabilities were included because they were
               used in the X11R6 terminal description for xterm(1).  tic uses  the
               box1 capability to cope with terminal descriptions written for AIX.

           During  the  1990s,  some  application developers were reluctant to use
           terminfo in spite  of  its  performance  (and  other)  advantages  over
           termcap.

           o   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).

           o   The  limitation  to  16-bit  signed  integers  was  also mentioned.
               Because termcap stores everything as a string, it  could  represent
               larger numbers.

           Although  termcap's  extensibility  was rarely used -- the claimant was
           never an implementor who had actually exercised it -- the criticism had
           a  point.   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.
           ncurses  terms these user-defined capabilities because no modifications
           to the standard capability list are needed.

           The ncurses utilities tic and infocmp have a command-line  option  "-x"
           to   control   whether  the  nonstandard  capabilities  are  stored  or
           retrieved.  ncurses provides use_extended_names(3x) to programs for the
           same purpose.

           When compiling a terminal database, if "-x" is used, tic stores a user-
           defined capability if the capability name is not standard.

           Because ncurses provides  a  termcap  library  interface,  these  user-
           defined capabilities may be visible to termcap applications.

           o   The   termcap  interface  (like  all  implementations  of  termcap)
               restricts capability names to two characters.

               When  the  capability  is  simple  enough  for  use  in  a  termcap
               application, it is provided as a two-character name.

           o   Other  user-defined  capabilities  employ  features  not  usable in
               termcap, such as parameterized  strings  that  use  more  than  two
               parameters  or  require  more  powerful  expressions  than  termcap
               supports.  Such capabilities should, in the terminfo database, have
               names at least three characters in length.

           o   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 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 ncurses database uses a
               convention based on xterm(1) to provide extended special-key names.

               Fitting that into termcap's limitation of 2-character  names  would
               be  pointless.   These  extended keys are available only with term-
               info.

### Recognized Capabilities

           The ncurses library employs  user-definable  capabilities.   While  the
           terminfo  database  may  have  other extensions, ncurses makes explicit
           checks for the following.

              AX (Boolean) asserts that the terminal interprets SGR 39 and SGR  49
                 by  resetting the foreground and background colors, respectively,
                 to the default.

                 screen(1) recognizes this capability as well.

              E3 (string)  tells  an  application  how  to  clear  the  terminal's
                 scrollback buffer.  When present, the clear(1) program sends this
                 before clearing the terminal.

                 The command "tput clear" does the same thing.

              NQ (Boolean)  suppresses  a consistency check in tic for the ncurses
                 string capabilities user6 (u6) through user9 (u9), which tell  an
                 application  how  to query the terminal's cursor position and its
                 device attributes.

              RGB
                 (Boolean, numeric, or string) asserts that  the  set_a_foreground
                 (setaf)  and  set_a_background (setab) capabilities employ direct
                 colors,  using  an   RGB   (red/green/blue)   convention.    This
                 capability  allows color_content(3x) to return appropriate values
                 without requiring the  application  to  initialize  colors  using
                 init_color(3x).

                 The capability type determines the values ncurses sees.

                 Boolean
                    implies  that  the number of bits for red, green, and blue are
                    the  same.   Starting  with  the  value  of   the   capability
                    max_colors  (colors;  termcap:  co), ncurses adds two, divides
                    the sum by three, and assigns the result to  red,  green,  and
                    blue, in that order.

                    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.

                 numeric
                    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
                    Boolean case.

                 string
                    specify the quantity of bits used for  red,  green,  and  blue
                    color channels as a slash-separated list of decimal integers.

                 Because there are several RGB encodings in use, applications that
                 make  assumptions  about the number of bits per color channel are
                 unlikely to work reliably.  As a trivial case, one  could  define
                 RGB#1 to represent the standard eight ANSI X3.64/ECMA-48/ISO 6429
                 colors using one bit per color channel.

              U8 (numeric)  asserts  whether  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.  See the discussion of NCURSES_NO_UTF8_ACS  in  section
                 "ENVIRONMENT" of ncurses(3x).

                 Set this capability to a nonzero value to enable it.

              XM (string) override ncurses's built-in string that directs xterm(1)
                 to enable or disable mouse mode.

                 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.

                 The  mouse  protocol  is  enabled  when  the mask argument to the
                 mousemask(3x) function is nonzero.  By default,  ncurses  handles
                 the  responses  for  the X11 xterm mouse protocol.  It also knows
                 about the SGR 1006 xterm mouse protocol, but must to be  told  to
                 look  for it specifically.  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.

                 The  XM  capability  has a single numeric parameter.  If nonzero,
                 the mouse  protocol  should  be  enabled.   If  zero,  the  mouse
                 protocol should be disabled.  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  SGR 1006  xterm  mouse
                 protocol.

                 The  xterm  mouse  protocol  is used by other terminal emulators.
                 The terminal database uses building blocks for the various  xterm
                 mouse protocols usable in customized terminal descriptions.

                 The terminal database building blocks for this mouse feature also
                 have  an  experimental  capability,  xm, that describes the mouse
                 response.  No known  interpreter  uses  this  information,  which
                 could make mouse support completely data-driven.

                 xm shows the format of the mouse responses.  In this experimental
                 capability, the parameters are as follows.

                   p1   y-ordinate

                   p2   x-ordinate

                   p3   button

                   p4   state, e.g., pressed or released

                   p5   y-ordinate starting region

                   p6   x-ordinate starting region

                   p7   y-ordinate ending region

                   p8   x-ordinate ending region

                 Here  are  examples  from  the  terminal  database  for  the most
                 commonly used xterm mouse protocols.

                   xterm+x11mouse|X11 xterm mouse protocol,
                           kmous=\E[M, XM=\E[?1000%?%p1%{1}%=%th%el%;,
                           xm=\E[M
                              %?%p4%t%p3%e%{3}%;%' '%+%c
                              %p2%'!'%+%c
                              %p1%'!'%+%c,

                   xterm+sm+1006|xterm SGR-mouse,
                           kmous=\E[<, XM=\E[?1006;1000%?%p1%{1}%=%th%el%;,
                           xm=\E[<%i%p3%d;
                              %p1%d;
                              %p2%d;
                              %?%p4%tM%em%;,

### 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.

           Since 1999, xterm(1)  has  supported  shift,  control,  alt,  and  meta
           modifiers  which  produce  distinct special-key strings.  In a terminal
           description, ncurses has no special knowledge of  the  modifiers  used.
           Applications  can  use  the  naming convention established for xterm to
           find these special keys in the terminal description.

           Starting with the curses convention that  capability  codes  describing
           the  input  generated by a terminal's key caps begin with "k", and that
           shifted special keys use uppercase letters in  their  names,  ncurses's
           terminal  database  defines  the  following  names and codes to which a
           suffix is added.

                Code   Description
                -------------------------------------------------------------------
                kDC    shifted kdch1 (delete character)
                kDN    shifted kcud1 (cursor down)
                kEND   shifted kend (end)
                kHOM   shifted khome (home)
                kLFT   shifted kcub1 (cursor back)
                kNXT   shifted knext (next)
                kPRV   shifted kprev (previous)
                kRIT   shifted kcuf1 (cursor forward)
                kUP    shifted kcuu1 (cursor up)

           Keycap nomenclature on the Unix systems for which curses was  developed
           differs  from  today's ubiquitous descendants of the IBM PC/AT keyboard
           layout.  In the foregoing, interpret "backward" as "left", "forward" as
           "right", "next" as "page down", and "prev(ious)" as "page up".

           These are the suffixes used to denote the modifiers:

                Value   Description
                ----------------------------------
                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

           ncurses  defines  no  capabilities  for   modified   F-keys;   terminal
           descriptions  can  refer  to names that ncurses allocates at runtime to
           key codes.  To use these keys in an  ncurses  program,  an  application
           could do this:

           o   using  a  list  of  extended  key names, ask tigetstr(3x) for their
               values, and

           o   given the list of values,  ask  key_defined(3x)  for  the  key-code
               which would be returned for those keys by wgetch(3x).

## PORTABILITY

           The  "-x"  extension  feature  of  tic  and infocmp has been adopted in
           NetBSD curses.  That implementation stores  user-defined  capabilities,
           but makes no use of these capabilities itself.

## AUTHORS

           Thomas E. Dickey
           beginning with ncurses 5.0 (1999)

## SEE ALSO

           infocmp(1m), tic(1m)

           In  the source form of the terminal database, terminfo.src, the section
           "NCURSES USER-DEFINABLE CAPABILITIES".  summarizes commonly-used  user-
           defined  capabilities  employed  in the terminal descriptions.  Some of
           those features are mentioned in screen(1) or tmux(1).

           XTerm Control Sequences provides further information  on  the  xterm(1)
           features that are used in these extended capabilities.

    ncurses 6.5                       2025-11-11                      user_caps(5)