threads(3NCURSES)

📦

version 6.6+20260608 · 6 versions

6.6+20260608 · ubuntu resolute, ubuntu stonking (latest)
6.5.20250531 · opensuse-leap 16.0
6.3 · ubuntu jammy
6.4+20240113 · ubuntu noble
6.4 · debian bookworm
6.5+20250216 · debian trixie, ubuntu questing

threads(3NCURSES) 🧵✨

okay bestie, this is the manual page for threads(3NCURSES) — it's a long one so it comes in three parts, and this is part one. buckle up 💖

🌸 NAME 🌸

NCURSES_WINDOW_CB, NCURSES_SCREEN_CB, get_escdelay, set_escdelay, set_tabsize, use_screen, use_window — curses support for multi-threaded applications

✨ SYNOPSIS ✨

#include <curses.h>

/* data types */
typedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);
typedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);

int get_escdelay(void);
int set_escdelay(int ms);
int set_tabsize(int cols);

int use_screen(SCREEN *scr, NCURSES_SCREEN_CB func, void *data);
int use_window(WINDOW *win, NCURSES_WINDOW_CB func, void *data);

💅 DESCRIPTION 💅

okay so. the ncurses library can be configured to support multi-threaded applications in a rudimentary way. like, it's giving "we did the thing but we kept it lowkey" 😭. such a configuration produces a different set of libraries, named libncursest for example, since doing that alters ncurses's application binary interface (ABI). so yes bestie, that's a whole different ABI, not just a vibe change 🫶

instead of modifying the programming interface (API) so that ncurses functions would expect an extra argument specifying a thread, the library adds functions — usable in any configuration — that hide the mutexes (mutual exclusion locks) you need to prevent concurrent access to variables shared by multiple threads of execution. so the locks are just... hidden behind the curtain, doing their thing, iconic behavior honestly 👑

ncurses threading support requires the use of functions to access members of the WINDOW structure (see opaque(3NCURSES)). and it further makes functions of the common global variables COLORS, COLOR_PAIRS, COLS, ESCDELAY, LINES, TABSIZE, curscr, newscr, and ttytype — maintaining them as read-only values in the SCREEN structure.

but even this is not enough to make an application using curses thread-safe. not me thinking we were done 😭

we would expect a multi-threaded application to have threads updating separate windows (on the same device), and separate screens (on different devices). further, applications expect a few of the global variables to be writable. the functions described here address these special situations. slay, problem solved 💅

the ESCDELAY and TABSIZE global variables are modified by some applications. to modify them in any configuration, use the set_escdelay or set_tabsize functions. other global variables are not modifiable. periodt, they said what they said 🙈

get_escdelay retrieves ESCDELAY's value.

the use_window and use_screen functions provide coarse-grained mutexes for their respective WINDOW and SCREEN parameters; they call a user-supplied function, pass it a data parameter, and return the value from the user-supplied function to the application. like a lil relay race but make it locking 🏃♀️

🌈 Usage 🌈

all ncurses library functions assume that the locale is not altered during operation. no mid-run glow-ups allowed bestie. in addition, they use data that is maintained within a hierarchy of scopes. it's giving nesting dolls 🪆

global data used in the low-level terminfo or termcap interfaces
terminal data associated with a call to set_curterm(3NCURSES)

terminal data are initialized when screens are created.

screen data associated with a call to newterm(3NCURSES) or initscr(3NCURSES)
window data associated with a call to newwin(3NCURSES) or subwin(3NCURSES)

windows are associated with screens. pads are not necessarily associated with any particular screen. 🙃

most curses applications operate on one or more windows within a single screen.

reentrant data associated with “pure” functions that alter no shared variables ✨

the following table lists the scope of each symbol in the ncurses library when configured to support multi-threaded applications.

💖 okay that's part 1 bestie, the table is coming in the next part, don't go anywhere 🎀

okay bestie we're deep in it now 💖 this next bit is the big master list — every single symbol this page is about, plus exactly what scope it lives in. it's giving phonebook but make it iconic. symbol → scope, alphabetical, zero skips. screenshot it, bookmark it, tattoo it idk. 🫶

BC — global 🌍
COLORS — screen (read-only)
COLOR_PAIR — reentrant
COLOR_PAIRS — screen (read-only)
COLS — screen (read-only)
ESCDELAY — screen (read-only; see set_escdelay) ⏱️
LINES — screen (read-only)
PAIR_NUMBER — reentrant
PC — global
SP — global
TABSIZE — screen (read-only; see set_tabsize)
UP — global
acs_map — screen (read-only)
add_wch — window (stdscr)
add_wchnstr — window (stdscr)
add_wchstr — window (stdscr)
addch — window (stdscr) ✨
addchnstr — window (stdscr)
addchstr — window (stdscr)
addnstr — window (stdscr)
addnwstr — window (stdscr)
addstr — window (stdscr)
addwstr — window (stdscr)
assume_default_colors — screen
attr_get — window (stdscr)
attr_off — window (stdscr)
attr_on — window (stdscr)
attr_set — window (stdscr)
attroff — window (stdscr)
attron — window (stdscr) 💅
attrset — window (stdscr)
baudrate — screen
beep — screen 🐝
bkgd — window (stdscr) 🎨
bkgdset — window (stdscr)
bkgrnd — window (stdscr)
bkgrndset — window (stdscr)
boolcodes — global (read-only)
boolfnames — global (read-only)
boolnames — global (read-only)
border — window (stdscr)
border_set — window (stdscr)
box — window (stdscr) 📦
box_set — window (stdscr)
can_change_color — terminal 🎨
cbreak — screen ⚡
chgat — window (stdscr)
clear — window (stdscr) 🧹
clearok — window
clrtobot — window (stdscr)
clrtoeol — window (stdscr)
color_content — screen 🌈
color_set — window (stdscr)
copywin — window (locks source, target) 📋
cur_term — terminal 💻
curs_set — screen 🖱️
curscr — screen (read-only)
curses_version — global (read-only) 🏷️
def_prog_mode — terminal
def_shell_mode — terminal
define_key — screen
del_curterm — screen
delay_output — screen
delch — window (stdscr)
deleteln — window (stdscr)
delscreen — global (locks screen list, screen) 🗑️
delwin — global (locks window list) 🗑️
derwin — screen
doupdate — screen 🔄
dupwin — screen (locks window)
echo — screen 📣
echo_wchar — window (stdscr)
echochar — window (stdscr)
endwin — screen 👋
erase — window (stdscr) 🧽
erasechar — window (stdscr)
erasewchar — window (stdscr)
filter — global 🫧
flash — terminal ⚡
flushinp — screen 🚰
get_wch — screen (input operation)
get_wstr — screen (input operation)
getattrs — window
getbegx — window
getbegy — window
getbkgd — window
getbkgrnd — window
getcchar — reentrant
getch — screen (input operation) ⌨️
getcurx — window
getcury — window
getmaxx — window
getmaxy — window
getmouse — screen (input operation) 🖱️
getn_wstr — screen (input operation)
getnstr — screen (input operation)
getparx — window
getpary — window
getstr — screen (input operation)
getwin — screen (input operation)
halfdelay — screen ⏳
has_colors — terminal 🌈
has_ic — terminal
has_il — terminal
has_key — screen
hline — window (stdscr)
hline_set — window (stdscr)
idcok — window
idlok — window
immedok — window
in_wch — window (stdscr)
in_wchnstr — window (stdscr)
in_wchstr — window (stdscr)
inch — window (stdscr)
inchnstr — window (stdscr)
inchstr — window (stdscr)
init_color — screen
init_pair — screen
initscr — global (locks screen list) 🎬
innstr — window (stdscr)
innwstr — window (stdscr)
ins_nwstr — window (stdscr)
ins_wch — window (stdscr)
ins_wstr — window (stdscr)
insch — window (stdscr)
insdelln — window (stdscr)
insertln — window (stdscr)
insnstr — window (stdscr)
insstr — window (stdscr)
instr — window (stdscr)
intrflush — terminal
inwstr — window (stdscr)
is_cleared — window
is_idcok — window
is_idlok — window
is_immedok — window
is_keypad — window
is_leaveok — window
is_linetouched — window
is_nodelay — window
is_notimeout — window
is_scrollok — window
is_syncok — window
is_term_resized — terminal
is_wintouched — window
isendwin — screen
key_defined — screen
key_name — global (static data)
keybound — screen
keyname — global (static data)
keyok — screen
keypad — window ⌨️
killchar — terminal
killwchar — terminal
leaveok — window
longname — screen 📛
mcprint — terminal
meta — screen
mouse_trafo — window (stdscr)
mouseinterval — screen
mousemask — screen 🖱️
move — window (stdscr)
mvadd_wch — window (stdscr)
mvadd_wchnstr — window (stdscr)
mvadd_wchstr — window (stdscr)
mvaddch — window (stdscr)
mvaddchnstr — window (stdscr)
mvaddchstr — window (stdscr)
mvaddnstr — window (stdscr)
mvaddnwstr — window (stdscr)
mvaddstr — window (stdscr)
mvaddwstr — window (stdscr)
mvchgat — window (stdscr)
mvcur — screen 🚀
mvdelch — window (stdscr)
mvderwin — window (stdscr)
mvget_wch — screen (input operation)
mvget_wstr — screen (input operation)
mvgetch — screen (input operation)
mvgetn_wstr — screen (input operation)
mvgetnstr — screen (input operation)
mvgetstr — screen (input operation)
mvhline — window (stdscr)
mvhline_set — window (stdscr)
mvin_wch — window (stdscr)
mvin_wchnstr — window (stdscr)
mvin_wchstr — window (stdscr)
mvinch — window (stdscr)
mvinchnstr — window (stdscr)
mvinchstr — window (stdscr)
mvinnstr — window (stdscr)
mvinnwstr — window (stdscr)
mvins_nwstr — window (stdscr)
mvins_wch — window (stdscr)
mvins_wstr — window (stdscr)
mvinsch — window (stdscr)
mvinsnstr — window (stdscr)
mvinsstr — window (stdscr)
mvinstr — window (stdscr)
mvinwstr — window (stdscr)
mvprintw — window (stdscr)
mvscanw — screen
mvvline — window (stdscr)
mvvline_set — window (stdscr)
mvwadd_wch — window
mvwadd_wchnstr — window
mvwadd_wchstr — window
mvwaddch — window
mvwaddchnstr — window
mvwaddchstr — window
mvwaddnstr — window
mvwaddnwstr — window
mvwaddstr — window
mvwaddwstr — window
mvwchgat — window
mvwdelch — window
mvwget_wch — screen (input operation)
mvwget_wstr — screen (input operation)
mvwgetch — screen (input operation)
mvwgetn_wstr — screen (input operation)
mvwgetnstr — screen (input operation)
mvwgetstr — screen (input operation)
mvwhline — window
mvwhline_set — window
mvwin — window
mvwin_wch — window
mvwin_wchnstr — window
mvwin_wchstr — window
mvwinch — window
mvwinchnstr — window
mvwinchstr — window
mvwinnstr — window
mvwinnwstr — window
mvwins_nwstr — window
mvwins_wch — window
mvwins_wstr — window
mvwinsch — window
mvwinsnstr — window
mvwinsstr — window
mvwinstr — window
mvwinwstr — window
mvwprintw — window
mvwscanw — screen
mvwvline — window
mvwvline_set — window
napms — reentrant 😴
newpad — global (locks window list) 📝
newscr — screen (read-only) 🆕
newterm — global (locks screen list) 🎬
newwin — global (locks window list) 🪟
nl — screen ↩️
nocbreak — screen
nodelay — window ⚡
noecho — screen 🤫
nofilter — global
nonl — screen
noqiflush — terminal
noraw — screen
notimeout — window
numcodes — global (read-only)
numfnames — global (read-only)
numnames — global (read-only)
ospeed — global 🏃
overlay — window (locks source, target) 🎭
overwrite — window (locks source, target) ✍️
pair_content — screen
pecho_wchar — screen
pechochar — screen
pnoutrefresh — screen
prefresh — screen
printw — window 🖨️

and bestie… that's still not the whole page. keep scrolling, we're so not done 💅

…and the roster keeps going, bestie 💖 we're still in the middle of the function-by-function breakdown, so let's just roll straight into it. Every name on the left, every thread-safety category on the right, exactly as written — don't come for me about the alignment, that's the original's whole aesthetic ✨

       putp                   global
       putwin                 window
       qiflush                terminal
       raw                    screen
       redrawwin              window
       refresh                screen
       reset_prog_mode        screen
       reset_shell_mode       screen
       resetty                terminal
       resize_term            screen (locks window list)
       resizeterm             screen
       restartterm            screen
       ripoffline             global (static data)
       savetty                terminal
       scanw                  screen
       scr_dump               screen
       scr_init               screen
       scr_restore            screen
       scr_set                screen
       scrl                   window (stdscr)
       scroll                 window
       scrollok               window
       set_curterm            screen
       set_escdelay           screen
       set_tabsize            screen
       set_term               global (locks screen list, screen)
       setcchar               reentrant
       setscrreg              window (stdscr)
       setupterm              global
       slk_attr               screen
       slk_attr_off           screen
       slk_attr_on            screen
       slk_attr_set           screen
       slk_attroff            screen
       slk_attron             screen
       slk_attrset            screen
       slk_clear              screen
       slk_color              screen
       slk_init               screen
       slk_label              screen
       slk_noutrefresh        screen
       slk_refresh            screen
       slk_restore            screen
       slk_set                screen
       slk_touch              screen
       slk_wset               screen
       standend               window
       standout               window
       start_color            screen
       stdscr                 screen (read-only)
       strcodes               global (read-only)
       strfnames              global (read-only)
       strnames               global (read-only)
       subpad                 window
       subwin                 window
       syncok                 window
       term_attrs             screen
       termattrs              screen
       termname               terminal
       tgetent                global
       tgetflag               global
       tgetnum                global
       tgetstr                global
       tgoto                  global
       tigetflag              terminal
       tigetnum               terminal
       tigetstr               terminal
       timeout                window (stdscr)
       touchline              window
       touchwin               window
       tparm                  global (static data)
       tputs                  screen
       trace                  global (static data)
       ttytype                screen (read-only)
       typeahead              screen
       unctrl                 screen
       unget_wch              screen (input operation)
       ungetch                screen (input operation)
       ungetmouse             screen (input operation)
       untouchwin             window
       use_default_colors     screen
       use_env                global (static data)
       use_extended_names     global (static data)
       use_legacy_coding      screen
       use_screen             global (locks screen list, screen)
       use_window             global (locks window list, window)
       vid_attr               screen
       vid_puts               screen
       vidattr                screen
       vidputs                screen
       vline                  window (stdscr)
       vline_set              window (stdscr)
       vw_printw              window
       vw_scanw               screen
       vwprintw               window
       vwscanw                screen
       wadd_wch               window
       wadd_wchnstr           window
       wadd_wchstr            window
       waddch                 window
       waddchnstr             window
       waddchstr              window
       waddnstr               window
       waddnwstr              window
       waddstr                window
       waddwstr               window
       wattr_get              window
       wattr_off              window
       wattr_on               window
       wattr_set              window
       wattroff               window
       wattron                window
       wattrset               window
       wbkgd                  window
       wbkgdset               window
       wbkgrnd                window
       wbkgrndset             window
       wborder                window
       wborder_set            window
       wchgat                 window
       wclear                 window
       wclrtobot              window
       wclrtoeol              window
       wcolor_set             window
       wcursyncup             screen (affects window plus parents)
       wdelch                 window
       wdeleteln              window
       wecho_wchar            window
       wechochar              window
       wenclose               window
       werase                 window
       wget_wch               screen (input operation)
       wget_wstr              screen (input operation)
       wgetbkgrnd             window
       wgetch                 screen (input operation)
       wgetdelay              window
       wgetn_wstr             screen (input operation)
       wgetnstr               screen (input operation)
       wgetparent             window
       wgetscrreg             window
       wgetstr                screen (input operation)
       whline                 window
       whline_set             window
       win_wch                window
       win_wchnstr            window
       win_wchstr             window
       winch                  window
       winchnstr              window
       winchstr               window
       winnstr                window
       winnwstr               window
       wins_nwstr             window
       wins_wch               window
       wins_wstr              window
       winsch                 window
       winsdelln              window
       winsertln              window
       winsnstr               window
       winsstr                window
       winstr                 window
       winwstr                window
       wmouse_trafo           window
       wmove                  window
       wnoutrefresh           screen
       wprintw                window
       wredrawln              window
       wrefresh               screen
       wresize                window (locks window list)
       wscanw                 screen
       wscrl                  window
       wsetscrreg             window
       wstandend              window
       wstandout              window
       wsyncdown              screen (affects window plus parents)
       wsyncup                screen (affects window plus parents)
       wtimeout               window
       wtouchln               window
       wunctrl                global (static data)
       wvline                 window
       wvline_set             window

Like, genuinely the whole alphabet of curses, slay 👑 note the little side-notes in parentheses though — screen (read-only), window (locks window list), screen (affects window plus parents), global (static data), screen (input operation) — those are not decoration, they're the whole point of this page. That's the tea. 🫖

✨ RETURN VALUE ✨

okay so what do these even give you back 👀

get_escdelay — hands you back the value of ESCDELAY. That's it, that's the whole job 💅
set_escdelay and set_tabsize — return ERR when they fail and OK when they succeed, no cap 🌸
use_screen and use_window — they give you back the int that the user-supplied function they were called with returned. literally just passing the vibe along 💖

📝 NOTES 📝

tiny but important: ncurses gives you both a C function and a preprocessor macro for every single function documented on this page. two for one, we love to see it 🎀

🌍 PORTABILITY 🌍

bestie, listen up, this one matters 🚨

These routines are specific to ncurses. They were not supported on Version 7, BSD or System V implementations.
It is recommended that any code depending on ncurses extensions be conditioned using NCURSES_VERSION.

so if you're writing something that needs to compile on ancient BSD or System V… girl, guard it with NCURSES_VERSION or you're gonna have a bad time 😭 not me being dramatic, that's just the warning.

👀 SEE ALSO 👀

go read these next, fr fr 📚

ncurses(3NCURSES)
opaque(3NCURSES)
curses_variables(3NCURSES)

and that's a wrap on the whole page, bestie 🦋💖 you made it all the way through, which is genuinely main character energy ⭐ this was ncurses 6.6, dated 2025-02-15 — go forth and thread-safely, periodt 💅✨

📦 where this page comes from

ubuntu resolute: ncurses-doc 6.6+20251231-1 · MIT/X11
ubuntu stonking: ncurses-doc 6.6+20260608-2 · MIT/X11
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms