mirror/ncurses
1
0
Fork 0
mirror of https://github.com/ThomasDickey/ncurses-snapshots.git synced 2026-01-26 11:04:35 +00:00
Code Issues Packages Projects Releases Wiki Activity
ncurses/doc/html/man/user_caps.5.html
Thomas E. Dickey f061503fbd
snapshot of project "ncurses", label v6_6_20260117
2026-01-18 01:37:19 +00:00

437 lines
24 KiB
HTML
Raw Blame History

<!--
* t
****************************************************************************
* Copyright 2018-2025,2026 Thomas E. Dickey *
* Copyright 2017 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.64 2026/01/11 23:54:16 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
<TITLE>user_caps 5 2026-01-11 ncurses 6.6 File formats</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
<H1 class="no-header">user_caps 5 2026-01-11 ncurses 6.6 File formats</H1>
<PRE>
<STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> File formats <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>
</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
user_caps - user-defined <EM>terminfo</EM> capability format
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
<STRONG>infocmp</STRONG> <STRONG>-x</STRONG>
<STRONG>tic</STRONG> <STRONG>-x</STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
</PRE><H3><a name="h3-Background">Background</a></H3><PRE>
Prior to <EM>ncurses</EM> 5.0 (1999), <EM>terminfo</EM> databases used a <EM>fixed</EM> <EM>repertoire</EM>
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 <EM>terminfo</EM>
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 <EM>curses</EM> vendor extended the standard
capability lists in distinct ways, a library could be programmed to
recognize only compiled <EM>terminfo</EM> entries that it was prepared to
interpret. Standardization was incomplete.
<STRONG>o</STRONG> X/Open Curses describes only the <EM>source</EM> format, not its <EM>binary</EM>
representation on disk.
Library developers rely upon SVr4 documentation and reverse
engineering of compiled <EM>terminfo</EM> files to match the binary format.
<STRONG>o</STRONG> 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.
<STRONG>o</STRONG> The tables of capability names differ between implementations.
Although they <EM>may</EM> 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 <EM>ncurses</EM>'s capability repertoire is closest to that of
Solaris, the set of capabilities supported by each vendor's <EM>term-</EM>
<EM>info</EM> database differs from the list published by X/Open Curses.
<EM>ncurses</EM> can be configured with tables that match the terminal
databases for AIX, HP-UX, or OSF/1, rather than the default
Solaris-like configuration.
<STRONG>o</STRONG> In SVr4 <EM>curses</EM> and <EM>ncurses</EM>, 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
<EM>ncurses</EM> for terminal capabilities includes details of extensions to
X/Open Curses made by various systems. For example, <EM>ncurses</EM>
supports the following nonstandard capabilities in each
configuration.
<STRONG>memory_lock</STRONG>
(<STRONG>meml</STRONG>) lock memory above cursor
<STRONG>memory_unlock</STRONG>
(<STRONG>memu</STRONG>) unlock memory
<STRONG>box_chars_1</STRONG>
(<STRONG>box1</STRONG>) box characters primary set
The memory lock/unlock capabilities were included because they were
used in the X11R6 terminal description for <STRONG>xterm(1)</STRONG>. <STRONG>tic</STRONG> uses the
<STRONG>box1</STRONG> capability to cope with terminal descriptions written for AIX.
During the 1990s, some application developers were reluctant to use
<EM>terminfo</EM> in spite of its performance (and other) advantages over
<EM>termcap</EM>.
<STRONG>o</STRONG> 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).
<STRONG>o</STRONG> The limitation to 16-bit signed integers was also mentioned.
Because <EM>termcap</EM> stores everything as a string, it could represent
larger numbers.
Although <EM>termcap</EM>'s extensibility was rarely used -- the claimant was
never an implementor who had actually exercised it -- the criticism had
a point. <EM>ncurses</EM> 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.
<EM>ncurses</EM> terms these <EM>user-defined</EM> <EM>capabilities</EM> because no modifications
to the standard capability list are needed.
The <EM>ncurses</EM> utilities <STRONG>tic</STRONG> and <STRONG>infocmp</STRONG> have a command-line option "-x"
to control whether the nonstandard capabilities are stored or
retrieved. <EM>ncurses</EM> provides <STRONG><A HREF="curs_extend.3x.html">use_extended_names(3x)</A></STRONG> to programs for the
same purpose.
When compiling a terminal database, if "-x" is used, <STRONG>tic</STRONG> stores a user-
defined capability if the capability name is not standard.
Because <EM>ncurses</EM> provides a <EM>termcap</EM> library interface, these user-
defined capabilities may be visible to <EM>termcap</EM> applications.
<STRONG>o</STRONG> The <EM>termcap</EM> interface (like all implementations of <EM>termcap</EM>)
restricts capability names to two characters.
When the capability is simple enough for use in a <EM>termcap</EM>
application, it is provided as a two-character name.
<STRONG>o</STRONG> Other user-defined capabilities employ features not usable in
<EM>termcap</EM>, such as parameterized strings that use more than two
parameters or require more powerful expressions than <EM>termcap</EM>
supports. Such capabilities should, in the <EM>terminfo</EM> database, have
names at least three characters in length.
<STRONG>o</STRONG> Some terminals can send distinct strings for special keys (cursor-,
keypad- or function-keys) depending on modifier keys (shift,
control, etc.). While <EM>terminfo</EM> and <EM>termcap</EM> 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 <EM>ncurses</EM> database uses a
convention based on <STRONG>xterm(1)</STRONG> to provide extended special-key names.
Fitting that into <EM>termcap</EM>'s limitation of 2-character names would
be pointless. These extended keys are available only with <EM>term-</EM>
<EM>info</EM>.
</PRE><H3><a name="h3-Recognized-Capabilities">Recognized Capabilities</a></H3><PRE>
The <EM>ncurses</EM> library employs user-definable capabilities. While the
<EM>terminfo</EM> database may have other extensions, <EM>ncurses</EM> makes explicit
checks for the following.
<STRONG>AX</STRONG> (Boolean) asserts that the terminal interprets SGR 39 and SGR 49
by resetting the foreground and background colors, respectively,
to the default.
<STRONG>screen(1)</STRONG> recognizes this capability as well.
<STRONG>E3</STRONG> (string) tells an application how to clear the terminal's
scrollback buffer. When present, the <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG> program sends this
before clearing the terminal.
The command "<STRONG>tput</STRONG> <STRONG>clear</STRONG>" does the same thing.
<STRONG>NQ</STRONG> (Boolean) suppresses a consistency check in <STRONG>tic</STRONG> for the <EM>ncurses</EM>
string capabilities <STRONG>user6</STRONG> (<STRONG>u6</STRONG>) through <STRONG>user9</STRONG> (<STRONG>u9</STRONG>), which tell an
application how to query the terminal's cursor position and its
device attributes.
<STRONG>RGB</STRONG>
(Boolean, numeric, or string) asserts that the <STRONG>set_a_foreground</STRONG>
(<STRONG>setaf</STRONG>) and <STRONG>set_a_background</STRONG> (<STRONG>setab</STRONG>) capabilities employ <EM>direct</EM>
<EM>colors</EM>, using an RGB (red/green/blue) convention. This
capability allows <STRONG><A HREF="curs_color.3x.html">color_content(3x)</A></STRONG> to return appropriate values
without requiring the application to initialize colors using
<STRONG><A HREF="curs_color.3x.html">init_color(3x)</A></STRONG>.
The capability type determines the values <EM>ncurses</EM> sees.
Boolean
implies that the number of bits for red, green, and blue are
the same. Starting with the value of the capability
<STRONG>max_colors</STRONG> (<STRONG>colors</STRONG>; <EM>termcap:</EM> <STRONG>co</STRONG>), <EM>ncurses</EM> 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 <EM>ncurses</EM> what result to add to red, green, and blue. If
<EM>ncurses</EM> 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
<STRONG>RGB#1</STRONG> to represent the standard eight ANSI X3.64/ECMA-48/ISO 6429
colors using one bit per color channel.
<STRONG>U8</STRONG> (numeric) asserts whether <EM>ncurses</EM> 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 <STRONG>NCURSES_NO_UTF8_ACS</STRONG> in section
"ENVIRONMENT" of <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.
Set this capability to a nonzero value to enable it.
<STRONG>XM</STRONG> (string) override <EM>ncurses</EM>'s built-in string that directs <STRONG>xterm(1)</STRONG>
to enable or disable mouse mode.
<EM>ncurses</EM> 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 <EM>mask</EM> argument to the
<STRONG><A HREF="curs_mouse.3x.html">mousemask(3x)</A></STRONG> function is nonzero. By default, <EM>ncurses</EM> handles
the responses for the X11 <EM>xterm</EM> mouse protocol. It also knows
about the SGR 1006 <EM>xterm</EM> mouse protocol, but must to be told to
look for it specifically. <EM>ncurses</EM> 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 <STRONG>XM</STRONG> capability has a single numeric parameter. If nonzero,
the mouse protocol should be enabled. If zero, the mouse
protocol should be disabled. <EM>ncurses</EM> 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 <EM>xterm</EM> mouse
protocol.
The <EM>xterm</EM> mouse protocol is used by other terminal emulators.
The terminal database uses building blocks for the various <EM>xterm</EM>
mouse protocols usable in customized terminal descriptions.
The terminal database building blocks for this mouse feature also
have an experimental capability, <STRONG>xm</STRONG>, that describes the mouse
response. No known interpreter uses this information, which
could make mouse support completely data-driven.
<STRONG>xm</STRONG> shows the format of the mouse responses. In this experimental
capability, the parameters are as follows.
<EM>p1</EM> y-ordinate
<EM>p2</EM> x-ordinate
<EM>p3</EM> button
<EM>p4</EM> state, e.g., pressed or released
<EM>p5</EM> y-ordinate starting region
<EM>p6</EM> x-ordinate starting region
<EM>p7</EM> y-ordinate ending region
<EM>p8</EM> x-ordinate ending region
Here are examples from the terminal database for the most
commonly used <EM>xterm</EM> 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[&lt;, XM=\E[?1006;1000%?%p1%{1}%=%th%el%;,
xm=\E[&lt;%i%p3%d;
%p1%d;
%p2%d;
%?%p4%tM%em%;,
Some of these extended capabilities have parameters which <EM>ncurses</EM>
may use in the <STRONG>tparm</STRONG>, <STRONG>tiparm</STRONG>, or <STRONG>tiparm_s</STRONG> functions. The <EM>ncurses</EM>
library checks to ensure that both standard and extended
capabilities have the expected number and type of parameters. The
terminfo compiler <EM>tic</EM> has similar checks for these extensions as
well as for those which are used by other programs, which include
<EM>mintty</EM>, <EM>screen</EM>, <EM>tack</EM>, <EM>tmux</EM>, <EM>vim</EM>, and <EM>xterm</EM>.
</PRE><H3><a name="h3-Extended-Key-Definitions">Extended Key Definitions</a></H3><PRE>
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, <STRONG>xterm(1)</STRONG> has supported <EM>shift</EM>, <EM>control</EM>, <EM>alt</EM>, and <EM>meta</EM>
modifiers which produce distinct special-key strings. In a terminal
description, <EM>ncurses</EM> has no special knowledge of the modifiers used.
Applications can use the <EM>naming</EM> <EM>convention</EM> established for <EM>xterm</EM> to
find these special keys in the terminal description.
Starting with the <EM>curses</EM> 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, <EM>ncurses</EM>'s
terminal database defines the following names and codes to which a
suffix is added.
<STRONG>Code</STRONG> <STRONG>Description</STRONG>
-------------------------------------------------------------------
<STRONG>kDC</STRONG> shifted kdch1 (delete character)
<STRONG>kDN</STRONG> shifted kcud1 (cursor down)
<STRONG>kEND</STRONG> shifted kend (end)
<STRONG>kHOM</STRONG> shifted khome (home)
<STRONG>kLFT</STRONG> shifted kcub1 (cursor back)
<STRONG>kNXT</STRONG> shifted knext (next)
<STRONG>kPRV</STRONG> shifted kprev (previous)
<STRONG>kRIT</STRONG> shifted kcuf1 (cursor forward)
<STRONG>kUP</STRONG> shifted kcuu1 (cursor up)
Keycap nomenclature on the Unix systems for which <EM>curses</EM> 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:
<STRONG>Value</STRONG> <STRONG>Description</STRONG>
----------------------------------
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
<EM>ncurses</EM> defines no capabilities for modified F-keys; terminal
descriptions can refer to <EM>names</EM> that <EM>ncurses</EM> allocates at runtime to
<EM>key</EM> <EM>codes</EM>. To use these keys in an <EM>ncurses</EM> program, an application
could do this:
<STRONG>o</STRONG> using a list of extended key <EM>names</EM>, ask <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG> for their
values, and
<STRONG>o</STRONG> given the list of values, ask <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG> for the <EM>key-code</EM>
which would be returned for those keys by <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
The "-x" extension feature of <STRONG>tic</STRONG> and <STRONG>infocmp</STRONG> has been adopted in
NetBSD <EM>curses</EM>. That implementation stores user-defined capabilities,
but makes no use of these capabilities itself.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
Thomas E. Dickey
beginning with <EM>ncurses</EM> 5.0 (1999)
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>
In the source form of the terminal database, <EM>terminfo.src</EM>, the section
"NCURSES USER-DEFINABLE CAPABILITIES". summarizes commonly-used user-
defined capabilities employed in the terminal descriptions. Some of
those features are mentioned in <STRONG>screen(1)</STRONG> or <STRONG>tmux(1)</STRONG>.
<EM>XTerm</EM> <EM>Control</EM> <EM>Sequences</EM> provides further information on the <STRONG>xterm(1)</STRONG>
features that are used in these extended capabilities.
ncurses 6.6 2026-01-11 <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#h3-Background">Background</a></li>
<li><a href="#h3-Recognized-Capabilities">Recognized Capabilities</a></li>
<li><a href="#h3-Extended-Key-Definitions">Extended Key Definitions</a></li>
</ul>
</li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
<li><a href="#h2-AUTHORS">AUTHORS</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
</ul>
</div>
</BODY>
</HTML>
Reference in New Issue View Git Blame Copy Permalink