curs_variables(3X)

🌸 NAME 🌸

okay so bestie, welcome to curs_variables(3X) — the little glossary page of the curses library, from the ncurses 6.6 manual. it's giving "cheat sheet for every type, constant and global variable you'll ever bump into": 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 of them. 🫶

---

✨ 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 is the ✨summary✨, the vibe check on all the data types, constants and variables the curses library hands you. wanna go deeper on any of them? the full discussion lives in curses(3X). no cap.

so here's the tea though: depending on how ncurses was configured at build time, these variables might actually be macros instead (peep curs_threads(3X) and curs_opaque(3X)) — macros that give you read-only access to the library's internal state. either way, bestie, treat them as read-only. do not write to them. writing to them confuses the library and that is not the main character energy we want. 😭

---

🎀 CONSTANTS 🎀

💅 TRUE, FALSE

the curses library defines TRUE and FALSE to represent the values of the Boolean data type. that's it. that's the whole job.

💀 ERR, OK

curses and terminfo functions return these constant integral values all the time to say "nope, failed" and "yay, succeeded" respectively. ERR = the L. OK = ate. 👑

⭐ CCHARW_MAX

this integral value — an ncurses extension, iykyk — tells you the maximum number of wchar_t wide characters that can fit inside one curses complex character, a cchar_t. it's the capacity limit, the "how many besties can we squeeze in here" number. 🦋

---

🌈 DATA TYPES 🌈

🍓 bool

curses defines an integral type called bool. wild history fact: X/Open Issue 4 curses (1996) came before the ISO C99 and ISO C++98 standards, and each of those standards also went and defined a Boolean data type with that exact same name. so yeah, everyone named their kid the same thing. 🙈

ncurses's configure script tries to discover the data type that your system's C and C++ compilers actually use, so it can reuse them as its own bool. teamwork, honestly.

🎨 chtype

chtype is an integral type that combines a ("narrow", 8-bit) character with attributes encoding the character's rendition — think the styling of its typeface and/or its foreground and background colors. it's the glow-up in a single integer. check out addch(3X), attron(3X), and inch(3X) for the receipts.

🧚 cchar_t, attr_t

chtype is too small to hold the standard C library's wide-character type, wchar_t — tragic, honestly. cchar_t is the type that can accommodate an attr_t and enough wide characters to store what Unicode calls a grapheme cluster (a "user-perceived character" [UAX #29], which may still need several character encoding units to represent — she contains multitudes 💜). attr_t is an integral type storing "wide" attributes that apply to cchar_ts. see add_wch(3X), attr_on(3X), and in_wch(3X).

👑 SCREEN

curses manages a terminal device with this structure type. see initscr(3X).

🪟 WINDOW

curses represents rectangular portions of the terminal screen with the WINDOW structure type. see the "Overview" subsection of ncurses(3X).

---

✨ VARIABLES ✨

🦋 curscr, newscr, stdscr

when a curses application calls initscr(3X) or newterm(3X), the library creates a window named stdscr that's the same size as the terminal screen (minus any lines reserved by ripoffline(3X) or slk_init(3X)). it's the implicit window — the one used by functions that interact with a window but don't take a parameter identifying which one, and bestie, so many curses functions use it. that said, an application doesn't have to use stdscr; it might prefer to tile the display into multiple windows instead. do you. 💅

the library records updates to the terminal screen in a window named curscr. this object is what's referred to as the "physical screen" in curs_refresh(3X) and curs_outopts(3X).

ncurses collects pending updates to the terminal screen in a window named newscr. this one is referred to as the "virtual screen" in curs_kernel(3X), curs_refresh(3X), and curs_outopts(3X). when the screen is refreshed, curses figures out a minimal set of updates — using the terminal's capabilities — to make curscr look like newscr. it's a makeover episode, lowkey. ✨

🌸 COLORS

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

🌈 COLOR_PAIRS

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

📐 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, in that order. width then height. don't flip them, i'm begging. 😭

⌛ ESCDELAY

when reading key strokes from a window in keypad mode, curses has to tell apart the ESC character from a user pressing the "Escape" key on the input device, versus an ESC that begins an escape sequence (commonly 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 this interval in milliseconds.

heads up bestie: if keypad(3X) is disabled for the curses window receiving input, then your program has to disambiguate escape sequences itself. no training wheels. 🫠

🎀 TABSIZE

the curses library converts a tab character into this number of spaces as it adds a tab to a window. see curs_addch(3X).

---

📝 NOTES 📝

initialize a curses screen with either initscr(3X) or newterm(3X).

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.

---

🌟 EXTENSIONS 🌟

the CCHARW_MAX constant, plus the ESCDELAY, TABSIZE, and newscr variables, are extensions — and the first of those originated in ncurses. 🎉

---

🚀 PORTABILITY 🚀

applications that use ncurses extensions should condition their use on the visibility of the NCURSES_VERSION preprocessor macro. don't just rawdog it, babes.

the X/Open Curses standard documents all of the foregoing types and symbols — 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 one specified its interaction with the rest of the interface beyond using it as an argument to clearok(3X) and wrefresh(3X).

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(3X). 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 (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(3X) and the physical screen with mvcur(3X).
• 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 lets TABSIZE be set through an environment variable. ncurses does not. (rude of them to have options, honestly.)
  • 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. consequently, most users have decided to either override the value, or just rely on its default. choose your fighter. 💀

---

👀 SEE ALSO 👀

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

getcchar(3X) further discusses the ncurses extension CCHARW_MAX.

curses(3X), curs_color(3X), curs_opaque(3X), curs_terminfo(3X), curs_threads(3X), term_variables(3X), terminfo(5)

---

and that's the whole page bestie, you ate it up 💅 this was ncurses 6.6, dated 2025-08-23. go forth and treat your globals as read-only, mwah 🫶✨💖