curses_variables(3NCURSES)

💖 curses_variables — bestie's guide to the NCURSES types, constants & globals 💖

okay so this is curses_variables(3NCURSES), the one-stop glossary page for all the data types, constants, and global variables that the curses library hands you. consider this your group chat with the library. 💅

---

✨ 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 — literally all the curses data types, constants, and global variables, in one place. no cap. 🌸

---

🦋 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 🌈

so this page is the tl;dr of every data type, constant, and variable the curses library serves you. want the deep dive? go read ncurses(3NCURSES). it's giving ✨full lore✨.

depending on how ncurses got built (its build-time configuration, iykyk), these variables might actually be macros instead — see threads(3NCURSES) and opaque(3NCURSES) — and those macros only give you read-only access to the library's state. either way? bestie, treat them as read-only. seriously. write to them and you will confuse the library and nobody wants that. 😭

---

🎀 CONSTANTS 🎀

TRUE, FALSE

the curses library defines TRUE and FALSE to represent the values of the Boolean data type. iconic, classic, no notes. 👑

ERR, OK

curses and terminfo functions keep returning these constant integral values to tell you failure and success, respectively. if you see ERR, that's the universe saying "not me". if you see OK, slay. 💅

CCHARW_MAX

this integral value — an ncurses extension, bestie — tells you the maximum number of wchar_t wide characters that can fit in a curses complex character, aka a cchar_t. it's the capacity limit, the bag size, the closet space. 🧚

---

💜 DATA TYPES 💜

bool

curses defines an integral type called bool. plot twist: X/Open Issue 4 curses (1996) existed before ISO C99 and ISO C++98, and both of those standards also went and defined a Boolean data type with the same name. so yeah, name collision, it's a whole thing. 🙈

ncurses's configure script tries to discover which data type the system's C and C++ compilers use, so it can reuse them as its own bool. reusing is sustainable, we love that for the environment. 🌱

chtype

the chtype integral type combines a ("narrow", 8-bit) character with attributes that encode the character's rendition — like the styling of its typeface and/or its foreground and background colors. think of it as the character plus its whole outfit. 💅

want examples? peek at addch(3NCURSES), attron(3NCURSES), and inch(3NCURSES).

cchar_t, attr_t

okay so chtype is simply too small for the standard C library's wide-character type, wchar_t. it's giving tiny bag energy. so we have cchar_t, a type that can hold an attr_t and enough wide characters to store what Unicode calls a grapheme cluster — a "user-perceived character" [UAX #29] — which might still need several character encoding units to represent. yes bestie, one visible character can be multiple units. it's complicated. 😭

attr_t is the integral type that stores the "wide" attributes applying to cchar_ts.

see add_wch(3NCURSES), attr_on(3NCURSES), and in_wch(3NCURSES) for the vibes in action.

SCREEN

curses manages a terminal device using this structure type. see initscr(3NCURSES). it's the main character of the whole terminal, fr fr. 👑

WINDOW

curses represents rectangular portions of the terminal screen with the WINDOW structure type. see the subsection "Overview" of ncurses(3NCURSES) for the full picture. 🪟✨

---

🌸 VARIABLES 🌸

curscr, newscr, stdscr

when a curses application calls initscr(3NCURSES) or newterm(3NCURSES), the library creates a window named stdscr that's the same size as the terminal screen (minus any lines reserved by ripoffline(3NCURSES) or slk_init(3NCURSES)). it's also the implicit window — the one used by any function that interacts with a window but doesn't take a parameter identifying one. and like, many curses functions use it. it's the default friend in the group chat. 🫶

an application doesn't have to use stdscr though — maybe you'd rather tile the display into multiple windows instead. multitasking queen behavior. 🎀

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 figures out a minimal set of updates using the terminal's capabilities, to make curscr look like newscr. minimal effort, maximum result. that's the dream. ✨

COLORS

once a curses screen is initialized, COLORS contains the number of colors supported by the terminal. see color(3NCURSES). 🌈

COLOR_PAIRS

once a curses screen is initialized, COLOR_PAIRS contains the number of color pairs supported by the terminal. see color(3NCURSES). 💞

COLS, LINES

once a curses screen is initialized, COLS and LINES contain its width and height in character cells, respectively — that is, the number of columns and lines. yes, width first, height second. don't mix them up bestie, I'm begging. 😭

ESCDELAY

when reading key strokes from a window in keypad mode, curses has to tell apart the ESC character that comes from a user pressing the "Escape" key on the input device, from an ESC that begins an escape sequence (usually produced by function keys). how? by waiting after receiving the escape character, to see if more characters show up on the input stream within a short interval. ESCDELAY stores that interval, in milliseconds. ⏱️

if keypad(3NCURSES) is disabled for the curses window receiving input, then a program has to disambiguate escape sequences all by itself. you're on your own, girl. 💀

TABSIZE

the curses library converts a tab character into this number of spaces as it adds a tab to a window. see addch(3NCURSES). tab expansion, but make it a setting. 🍓

---

🫶 NOTES 🫶

initialize a curses screen with either initscr(3NCURSES) or newterm(3NCURSES). pick one, start the party. 🎉

if ncurses is configured to provide separate curses and tinfo libraries, most of these symbols live in the former. both of them use the bool data type. sharing is caring. 💖

---

⭐ EXTENSIONS ⭐

the CCHARW_MAX constant, and the ESCDELAY, TABSIZE, and newscr variables, are all extensions — and the first of those originated in ncurses. origin story, periodt. ✨

---

🌟 PORTABILITY 🌟

if you're using ncurses extensions, bestie, condition their use on whether the NCURSES_VERSION preprocessor macro is visible. that's the vibe check. ✅

the X/Open Curses standard documents all of the types and symbols above except CCHARW_MAX, newscr, TABSIZE, and ESCDELAY. so if you're porting, mind the gap. 😬

X/Open Curses describes curscr only as "an internal data structure". SVr4 spilled more tea, noting its use "for certain low-level operations like clearing and redrawing a screen containing garbage". neither one specified how it interacts with the rest of the interface beyond being used as an argument to clearok(3NCURSES) and wrefresh(3NCURSES). mysterious. iconic. a little unhinged. 🫠

newscr is a feature of SVr4 curses. when refreshing the screen, it's used as a working area for combining the standard window stdscr with any others the application may have created with newwin(3NCURSES). once the update of newscr is complete, curses modifies curscr to match newscr. copy-paste, but make it rendering. 🎨

TABSIZE is a feature of SVr4 curses.

• SVr4 initially sets TABSIZE from the terminal description's init_tabs (it) capability. after that, applications using SVr4 curses can alter it.
• SVr4 curses uses TABSIZE's value to compute the position of tab stops when updating both the virtual screen with addch(3NCURSES) and the physical screen with mvcur(3NCURSES).
• in ncurses, TABSIZE's value affects only the virtual screen. the library uses the terminal type description's init_tabs (it) capability to compute 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 (it) capability and the TABSIZE variable only to update the virtual screen.

ESCDELAY is a feature of AIX curses.

• AIX treats ESCDELAY's value as counting fifths of milliseconds.
• AIX's default ESCDELAY equals 0.1 seconds.
• AIX also enforces a limit of 10,000 seconds for ESCDELAY; ncurses does not enforce an upper limit.

ncurses has long interpreted ESCDELAY as a count of milliseconds, which makes it impossible to be completely compatible with AIX. and so, consequently, most users have decided to either override the value, or just rely on its default. we call that coping gracefully. 💅

---

🔥 SEE ALSO 🔥

[UAX #29] "Unicode Standard Annex #29: Unicode Text Segmentation"

getcchar(3NCURSES) discusses the ncurses extension CCHARW_MAX further. go get the extra lore.

ncurses(3NCURSES), color(3NCURSES), opaque(3NCURSES), terminfo(3NCURSES), threads(3NCURSES), terminfo_variables(3NCURSES), terminfo(5)

---

and that's the whole page bestie, you ate it. 💅✨ this was ncurses 6.6, dated 2025-08-23, and it lives under the name curses_variables(3NCURSES). go forth and treat your globals as read-only. 🎀🦋💖