# user_caps 5 2025-08-16 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-08-16                      user_caps(5)