curs_threads(3X)

📦
version 6.6_p20260516 · 6 versions
, in alpine 3.24, arch rolling, fedora 44

✨ NAME ✨

okay so bestie, this is the curs_threads(3X) page from the Library calls section, and it's all about curses support for multi-threaded applications. The whole squad is NCURSES_WINDOW_CB, NCURSES_SCREEN_CB, get_escdelay, set_escdelay, set_tabsize, use_screen, and use_window. 💖

✨ 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 tea: the ncurses library can be configured to support multi-threaded applications in a rudimentary way. That configuration produces a different set of libraries — named libncursest, for example — since doing so alters ncurses's application binary interface (ABI). periodt.

Instead of modifying the programming interface (API) to make ncurses functions expect an additional argument specifying a thread, the library adds functions, usable in any configuration, that hide the mutexes (mutual exclusion locks) needed to prevent concurrent access to variables shared by multiple threads of execution. no cap, it's giving lock magic. 🔒

ncurses threading support requires the use of functions to access members of the WINDOW structure (see curs_opaque(3X)). 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. obsessed with this level of organization.

Even this is not enough to make an application using curses thread-safe. 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. main character energy for real.

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. 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. so handy, honestly.

🦋 Usage 🦋

All ncurses library functions assume that the locale is not altered during operation. In addition, they use data that is maintained within a hierarchy of scopes. vibe check: here's the hierarchy.

  • global data used in the low-level terminfo or termcap interfaces
  • terminal data associated with a call to set_curterm(3X) Terminal data are initialized when screens are created.
  • screen data associated with a call to newterm(3X) or initscr(3X)
  • window data associated with a call to newwin(3X) or subwin(3X) 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 bestie, deep breath, because this is THE LIST 💅 every single symbol in this entire API, plus the scope it lives in. it's giving seating chart for the most unhinged group project of all time: some of these are global, some are out here living on a screen, some are window girlies, some belong to the terminal, and a few are reentrant because they're just built different ✨

we are going through every last one. no skipping, no shortcuts, no "eh, you get the idea". you WILL know exactly where every symbol lives. periodt.

  • 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 — she goes beep 🔔
  • 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) — locks BOTH of them, no sneaking in 🔒
  • 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) — two locks at once, thorough queen 👑
  • delwin — global (locks window list)
  • derwin — screen
  • doupdate — screen
  • dupwin — screen (locks window)
  • echo — screen
  • echo_wchar — window (stdscr)
  • echochar — window (stdscr)
  • endwin — screen — and scene 🎬
  • erase — window (stdscr)
  • erasechar — window (stdscr)
  • erasewchar — window (stdscr)
  • filter — global
  • flash — terminal — she goes flash ⚡
  • 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) — the main character herself, obviously 👑
  • 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) — static data, so mind your business 🙈
  • 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 — nap time bestie, love that for her 😴
  • 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) — double lock again, she's not playing 🔒
  • overwrite — window (locks source, target)
  • pair_content — screen
  • pecho_wchar — screen
  • pechochar — screen
  • pnoutrefresh — screen
  • prefresh — screen
  • printw — window

…and the list keeps going, bestie, we're not even close to done yet 💅

  • 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

✨ RETURN VALUE ✨

Okay so here's what you actually get back, bestie 🎀

  • get_escdelay hands you the value of ESCDELAY. that's it, that's the whole vibe.
  • set_escdelay and set_tabsize give you ERR if it flops and OK if it ate and left no crumbs ✅
  • use_screen and use_window return the int that the user-supplied function you passed them gives back — so like, whatever your lil callback returns, that's what comes out. no middleman behavior, no cap 🫶

📝 NOTES 📝

Real talk for a sec: ncurses gives you both a C function and a preprocessor macro for every single function documented on this page. two for the price of one, we love a generous queen 👑

🌍 PORTABILITY 🌍

Heads up, bestie — these routines are specific to ncurses. They were not supported on Version 7, BSD or System V implementations.

So if your code is leaning on these ncurses extensions, the move is to condition it using NCURSES_VERSION. protect your peace (and your portability) fr fr 🧚

👀 SEE ALSO 👀

  • curses(3X)
  • curs_opaque(3X)
  • curs_variables(3X)

And that's a wrap on the whole page, babes 💖 this was ncurses 6.6, dated 2025-02-15, and the manual section is curs_threads(3X). go forth and thread safely, my icon 👑✨

📦 where this page comes from