curs_color(3x) Library calls curs_color(3x)
start_color, has_colors, can_change_color, init_pair, init_color,
init_extended_pair, init_extended_color, color_content, pair_content,
extended_color_content, extended_pair_content, reset_color_pairs,
COLOR_PAIR, PAIR_NUMBER, COLORS, COLOR_PAIRS, COLOR_BLACK, COLOR_RED,
COLOR_GREEN, COLOR_YELLOW, COLOR_BLUE, COLOR_MAGENTA, COLOR_CYAN,
COLOR_WHITE, A_COLOR - manipulate terminal colors with curses
#include <curses.h>
/* variables */
int COLOR_PAIRS;
int COLORS;
int start_color(void);
bool has_colors(void);
bool can_change_color(void);
int init_pair(short pair, short f, short b);
int init_color(short index, short r, short g, short b);
/* extensions */
int init_extended_pair(int pair, int f, int b);
int init_extended_color(int index, int r, int g, int b);
int color_content(short index, short *r, short *g, short *b);
int pair_content(short pair, short *f, short *b);
/* extensions */
int extended_color_content(int index, int *r, int *g, int *b);
int extended_pair_content(int pair, int *f, int *b);
/* extension */
void reset_color_pairs(void);
/* macros */
int COLOR_PAIR(int n);
PAIR_NUMBER(int attr);
COLOR_BLACK
COLOR_RED
COLOR_GREEN
COLOR_YELLOW
COLOR_BLUE
COLOR_MAGENTA
COLOR_CYAN
COLOR_WHITE
A_COLOR
curses supports color rendering on terminals with applicable
capabilities. Once the library has initialized the terminal,
has_colors tells an application whether that terminal type has color
capability. If it does, calling start_color enables the feature. (See
section "NOTES" below regarding ripoffline(3x).)
When applying colors to a curses window, the library manages them in
pairs. A color pair couples a foreground color applied to the visible
strokes of a glyph with a background color for the field in the
character cell within which the glyph appears. Configure at least one
color pair to use the color feature. init_pair initializes a color
pair identifier, whose value you select, from a pair of color indices,
foreground and background. Each index represents a color. X/Open
Curses standardizes, and a curses library defines, a small set of color
indices; see section "MACROS" below. The macro COLOR_PAIR(n) converts
a pair n thus initialized to the value required to encode it in a
chtype or attr_t. Another macro, PAIR_NUMBER(n) conversely extracts a
color pair identifier from variables of those data types. pair_content
permits discovery of a color pair's current definition. color_content
extracts the red, green, and blue components of the color using the
given index.
can_change_color tells an application whether the terminal type permits
(re)definition of a color. If it does, you can call init_color to
update the specified color index to use red, green, and blue components
of your choice.
Subsection "Color Handling" of terminfo(5) describes the capabilities
that terminal types use to manage color.
Passing a curses function a color index outside the range 0 to
COLORS-1, or a color pair identifier outside the range 0 to
COLOR_PAIRS-1 may result in a runtime error. COLORS corresponds to the
terminal type's max_colors (colors) capability, and COLOR_PAIRS to
max_pairs (pairs). ncurses permits specification of a color index of
-1 in certain extended functions to select a default color; see
use_default_colors(3x).
Color pair 0 is special; it denotes "no color", meaning the terminal's
(typically monochrome) power-up default fore- and background.
For each screen, ncurses maintains a color palette that maps color
indices into the RGB (red, green, blue) color space.
is initialized by start_color to the maximum number of colors the
terminal can support.
is initialized by start_color to the maximum number of color pairs the
terminal can support. Often, its value is the product COLORS x COLORS,
but this is not always true.
o A few terminals use the HLS color space, ignoring this rule; and
o while a terminal type may support many colors, a portable curses
application is limited to the number of distinct color indices and
color pair identifiers that a signed short value can represent.
has_colors returns TRUE if the terminal supports colors and FALSE if it
does not. initscr(3x) or newterm(3x) must be called first, but
start_color need not be. An application might call has_colors to
inform its decision whether to use color or a video attribute like
A_BOLD to render text.
If your application requires color, call start_color before any other
color manipulation function. As a rule, do so immediately after
initscr. If the terminal type supports color, start_color:
o initializes the two global variables, COLORS and COLOR_PAIRS,
described above;
o initializes (only) the color pair 0 to the terminal type's power-up
foreground and background colors (but see the ncurses extension
use_default_colors(3x));
o initializes the color palette; and
o selects color pair 0.
start_color sets up the color palette for the eight colors named by the
X/Open Curses standard (see section "CONSTANTS" above) applying weights
appropriate to the color space. curses does not attempt to initialize
the color palette to match a terminal type's power-up configuration.
See section "NOTES" below.
Calling start_color again after it has returned OK does nothing.
(Re-)define a color pair with init_pair, which takes three arguments:
the color pair identifier to be updated, a foreground color index, and
a background color index. A portable application restricts these
argument values to the valid ranges stated above. If the application
uses ncurses's default color extension (see below), the library adjusts
the upper limit to allow for extra pairs that use a default color in
the foreground and/or background.
If a color pair was previously defined, init_pair causes a refresh of
the entire screen, and all occurrences of that color pair change to use
its new definition. ncurses suppresses this refresh if the color
pair's new color indices are the same as the old.
ncurses extensions allow you to update color pair 0 via
assume_default_colors(3x), and to access the terminal's default colors
as color index -1 if you first call use_default_colors(3x).
Because init_pair uses signed shorts for its parameters, its color pair
identifiers and color indices are limited to 32767 even for terminal
types that are much more capable. This ncurses extension uses ints
instead, expanding their range.
An application can discover the color index assignments of a color pair
with pair_content. Its first argument is the color pair identifier of
interest, and the remaining two are each a pointer to short that the
function populates with the foreground and background color indices,
respectively.
Because pair_content uses signed shorts for its parameters, its color
pair identifiers and color indices are limited to 32767 even for
terminal types that are much more capable. This ncurses extension uses
ints instead, expanding their range.
This ncurses extension directs the library to discard all color pair
assignments configured by application calls of init_pair and
init_extended_pair. It furthermore marks the entire screen as
requiring refresh; an application can thus easily reconfigure its color
scheme by subsequently initializing as many color pairs as required.
can_change_color returns TRUE if the terminal supports colors and can
change their mappings, and FALSE if it does not.
Change a color's mapping (definition) by supplying this function four
arguments: the color index; and red, green, and blue color channel
values in the range 0-1000.
If the color index is in use in a color pair on the screen, all
occurrences of it change to use its new definition. No refresh(3x) is
necessary.
Because init_color uses signed shorts for its parameters, the maximum
value of its color index argument is limited to 32767 even for terminal
types that are much more capable. (The range of valid RGB channel
values remains 0-1000.) This ncurses extension uses ints instead,
expanding the range of permissible color indices.
If the color index is in use in a color pair on the screen, all
occurrences of it change to use its new definition. No refresh(3x) is
necessary.
An application can query a color index's location in RGB space by
calling color_content. The library stores the color channel values
corresponding to the specified color index in the red, green, and blue
pointer-to-short arguments.
Because color_content uses signed shorts for its parameters, the
maximum value of its color index argument is limited to 32767 even for
terminal types that are much more capable. This ncurses extension uses
ints instead, expanding the range of permissible color indices.
ISO 6429 and ECMA-48 define eight standard colors (known inaccurately
as "ANSI" colors), to which X/Open Curses assigns symbolic names as
object-like macros COLOR_BLACK, COLOR_RED, COLOR_GREEN, COLOR_YELLOW,
COLOR_BLUE, COLOR_MAGENTA, COLOR_CYAN, and COLOR_WHITE. curses assumes
that COLOR_BLACK is the default background color for all terminals.
ncurses offers an extension to override that assumption; see
assume_default_colors(3x). Some terminals support additional colors
that lack standard names.
A_COLOR is a bit mask that, when bitwise "and"-ed with a chtype,
extracts its color pair identifier. X/Open Curses mandates the
provision of two function-like macros. They have no application in the
wide-character API of curses.
COLOR_PAIR(n) replaces color pair identifier n with its encoded value
appropriate for use in a chtype. Such values have a limited,
implementation-dependent range. Non-wide API functions such as
attrset(3x) cannot handle larger color pair identifiers than this. A
portable application checks that n's value is less than COLOR_PAIRS
before employing this macro on it. If you need to transform a larger
color pair identifier, you must use the wide API and call, for example,
attr_set(3x), which passes the color pair identifier as a parameter
separate from the attributes.
PAIR_NUMBER(n) replaces its chtype or attr_t argument n with the color
pair identifier encoded within it.
COLOR_PAIR() and PAIR_NUMBER() are inverse operations.
can_change_color and has_colors return TRUE or FALSE. The other
functions return OK on success and ERR on failure.
In ncurses, color manipulation functions returning an int recognize
several error conditions.
o All return ERR if the screen has not been initialized; see
initscr(3x) or newterm(3x).
o All except start_color return ERR if start_color has not been
called, or itself returned ERR.
o start_color returns ERR if it cannot allocate memory for its color
pair table.
o init_color returns ERR if the terminal type does not support
assignable color values; that is, if the initialize_color (initc)
capability is absent from its description.
o init_color returns ERR if any of its r, g, b arguments is outside
the range 0-1000 inclusive.
o init_pair, init_color, init_extended_pair, init_extended_color,
color_content, pair_content, extended_color_content, and
extended_pair_content return ERR on attempts to use
o color identifiers outside the range 0-COLORS-1 inclusive, the
default colors extension notwithstanding, or
o color pair identifiers outside the range 0-COLOR_PAIRS-1
inclusive.
X/Open Curses says nothing about how the standard colors are to be
configured in a color space. ncurses initializes a screen's color
palette such that, in the RGB color space, each channel of the eight
standard colors has a value of either 680 or 0. If the terminal type
supports at least 16 colors, this configuration aids an application to
support a terminal type with only one typeface to simulate bold text
with "bright" colors. With appropriate configuration of the bright
color pairs by the application, increasing nonzero channel values to
1000, this scheme suffices to approximate the 16 colors of IBM CGA text
mode video and the power-up configuration of the DEC VT525. SVr4
curses instead assigns values of 1000 to the nonzero color channel
values of the eight standard colors.
Setting a background color via a color pair identifier affects only
character cells that a character write operation explicitly touches.
To change the background color used when parts of a window are blanked
by erasing or scrolling operations, see bkgd(3x) (wide-character API
users: bkgrnd(3x)).
Windows created by ripoffline(3x) do not inherit color pair
configuration applied to stdscr; they must be configured independently.
In ncurses, init_pair accepts negative foreground and background color
arguments to support its use_default_colors(3x) extension, but only
after the latter function has been called.
The assumption that COLOR_BLACK is the terminal's default background
color can be overridden using ncurses's assume_default_colors(3x)
extension.
In ncurses, each pointer passed to color_content and pair_content can
be null, in which case the library ignores it, permitting the
application to disregard unnecessary information.
In ncurses, each screen has a color activation flag, color palette,
color pair table, and associated COLORS and COLOR_PAIRS values;
start_color affects only the current screen. The SVr4 curses
interface, standardized by X/Open Curses, was not designed with
distinguishable screens clearly in mind; historical implementations may
use a single shared color palette for all screens the library manages.
Several caveats apply to emulation of the CGA/EGA/VGA video of IBM PC-
compatible machines of the 80486 era and earlier.
o COLOR_YELLOW was frequently converted, in the analog domain, to a
shade of brown if the intensity bit was not set. To get yellow on
such devices, one would combine COLOR_YELLOW with the A_BOLD
attribute.
o The A_BLINK attribute should in theory make the background bright.
This often fails to work, and even VGA controllers for which it
mostly works, such as those from Paradise and compatibles, do the
wrong thing when you try to set a bright "yellow" background -- you
get a blinking yellow foreground instead.
o Color RGB values are not configurable on these devices (in text
mode).
A programmer new to curses may wonder why the library works with pairs
of indexed colors instead of "direct" foreground and background RGB
triples. The answer lies in the limited bandwidth between terminals
and their time-sharing host machines. In the 1980s, a 9600bps serial
link was considered fast. That speed typically corresponded to a data
rate of 960 bytes per second. Using a single-byte character encoding,
refreshing an 80x24 terminal screen took two full seconds. In other
words, such a terminal refreshing its entire screen contents rendered
half a frame per second. Adding data to each character cell necessary
for the "direct" color model at 8 bits per color channel would add 6
bytes to every character cell, extending the full-screen refresh time
to 14 seconds. Even a pair of 8-bit color values would triple the
refresh time.
Moreover, the vast majority of curses applications do not demand a wide
gamut of colors. Even a colorful application like the game nethack(6)
renders most of its interface in monochrome by default. A text user
interface employing the form(3x) or menu(3x) libraries often uses fewer
than ten distinct colors at any one time. Thus, small integers suffice
both to index individual colors and to pair them. Typically, each
color pair is assigned to a type of user interface element, like a
button or scroll bar control. Further, in the original SVr3.2 curses
implementation of color and today still in ncurses's non-wide library,
chtype affords few bits for encoding of the color pair identifier.
Even in the common modern scenario where a terminal emulator runs on
the same host as the curses application, and available bandwidth is
limited only by the speed of the system bus, efficient encoding of
character cell data aids performance by minimizing the copies to and
from the kernel's memory space by use of the pseudoterminal (pty)
system interface. For example, in the Linux 7.2 kernel, the pty buffer
size is 4 KiB, ensuring a CPU mode switch every time it fills up.
Parsimonious data management also reduces memory cache pressure.
The functions marked as extensions originated in ncurses, and are not
found in SVr4 curses, 4.4BSD curses, or any other previous curses
implementation.
Applications employing ncurses extensions should condition their use on
the visibility of the NCURSES_VERSION preprocessor macro.
X/Open Curses Issue 4 describes these functions. It specifies no error
conditions for them.
ncurses satisfies X/Open Curses's minimum maximums for COLORS and
COLOR_PAIRS.
ncurses does not refresh the screen if init_pair is used to no effect
on an existing color pair.
X/Open Curses does not specify a limit for the number of color indices
and color pair identifiers a terminal can support. However, in its use
of short for the parameters, it carries over SVr4's implementation
detail for the compiled terminfo database, which uses signed 16-bit
numbers. ncurses provides extended versions of the functions using int
parameters, allowing applications to use larger index and pair
identifiers.
SVr4 curses returns ERR from pair_content if its pair argument was not
initialized using init_pairs, and from color_content if the terminal
does not support changing colors. ncurses does neither.
SVr3.2 (1988) introduced color support to curses with all of the
symbols in the synopsis above except those marked as extensions. It
reserved color pair 0 as the terminal's initial, "uncolored" state, and
limited the number of possible color pairs to 64, because the color
pair datum was encoded in six bits of a chtype.
SVr4 (1989) made only internal changes, such as moving the storage of
color state from the SCREEN structure (pointed to by SP) to the
TERMINAL structure (pointed to by cur_term).
Other curses implementations impose different limits on the number of
color indices and color pairs.
o PCCurses (1987-1990) provided for only 8 color indices (and
therefore permitted at most 8x8 = 64 color pairs).
o PDCurses (1992-present) initially inherited the 8-color limitation
from PCCurses, but increased it to 256 in version 2.5 (2001), and
widened its chtype from 16 to 32 bits.
o X/Open Curses (1992-present) specified a new integral type, attr_t,
storing rendering attributes (see attr_on(3x)) and a color pair
identifier, and a new structure type, cchar_t, to store a sequence
of wide character codes separately from the character cell's
attributes and color pair, allowing an increased range of color
pairs. The standard specifies attr_t as a short, limiting portable
values to 15 bits; negative values are invalid in System V.
o ncurses (1992-present), in its non-wide-character configuration,
uses 8 bits of chtype for the color pair identifier.
Version 5.3 (2002) introduced a wide-character interface, but
encoded the color pair identifier with attributes in the character
type.
Since version 6 (2015), ncurses uses a separate int for the color
pair identifier in a cchar_t, adding extension functions to manage
the wider type. When a color pair identifier fits in 8 bits,
ncurses permits manipulation of color pair identifiers with
functions taking chtype arguments, even when a curses window uses
wide-character cells.
o NetBSD curses used 6 bits for the color pair identifier from 2000
(when it first added color support) until 2004. At that point,
NetBSD widened the color pair identifier to use 9 bits. As of
2025, that size is unchanged. Like ncurses before version 6, the
NetBSD color pair identifier is stored in the attributes field of
cchar_t, limiting the number of color pairs.
ncurses 6.1 (2018) introduced init_extended_pair, init_extended_color,
extended_pair_content, extended_color_content, and reset_color_pairs.
curses(3x), curs_attr(3x), curs_initscr(3x), curs_variables(3x),
default_colors(3x)
ncurses 6.6 2026-09-19 curs_color(3x)