curses_variables(3NCURSES) Library calls curses_variables(3NCURSES)
NAME
bool, chtype, cchar_t, attr_t, SCREEN, WINDOW, TRUE, FALSE, ERR, OK,
CCHARW_MAX, curscr, newscr, stdscr, COLORS, COLOR_PAIRS, COLS, LINES,
ESCDELAY, TABSIZE - curses data types, constants, and global variables
SYNOPSIS
#include <curses.h>
/* data types */
typedef /* ... */ bool;
typedef /* ... */ chtype;
typedef /* ... */ cchar_t;
typedef /* ... */ attr_t;
typedef /* ... */ SCREEN;
typedef /* ... */ WINDOW;
/* constants */
const bool TRUE;
const bool FALSE;
const /* ... */ ERR;
const /* ... */ OK;
/* extension */
const /* ... */ CCHARW_MAX;
/* variables */
int COLORS;
int COLOR_PAIRS;
int COLS;
int LINES;
WINDOW * curscr;
WINDOW * stdscr;
/* extensions */
int ESCDELAY;
int TABSIZE;
WINDOW * newscr;
DESCRIPTION
This page summarizes data types, constants, and variables provided by
the curses library. Locate further discussion in ncurses(3NCURSES).
Depending on ncurses's build-time configuration, the variables may in-
stead be macros (see threads(3NCURSES) and opaque(3NCURSES)) that pro-
vide read-only access to the library's state. In either case, applica-
tions should treat them as read-only to avoid confusing the library.
CONSTANTS
TRUE, FALSE
The curses library defines TRUE and FALSE to represent the values of the
Boolean data type.
ERR, OK
curses and terminfo routines frequently return these constant integral
values indicating failure and success, respectively.
CCHARW_MAX
This integral value, an ncurses extension, contains the maximum number
of wchar_t wide characters that can be stored in a curses complex char-
acter cchar_t.
PREDEFINED TYPES
bool
X/Open Issue 4 curses (1996) preceded the ISO C99 and ISO C++98 stan-
dards, each of which also defined a Boolean data type. The curses li-
brary requires an integral type bool.
ncurses' configure script attempts to discover the data type used by the
system's C and C++ compilers, to reuse for the curses bool.
chtype
The chtype integral type combines a (“narrow”, 8-bit) character with at-
tributes encoding the character's rendition, such as the styling of its
typeface and/or foreground and background colors. See, for example,
addch(3NCURSES), attron(3NCURSES), and inch(3NCURSES).
cchar_t, attr_t
chtype is too small for the standard C library's wide-character type,
wchar_t. cchar_t is a type that can accommodate an attr_t and enough
wide characters to store what Unicode terms a grapheme cluster (a “user-
perceived character” [UAX #29], which may nevertheless require several
character encoding units to represent). attr_t is an integral type
storing “wide” attributes that apply to cchar_ts. See, for example,
add_wch(3NCURSES), attr_on(3NCURSES), and in_wch(3NCURSES).
SCREEN
curses manages a terminal device with this structure type; see
initscr(3NCURSES).
WINDOW
curses represents rectangular portions of the terminal screen with the
WINDOW structure type; see subsection “Overview” of ncurses(3NCURSES).
VARIABLES
curscr, newscr, stdscr
When a curses application calls initscr(3NCURSES) or newterm(3NCURSES),
the library creates a window named stdscr that is the same size as the
terminal screen and is the implicit window used by functions that inter-
act with a window but do not take a parameter identifying one; many
curses functions use it. An application need not use stdscr; it might
prefer to tile the display into multiple windows instead.
The library records updates to the terminal screen in a window named
curscr. This object is referred to as the “physical screen” in
refresh(3NCURSES) and outopts(3NCURSES).
ncurses collects pending updates to the terminal screen in a window
named newscr. This object is referred to as the “virtual screen” in the
kernel(3NCURSES), refresh(3NCURSES), and outopts(3NCURSES). When the
screen is refreshed, curses determines a minimal set of updates using
the terminal's capabilities to make curscr look like newscr.
COLORS
Once curses is initialized, COLORS contains the number of colors sup-
ported by the terminal; see color(3NCURSES).
COLOR_PAIRS
Once curses is initialized, COLOR_PAIRS contains the number of color
pairs supported by the terminal; see color(3NCURSES).
COLS, LINES
Once curses is initialized, COLS and LINES contain the screen's width
and height in character cells, respectively; that is, the number of
columns and lines.
ESCDELAY
For curses to distinguish the ESC character resulting from a user's
press of the “Escape” key on the input device from one beginning an es-
cape sequence (as commonly produced by function keys), it waits after
the escape character to see if further characters are available on the
input stream within a short interval. ESCDELAY stores this interval in
milliseconds.
If keypad(3NCURSES) is disabled for the curses window receiving input, a
program must disambiguate escape sequences itself.
TABSIZE
The curses library converts a tab character to this number of spaces as
it adds a tab to a window; see addch(3NCURSES).
NOTES
Either initscr(3NCURSES) or newterm(3NCURSES) initializes curses.
If ncurses is configured to provide separate curses and tinfo libraries,
most of these symbols reside in the former. The bool data type is used
by both.
EXTENSIONS
The CCHARW_MAX constant, and ESCDELAY, TABSIZE, and newscr variables,
are extensions, the first of these originating in ncurses.
PORTABILITY
Applications employing ncurses extensions should condition their use on
the visibility of the NCURSES_VERSION preprocessor macro.
The X/Open Curses standard documents all of the foregoing types and sym-
bols except for CCHARW_MAX, newscr, TABSIZE, and ESCDELAY.
X/Open Curses describes curscr only as “an internal data structure”;
SVr4 gave more details, noting its use “for certain low-level operations
like clearing and redrawing a screen containing garbage”. Neither spec-
ified its interaction with the rest of the interface beyond use as an
argument to clearok(3NCURSES) and wrefresh(3NCURSES).
newscr is a feature of SVr4 curses. When refreshing the screen, it is
used as a working area for combining the standard window stdscr with any
others the application may have created with newwin(3NCURSES). When the
update of newscr is complete, curses modifies curscr to match newscr.
TABSIZE is a feature of SVr4 curses.
• SVr4 initially sets TABSIZE from the terminal description's
init_tabs capability. After that, it can be altered by applications
using SVr4 curses.
• SVr4 curses uses the value of TABSIZE to compute the position of tab
stops when updating both the virtual screen with addch(3NCURSES) and
the physical screen with mvcur(3NCURSES).
• ncurses uses the value of TABSIZE only to update the virtual screen.
It uses the terminal description's “it” (init_tabs) capability for
computing hardware tabs (that is, tab stops on the physical screen).
• Other implementations differ. For instance, NetBSD curses allows
TABSIZE to be set through an environment variable. ncurses does
not.
NetBSD curses does not support hardware tabs; it uses the init_tabs
capability and the TABSIZE variable only for updating the virtual
screen.
ESCDELAY is a feature of AIX curses.
• In AIX, the units for ESCDELAY are fifths of milliseconds.
• The default value for AIX's ESCDELAY equals 0.1 seconds.
• AIX also enforces a limit of 10,000 seconds for ESCDELAY; ncurses
does not enforce any upper limit.
ncurses has long used ESCDELAY with units of milliseconds, making it im-
possible to be completely compatible with AIX. Consequently, most users
have decided either to override the value, or to rely upon its default.
SEE ALSO
]8;;https://unicode.org/reports/tr29/\[UAX #29] “Unicode Standard Annex #29: Unicode Text Segmentation”]8;;\
getcchar(3NCURSES) further discusses CCHARW_MAX.
ncurses(3NCURSES), color(3NCURSES), opaque(3NCURSES),
terminfo(3NCURSES), threads(3NCURSES), terminfo_variables(3NCURSES),
terminfo(5)
ncurses 6.5 2025-01-18 curses_variables(3NCURSES)
Generated by dwww version 1.16 on Fri Oct 2 21:40:58 CEST 2026.