--- name: "curses" section: "3" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/curses" --- # curses(3) character-cell terminal interface with optimized output ## NAME **ncurses** - character-cell terminal interface with optimized output ## SYNOPSIS ``` #include ``` ## DESCRIPTION **The “new curses” library offers the programmer a** **terminal-independent means of reading keyboard and mouse input and** **writing to character-cell displays with output optimized to minimize** **screen updates.** *ncurses* **replaces the** *curses* **libraries from** **System V Release 4 Unix (“SVr4”)** **and** **4.4BSD Unix,** **the development of which ceased in the 1990s.** **This document describes** *ncurses* **version 6.6** **(patch 20251230).** *ncurses* **permits control of the terminal screen's contents;** **abstraction and subdivision thereof with** *windows* **and** *pads*; **acquisition of keyboard and mouse events;** **selection of color and rendering attributes** **(such as bold or underline);** **the definition and use of** *soft label* **keys;** **access to the** *terminfo* **terminal capability database;** **a** *termcap* **compatibility interface;** **and an abstraction of the system's API for manipulating the terminal** **(such as** *termios***(3)).** *ncurses* **implements the interface described by X/Open Curses Issue 7.** **In many behavioral details not standardized by X/Open,** *ncurses* **emulates the** *curses* **library of SVr4 and provides numerous useful extensions.** *ncurses* **man pages employ several sections to clarify matters of usage and** **interoperability with other** *curses* **implementations.** - • **“NOTES” describes issues and caveats of which any user of the** *ncurses* **API should be aware,** **such as limitations on the size of an underlying integral type or the** **availability of a preprocessor macro exclusive of a function definition** **(which prevents its address from being taken).** **This section also describes implementation details** **of significance to the programmer but which are not standardized.** - • **“EXTENSIONS” presents** *ncurses* **innovations beyond the X/Open Curses standard and/or the SVr4** *curses* **implementation.** **They are termed** *extensions* **to indicate that they cannot be implemented solely by using the library** **API,** **but require access to the library's internal state.** - • **“PORTABILITY” discusses matters** **(beyond the exercise of extensions)** **that should be considered when writing to a** *curses* **standard,** **or for multiple implementations.** - • **“HISTORY” examines points of detail in** *ncurses* **and other** *curses* **implementations over the decades of their development,** **particularly where precedent or inertia have frustrated better design** **(and,** **in a few cases,** **where such inertia has been overcome).** **A** *curses* **application must be linked with the library;** **use the** **-lncurses** **option to your compiler or linker.** **A debugging version of the library may be available;** **if so,** **link with it using** **-lncurses\_g**. **(Your system integrator may have installed these libraries such that you** **can use the options** **-lcurses** **and** **-lcurses\_g**, **respectively.)** **The** *ncurses\_g* **library logs events describing** *ncurses* **actions** **to a file called** *trace* **in the application's working directory at startup.** **See section “ALTERNATE CONFIGURATIONS” below.** ### Application Structure **A** *curses* **application uses information from the system locale;** *setlocale***(3) prepares it for** *curses* **library calls.** ``` setlocale(LC_ALL, ""); ``` **If the locale is not thus initialized,** **the library assumes that characters are printable as in ISO 8859-1,** **to work with certain legacy programs.** **You should initialize the locale;** **do not expect consistent behavior from the library when the locale has** **not been set up.** **initscr(3X) or newterm(3X)** **must be called to initialize** *curses* **before use of any functions** **that access or manipulate windows or screens.** **To get character-at-a-time input without echoing —** **most interactive,** **screen-oriented programs want this —** **use the following sequence.** ``` initscr(); cbreak(); noecho(); ``` **Most applications would perform further setup as follows.** ``` noqiflush(); keypad(stdscr, TRUE); ``` **A** *curses* **program then often enters an event-handling loop.** **Call endwin(3X) before exiting.** ### Overview **A** *curses* **library abstracts the terminal with a** *SCREEN* **data structure,** **and represents all or part of its display** **with** *WINDOW* **structures.** **Distinct properties apply to each;** **for example,** **the** *line discipline* **of a typical Unix terminal driver** **is in one of three modes:** **raw,** **cbreak,** **or canonical (“cooked”).** **In** *curses*, **the line discipline is a property of the screen,** **applying identically to all windows associated with it.** **A** *window* **is a rectangular grid of character cells,** **addressed by line and column coordinates** (*y*, *x*), **with the upper left corner as (0, 0).** **A window called** **stdscr**, **by default the same size as the terminal screen,** **is always available.** **Create others with newwin(3X).** **A** *curses* **library does not manage overlapping windows** **(but see below).** **You can either use** **stdscr** **to manage one screen-filling window,** **or tile the screen into non-overlapping windows and not use** **stdscr** **at all.** **Mixing the two approaches will result in unpredictable and undesired** **effects.** **Functions permit manipulation of a window and the** *cursor* **identifying the cell within it at which the next operation will occur.** **Among those,** **the most basic are move(3X) and addch(3X):** **these place the cursor within and write a character to** **stdscr**, **respectively.** **Frequent changes to the terminal screen can cause unpleasant flicker or** **inefficient use of the communication channel to the device,** **so as a rule the library does not update it automatically.** **Therefore,** **after using** *curses* **functions to accumulate a set of desired updates that make sense to** **present together,** **call refresh(3X) to tell the library to make the user's screen** **look like stdscr.** **The library** *optimizes* **its output by computing a minimal volume of operations to mutate the** **screen from its state at the previous refresh to the new one.** **Effective optimization demands accurate information about the terminal** **device:** **the management of such information is the province of the** **terminfo(3X) API,** **a feature of every standard** *curses* **implementation.** **Special windows called** *pads* **may also be manipulated.** **These are not constrained to the size of the terminal screen and their** **contents need not be completely displayed.** **See curs\_pad(3X).** **Many terminals support configuration of character cell foreground and** **background colors as well as** *attributes*, **which cause characters to render in such modes as** **boldfaced,** **underlined,** **or in reverse video.** **See curs\_color(3X) and curs\_attr(3X).** *curses* **defines constants to simplify access** **to a small set of forms-drawing graphics** **corresponding to the DEC Alternate Character Set (ACS),** **a feature of VT100 and other terminals.** **See addch(3X).** *curses* **is implemented using the operating system's terminal driver;** **key events are received not as scan codes but as byte sequences.** **The driver reports graphical keycaps** **(alphanumeric and punctuation keys,** **and the space)** **as-is.** **Everything else,** **including the tab,** **enter/return,** **keypad,** **arrow,** **and function keys,** **appears to** *curses* **as a control character or a multibyte** *escape sequence.* *curses* **can translate the latter into unique** *key codes.* **See keypad(3X) and getch(3X).** *ncurses* **provides reimplementations of the SVr4 panel(3X), form(3X),** **and menu(3X) libraries;** **they permit overlapping windows and ease construction of user interfaces** **with** *curses*. ### Initialization **The selection of an appropriate value of** *TERM* **in the process environment is essential to correct** *curses* **and** *terminfo* **library operation.** **A well-configured system selects a correct** *TERM* **value automatically;** **[tset(1)](/tset/1.md) may assist with troubleshooting exotic situations.** **If you change the terminal type from a shell,** **export** *TERM*, **then run [tset(1)](/tset/1.md) or the** “**tput init**” **command.** **See subsection “Tabs and Initialization” of [terminfo(5)](/terminfo/5.md).** **If the environment variables** *LINES* **and** *COLUMNS* **are set,** **or if the** *curses* **program is executing in a graphical windowing environment,** **the information obtained thence overrides that obtained by** *terminfo*. **An** *ncurses* **extension supports resizable terminal displays;** **see wresize(3X).** **If the environment variable** *TERMINFO* **is defined,** **a** *curses* **program checks first for a terminal type description in the location it** **identifies.** *TERMINFO* **is useful for developing type descriptions or when write permission to** */usr/share/misc/terminfo* **is not available.** **See section “ENVIRONMENT” below.** ### Naming Conventions *curses* **offers many functions in variant forms using a regular set of** **alternatives to the name of an elemental one.** **Those prefixed with “w” require a** *WINDOW* **pointer argument;** **those with a “mv” prefix first perform cursor movement using** **wmove(3X);** **a “mvw” prefix indicates both.** **The “w” function is typically the elemental one;** **the removal of this prefix usually indicates operation on** **stdscr**. **Four functions prefixed with “p” require a** *pad* **argument;** **see below.** **In function synopses,** *ncurses* **man pages apply the following names to parameters.** **We introduce the character types in the next subsection.** | | | | --- | --- | | *bf* | a *bool* (**TRUE** or **FALSE**) | | *c* | a *char* or *int* | | *ch* | a *chtype* | | *wc* | a *wchar\_t* or *wint\_t* | | *wch* | a *cchar\_t* | | *win* | pointer to a *WINDOW* | | *pad* | pointer to a *WINDOW* that is a pad | | *pair* | a foreground/background color pair identifier | ### Wide and Non-wide Character Configurations **This man page primarily surveys functions that appear in any** **configuration of the library.** **There are two common configurations;** **for others,** **see section “ALTERNATE CONFIGURATIONS” below.** - *ncurses* **is the library in its “non-wide” configuration,** **handling only eight-bit characters.** **It stores a character combined with attributes** **and a color pair identifier** **in a** *chtype* **datum,** **which is often an alias of** *int*. **A string of** *curses* **characters is similar to a C** *char* **string;** **a** *chtype* **string ends with an integral** **0**, **the null** *curses* **character.** - **Attributes and a color pair identifier** **(with no corresponding character)** **can be stored in variables of** *chtype* **or** *attr\_t* **type.** **In either case,** **they are accessed via an integral bit mask.** - *ncurses* **stores each cell of a** *WINDOW* **as a** *chtype*. **X/Open Curses does not specify the sizes of the character code or** **color pair identifier,** **nor the quantity of attribute bits,** **in** *chtype*; **these are implementation-dependent.** *ncurses* **uses eight bits for the character code.** **An application requiring a wider character type,** **for instance to represent Unicode,** **should use the wide-character API.** - *ncursesw* **is the library in its “wide” configuration,** **which handles character encodings requiring a larger data type than** *char* **(a byte-sized type)** **can represent.** **It provides additional functions that complement those in** **the non-wide library where the size of the underlying character type is** **significant.** **A somewhat regular naming convention relates many of the wide variants** **to their non-wide counterparts;** **where a non-wide function name contains “ch” or “str”,** **prefix it with “\_w” to obtain the wide counterpart.** **For example,** **waddch becomes wadd\_wch.** **An exception is** **ins\_nwstr** **(and its variants),** **spelled thus instead of “insn\_wstr”.** **(Exceptions that add only “w” comprise** **addwstr**, **inwstr**, **and their variants.)** - **This convention is inapplicable to some non-wide function names,** **so other transformations are used for the wide configuration:** **the window background management function “bkgd” becomes** **“bkgrnd”;** **the window border-drawing and -clearing functions are suffixed with** **“\_set”;** **and character attribute manipulation functions like** **“attron” become “attr\_on”.** - *cchar\_t* **is a** *curses complex character* **and corresponds to the non-wide-character configuration's** *chtype*. **It is a structure type** **because it requires more storage than a standard scalar type offers.** **A character code may not be representable as a** *char*, **and moreover more than one character may occupy a cell** **(as with accent marks and other diacritics).** **Each character is of type** *wchar\_t*; **a complex character contains one spacing character and zero or more** **non-spacing characters** **(see below).** **A string of complex characters ends with a** *cchar\_t* **whose** *wchar\_t* **member is the null wide character.** **Attributes and a color pair identifier are stored in separate fields of** **the structure,** **not combined into an integer as in** *chtype*. *ncurses* **stores each cell of a** *WINDOW* **as a** *cchar\_t*. **setcchar(3X) and getcchar(3X)** **store and retrieve** *cchar\_t* **data.** **The wide library API of** *ncurses* **depends on two data types standardized by ISO C95.** - *wchar\_t* **stores a wide character.** **Like** *chtype*, **it may be an alias of** *int*. **Depending on the character encoding,** **a wide character may be** *spacing*, **meaning that it occupies a character cell by itself and typically** **accompanies cursor advancement,** **or** *non-spacing*, **meaning that it occupies the same cell as a spacing character,** **is often regarded as a “modifier” of the base glyph with which** **it combines,** **and typically does not advance the cursor.** - *wint\_t* **can store a** *wchar\_t* **or the constant** *WEOF*, **analogously to the** *int*-sized **character manipulation functions of ISO C and its constant** *EOF*. ### Function Name Index **The following table lists the** *curses* **functions provided in the non-wide and wide APIs and the corresponding** **man pages that describe them.** **Those flagged with “\*”** **are** *ncurses*-specific, **neither described by X/Open Curses nor present in SVr4.** | | | | --- | --- | | *curses* Function Name | Man Page | | COLOR\_PAIR | **curs\_color**(3X) | | PAIR\_NUMBER | **curs\_color**(3X) | | add\_wch | **curs\_add\_wch**(3X) | | add\_wchnstr | **curs\_add\_wchstr**(3X) | | add\_wchstr | **curs\_add\_wchstr**(3X) | | addch | **curs\_addch**(3X) | | addchnstr | **curs\_addchstr**(3X) | | addchstr | **curs\_addchstr**(3X) | | addnstr | **curs\_addstr**(3X) | | addnwstr | **curs\_addwstr**(3X) | | addstr | **curs\_addstr**(3X) | | addwstr | **curs\_addwstr**(3X) | | alloc\_pair | **new\_pair**(3X)\* | | assume\_default\_colors | **default\_colors**(3X)\* | | attr\_get | **curs\_attr**(3X) | | attr\_off | **curs\_attr**(3X) | | attr\_on | **curs\_attr**(3X) | | attr\_set | **curs\_attr**(3X) | | attroff | **curs\_attr**(3X) | | attron | **curs\_attr**(3X) | | attrset | **curs\_attr**(3X) | | baudrate | **curs\_termattrs**(3X) | | beep | **curs\_beep**(3X) | | bkgd | **curs\_bkgd**(3X) | | bkgdset | **curs\_bkgd**(3X) | | bkgrnd | **curs\_bkgrnd**(3X) | | bkgrndset | **curs\_bkgrnd**(3X) | | border | **curs\_border**(3X) | | border\_set | **curs\_border\_set**(3X) | | box | **curs\_border**(3X) | | box\_set | **curs\_border\_set**(3X) | | can\_change\_color | **curs\_color**(3X) | | cbreak | **curs\_inopts**(3X) | | chgat | **curs\_attr**(3X) | | clear | **curs\_clear**(3X) | | clearok | **curs\_outopts**(3X) | | clrtobot | **curs\_clear**(3X) | | clrtoeol | **curs\_clear**(3X) | | color\_content | **curs\_color**(3X) | | color\_set | **curs\_attr**(3X) | | copywin | **curs\_overlay**(3X) | | curs\_set | **curs\_kernel**(3X) | | curses\_trace | **curs\_trace**(3X)\* | | curses\_version | **curs\_extend**(3X)\* | | def\_prog\_mode | **curs\_kernel**(3X) | | def\_shell\_mode | **curs\_kernel**(3X) | | define\_key | **define\_key**(3X)\* | | del\_curterm | **curs\_terminfo**(3X) | | delay\_output | **curs\_util**(3X) | | delch | **curs\_delch**(3X) | | deleteln | **curs\_deleteln**(3X) | | delscreen | **curs\_initscr**(3X) | | delwin | **curs\_window**(3X) | | derwin | **curs\_window**(3X) | | doupdate | **curs\_refresh**(3X) | | dupwin | **curs\_window**(3X) | | echo | **curs\_inopts**(3X) | | echo\_wchar | **curs\_add\_wch**(3X) | | echochar | **curs\_addch**(3X) | | endwin | **curs\_initscr**(3X) | | erase | **curs\_clear**(3X) | | erasechar | **curs\_termattrs**(3X) | | erasewchar | **curs\_termattrs**(3X) | | exit\_curses | **curs\_memleaks**(3X)\* | | exit\_terminfo | **curs\_memleaks**(3X)\* | | extended\_color\_content | **curs\_color**(3X)\* | | extended\_pair\_content | **curs\_color**(3X)\* | | extended\_slk\_color | **curs\_slk**(3X)\* | | filter | **curs\_util**(3X) | | find\_pair | **new\_pair**(3X)\* | | flash | **curs\_beep**(3X) | | flushinp | **curs\_util**(3X) | | free\_pair | **new\_pair**(3X)\* | | get\_escdelay | **curs\_threads**(3X)\* | | get\_wch | **curs\_get\_wch**(3X) | | get\_wstr | **curs\_get\_wstr**(3X) | | getattrs | **curs\_attr**(3X) | | getbegx | **curs\_legacy**(3X)\* | | getbegy | **curs\_legacy**(3X)\* | | getbegyx | **curs\_getyx**(3X) | | getbkgd | **curs\_bkgd**(3X) | | getbkgrnd | **curs\_bkgrnd**(3X) | | getcchar | **curs\_getcchar**(3X) | | getch | **curs\_getch**(3X) | | getcurx | **curs\_legacy**(3X)\* | | getcury | **curs\_legacy**(3X)\* | | getmaxx | **curs\_legacy**(3X)\* | | getmaxy | **curs\_legacy**(3X)\* | | getmaxyx | **curs\_getyx**(3X) | | getmouse | **curs\_mouse**(3X)\* | | getn\_wstr | **curs\_get\_wstr**(3X) | | getnstr | **curs\_getstr**(3X) | | getparx | **curs\_legacy**(3X)\* | | getpary | **curs\_legacy**(3X)\* | | getparyx | **curs\_getyx**(3X) | | getstr | **curs\_getstr**(3X) | | getsyx | **curs\_kernel**(3X) | | getwin | **curs\_util**(3X) | | getyx | **curs\_getyx**(3X) | | halfdelay | **curs\_inopts**(3X) | | has\_colors | **curs\_color**(3X) | | has\_ic | **curs\_termattrs**(3X) | | has\_il | **curs\_termattrs**(3X) | | has\_key | **curs\_getch**(3X)\* | | has\_mouse | **curs\_mouse**(3X)\* | | hline | **curs\_border**(3X) | | hline\_set | **curs\_border\_set**(3X) | | idcok | **curs\_outopts**(3X) | | idlok | **curs\_outopts**(3X) | | immedok | **curs\_outopts**(3X) | | in\_wch | **curs\_in\_wch**(3X) | | in\_wchnstr | **curs\_in\_wchstr**(3X) | | in\_wchstr | **curs\_in\_wchstr**(3X) | | inch | **curs\_inch**(3X) | | inchnstr | **curs\_inchstr**(3X) | | inchstr | **curs\_inchstr**(3X) | | init\_color | **curs\_color**(3X) | | init\_extended\_color | **curs\_color**(3X)\* | | init\_extended\_pair | **curs\_color**(3X)\* | | init\_pair | **curs\_color**(3X) | | initscr | **curs\_initscr**(3X) | | innstr | **curs\_instr**(3X) | | innwstr | **curs\_inwstr**(3X) | | ins\_nwstr | **curs\_ins\_wstr**(3X) | | ins\_wch | **curs\_ins\_wch**(3X) | | ins\_wstr | **curs\_ins\_wstr**(3X) | | insch | **curs\_insch**(3X) | | insdelln | **curs\_deleteln**(3X) | | insertln | **curs\_deleteln**(3X) | | insnstr | **curs\_insstr**(3X) | | insstr | **curs\_insstr**(3X) | | instr | **curs\_instr**(3X) | | intrflush | **curs\_inopts**(3X) | | inwstr | **curs\_inwstr**(3X) | | is\_cbreak | **curs\_inopts**(3X)\* | | is\_cleared | **curs\_opaque**(3X)\* | | is\_echo | **curs\_inopts**(3X)\* | | is\_idcok | **curs\_opaque**(3X)\* | | is\_idlok | **curs\_opaque**(3X)\* | | is\_immedok | **curs\_opaque**(3X)\* | | is\_keypad | **curs\_opaque**(3X)\* | | is\_leaveok | **curs\_opaque**(3X)\* | | is\_linetouched | **curs\_touch**(3X) | | is\_nl | **curs\_inopts**(3X)\* | | is\_nodelay | **curs\_opaque**(3X)\* | | is\_notimeout | **curs\_opaque**(3X)\* | | is\_pad | **curs\_opaque**(3X)\* | | is\_raw | **curs\_inopts**(3X)\* | | is\_scrollok | **curs\_opaque**(3X)\* | | is\_subwin | **curs\_opaque**(3X)\* | | is\_syncok | **curs\_opaque**(3X)\* | | is\_term\_resized | **resizeterm**(3X)\* | | is\_wintouched | **curs\_touch**(3X) | | isendwin | **curs\_initscr**(3X) | | key\_defined | **key\_defined**(3X)\* | | key\_name | **curs\_util**(3X) | | keybound | **keybound**(3X)\* | | keyname | **curs\_util**(3X) | | keyok | **keyok**(3X)\* | | keypad | **curs\_inopts**(3X) | | killchar | **curs\_termattrs**(3X) | | killwchar | **curs\_termattrs**(3X) | | leaveok | **curs\_outopts**(3X) | | longname | **curs\_termattrs**(3X) | | mcprint | **curs\_print**(3X)\* | | meta | **curs\_inopts**(3X) | | mouse\_trafo | **curs\_mouse**(3X)\* | | mouseinterval | **curs\_mouse**(3X)\* | | mousemask | **curs\_mouse**(3X)\* | | move | **curs\_move**(3X) | | mvadd\_wch | **curs\_add\_wch**(3X) | | mvadd\_wchnstr | **curs\_add\_wchstr**(3X) | | mvadd\_wchstr | **curs\_add\_wchstr**(3X) | | mvaddch | **curs\_addch**(3X) | | mvaddchnstr | **curs\_addchstr**(3X) | | mvaddchstr | **curs\_addchstr**(3X) | | mvaddnstr | **curs\_addstr**(3X) | | mvaddnwstr | **curs\_addwstr**(3X) | | mvaddstr | **curs\_addstr**(3X) | | mvaddwstr | **curs\_addwstr**(3X) | | mvchgat | **curs\_attr**(3X) | | mvcur | **curs\_kernel**(3X) | | mvdelch | **curs\_delch**(3X) | | mvderwin | **curs\_window**(3X) | | mvget\_wch | **curs\_get\_wch**(3X) | | mvget\_wstr | **curs\_get\_wstr**(3X) | | mvgetch | **curs\_getch**(3X) | | mvgetn\_wstr | **curs\_get\_wstr**(3X) | | mvgetnstr | **curs\_getstr**(3X) | | mvgetstr | **curs\_getstr**(3X) | | mvhline | **curs\_border**(3X) | | mvhline\_set | **curs\_border\_set**(3X) | | mvin\_wch | **curs\_in\_wch**(3X) | | mvin\_wchnstr | **curs\_in\_wchstr**(3X) | | mvin\_wchstr | **curs\_in\_wchstr**(3X) | | mvinch | **curs\_inch**(3X) | | mvinchnstr | **curs\_inchstr**(3X) | | mvinchstr | **curs\_inchstr**(3X) | | mvinnstr | **curs\_instr**(3X) | | mvinnwstr | **curs\_inwstr**(3X) | | mvins\_nwstr | **curs\_ins\_wstr**(3X) | | mvins\_wch | **curs\_ins\_wch**(3X) | | mvins\_wstr | **curs\_ins\_wstr**(3X) | | mvinsch | **curs\_insch**(3X) | | mvinsnstr | **curs\_insstr**(3X) | | mvinsstr | **curs\_insstr**(3X) | | mvinstr | **curs\_instr**(3X) | | mvinwstr | **curs\_inwstr**(3X) | | mvprintw | **curs\_printw**(3X) | | mvscanw | **curs\_scanw**(3X) | | mvvline | **curs\_border**(3X) | | mvvline\_set | **curs\_border\_set**(3X) | | mvwadd\_wch | **curs\_add\_wch**(3X) | | mvwadd\_wchnstr | **curs\_add\_wchstr**(3X) | | mvwadd\_wchstr | **curs\_add\_wchstr**(3X) | | mvwaddch | **curs\_addch**(3X) | | mvwaddchnstr | **curs\_addchstr**(3X) | | mvwaddchstr | **curs\_addchstr**(3X) | | mvwaddnstr | **curs\_addstr**(3X) | | mvwaddnwstr | **curs\_addwstr**(3X) | | mvwaddstr | **curs\_addstr**(3X) | | mvwaddwstr | **curs\_addwstr**(3X) | | mvwchgat | **curs\_attr**(3X) | | mvwdelch | **curs\_delch**(3X) | | mvwget\_wch | **curs\_get\_wch**(3X) | | mvwget\_wstr | **curs\_get\_wstr**(3X) | | mvwgetch | **curs\_getch**(3X) | | mvwgetn\_wstr | **curs\_get\_wstr**(3X) | | mvwgetnstr | **curs\_getstr**(3X) | | mvwgetstr | **curs\_getstr**(3X) | | mvwhline | **curs\_border**(3X) | | mvwhline\_set | **curs\_border\_set**(3X) | | mvwin | **curs\_window**(3X) | | mvwin\_wch | **curs\_in\_wch**(3X) | | mvwin\_wchnstr | **curs\_in\_wchstr**(3X) | | mvwin\_wchstr | **curs\_in\_wchstr**(3X) | | mvwinch | **curs\_inch**(3X) | | mvwinchnstr | **curs\_inchstr**(3X) | | mvwinchstr | **curs\_inchstr**(3X) | | mvwinnstr | **curs\_instr**(3X) | | mvwinnwstr | **curs\_inwstr**(3X) | | mvwins\_nwstr | **curs\_ins\_wstr**(3X) | | mvwins\_wch | **curs\_ins\_wch**(3X) | | mvwins\_wstr | **curs\_ins\_wstr**(3X) | | mvwinsch | **curs\_insch**(3X) | | mvwinsnstr | **curs\_insstr**(3X) | | mvwinsstr | **curs\_insstr**(3X) | | mvwinstr | **curs\_instr**(3X) | | mvwinwstr | **curs\_inwstr**(3X) | | mvwprintw | **curs\_printw**(3X) | | mvwscanw | **curs\_scanw**(3X) | | mvwvline | **curs\_border**(3X) | | mvwvline\_set | **curs\_border\_set**(3X) | | napms | **curs\_kernel**(3X) | | newpad | **curs\_pad**(3X) | | newterm | **curs\_initscr**(3X) | | newwin | **curs\_window**(3X) | | nl | **curs\_inopts**(3X) | | nocbreak | **curs\_inopts**(3X) | | nodelay | **curs\_inopts**(3X) | | noecho | **curs\_inopts**(3X) | | nofilter | **curs\_util**(3X)\* | | nonl | **curs\_inopts**(3X) | | noqiflush | **curs\_inopts**(3X) | | noraw | **curs\_inopts**(3X) | | notimeout | **curs\_inopts**(3X) | | overlay | **curs\_overlay**(3X) | | overwrite | **curs\_overlay**(3X) | | pair\_content | **curs\_color**(3X) | | pecho\_wchar | **curs\_pad**(3X) | | pechochar | **curs\_pad**(3X) | | pnoutrefresh | **curs\_pad**(3X) | | prefresh | **curs\_pad**(3X) | | printw | **curs\_printw**(3X) | | putp | **curs\_terminfo**(3X) | | putwin | **curs\_util**(3X) | | qiflush | **curs\_inopts**(3X) | | raw | **curs\_inopts**(3X) | | redrawwin | **curs\_refresh**(3X) | | refresh | **curs\_refresh**(3X) | | reset\_color\_pairs | **curs\_color**(3X)\* | | reset\_prog\_mode | **curs\_kernel**(3X) | | reset\_shell\_mode | **curs\_kernel**(3X) | | resetty | **curs\_kernel**(3X) | | resize\_term | **resizeterm**(3X)\* | | resizeterm | **resizeterm**(3X)\* | | restartterm | **curs\_terminfo**(3X) | | ripoffline | **curs\_kernel**(3X) | | savetty | **curs\_kernel**(3X) | | scanw | **curs\_scanw**(3X) | | scr\_dump | **curs\_scr\_dump**(3X) | | scr\_init | **curs\_scr\_dump**(3X) | | scr\_restore | **curs\_scr\_dump**(3X) | | scr\_set | **curs\_scr\_dump**(3X) | | scrl | **curs\_scroll**(3X) | | scroll | **curs\_scroll**(3X) | | scrollok | **curs\_outopts**(3X) | | set\_curterm | **curs\_terminfo**(3X) | | set\_escdelay | **curs\_threads**(3X)\* | | set\_tabsize | **curs\_threads**(3X)\* | | set\_term | **curs\_initscr**(3X) | | setcchar | **curs\_getcchar**(3X) | | setscrreg | **curs\_outopts**(3X) | | setsyx | **curs\_kernel**(3X) | | setupterm | **curs\_terminfo**(3X) | | slk\_attr | **curs\_slk**(3X)\* | | slk\_attr\_off | **curs\_slk**(3X) | | slk\_attr\_on | **curs\_slk**(3X) | | slk\_attr\_set | **curs\_slk**(3X) | | slk\_attroff | **curs\_slk**(3X) | | slk\_attron | **curs\_slk**(3X) | | slk\_attrset | **curs\_slk**(3X) | | slk\_clear | **curs\_slk**(3X) | | slk\_color | **curs\_slk**(3X) | | slk\_init | **curs\_slk**(3X) | | slk\_label | **curs\_slk**(3X) | | slk\_noutrefresh | **curs\_slk**(3X) | | slk\_refresh | **curs\_slk**(3X) | | slk\_restore | **curs\_slk**(3X) | | slk\_set | **curs\_slk**(3X) | | slk\_touch | **curs\_slk**(3X) | | slk\_wset | **curs\_slk**(3X) | | standend | **curs\_attr**(3X) | | standout | **curs\_attr**(3X) | | start\_color | **curs\_color**(3X) | | subpad | **curs\_pad**(3X) | | subwin | **curs\_window**(3X) | | syncok | **curs\_window**(3X) | | term\_attrs | **curs\_termattrs**(3X) | | termattrs | **curs\_termattrs**(3X) | | termname | **curs\_termattrs**(3X) | | tgetent | **curs\_termcap**(3X) | | tgetflag | **curs\_termcap**(3X) | | tgetnum | **curs\_termcap**(3X) | | tgetstr | **curs\_termcap**(3X) | | tgoto | **curs\_termcap**(3X) | | tigetflag | **curs\_terminfo**(3X) | | tigetnum | **curs\_terminfo**(3X) | | tigetstr | **curs\_terminfo**(3X) | | timeout | **curs\_inopts**(3X) | | tiparm | **curs\_terminfo**(3X) | | tiparm\_s | **curs\_terminfo**(3X)\* | | tiscan\_s | **curs\_terminfo**(3X)\* | | touchline | **curs\_touch**(3X) | | touchwin | **curs\_touch**(3X) | | tparm | **curs\_terminfo**(3X) | | tputs | **curs\_termcap**(3X) | | tputs | **curs\_terminfo**(3X) | | trace | **curs\_trace**(3X)\* | | typeahead | **curs\_inopts**(3X) | | unctrl | **curs\_util**(3X) | | unget\_wch | **curs\_get\_wch**(3X) | | ungetch | **curs\_getch**(3X) | | ungetmouse | **curs\_mouse**(3X)\* | | untouchwin | **curs\_touch**(3X) | | use\_default\_colors | **default\_colors**(3X)\* | | use\_env | **curs\_util**(3X) | | use\_extended\_names | **curs\_extend**(3X)\* | | use\_legacy\_coding | **legacy\_coding**(3X)\* | | use\_screen | **curs\_threads**(3X)\* | | use\_tioctl | **curs\_util**(3X)\* | | use\_window | **curs\_threads**(3X)\* | | vid\_attr | **curs\_terminfo**(3X) | | vid\_puts | **curs\_terminfo**(3X) | | vidattr | **curs\_terminfo**(3X) | | vidputs | **curs\_terminfo**(3X) | | vline | **curs\_border**(3X) | | vline\_set | **curs\_border\_set**(3X) | | vw\_printw | **curs\_printw**(3X) | | vw\_scanw | **curs\_scanw**(3X) | | vwprintw | **curs\_printw**(3X) | | vwscanw | **curs\_scanw**(3X) | | wadd\_wch | **curs\_add\_wch**(3X) | | wadd\_wchnstr | **curs\_add\_wchstr**(3X) | | wadd\_wchstr | **curs\_add\_wchstr**(3X) | | waddch | **curs\_addch**(3X) | | waddchnstr | **curs\_addchstr**(3X) | | waddchstr | **curs\_addchstr**(3X) | | waddnstr | **curs\_addstr**(3X) | | waddnwstr | **curs\_addwstr**(3X) | | waddstr | **curs\_addstr**(3X) | | waddwstr | **curs\_addwstr**(3X) | | wattr\_get | **curs\_attr**(3X) | | wattr\_off | **curs\_attr**(3X) | | wattr\_on | **curs\_attr**(3X) | | wattr\_set | **curs\_attr**(3X) | | wattroff | **curs\_attr**(3X) | | wattron | **curs\_attr**(3X) | | wattrset | **curs\_attr**(3X) | | wbkgd | **curs\_bkgd**(3X) | | wbkgdset | **curs\_bkgd**(3X) | | wbkgrnd | **curs\_bkgrnd**(3X) | | wbkgrndset | **curs\_bkgrnd**(3X) | | wborder | **curs\_border**(3X) | | wborder\_set | **curs\_border\_set**(3X) | | wchgat | **curs\_attr**(3X) | | wclear | **curs\_clear**(3X) | | wclrtobot | **curs\_clear**(3X) | | wclrtoeol | **curs\_clear**(3X) | | wcolor\_set | **curs\_attr**(3X) | | wcursyncup | **curs\_window**(3X) | | wdelch | **curs\_delch**(3X) | | wdeleteln | **curs\_deleteln**(3X) | | wecho\_wchar | **curs\_add\_wch**(3X) | | wechochar | **curs\_addch**(3X) | | wenclose | **curs\_mouse**(3X)\* | | werase | **curs\_clear**(3X) | | wget\_wch | **curs\_get\_wch**(3X) | | wget\_wstr | **curs\_get\_wstr**(3X) | | wgetbkgrnd | **curs\_bkgrnd**(3X) | | wgetch | **curs\_getch**(3X) | | wgetdelay | **curs\_opaque**(3X)\* | | wgetn\_wstr | **curs\_get\_wstr**(3X) | | wgetnstr | **curs\_getstr**(3X) | | wgetparent | **curs\_opaque**(3X)\* | | wgetscrreg | **curs\_opaque**(3X)\* | | wgetstr | **curs\_getstr**(3X) | | whline | **curs\_border**(3X) | | whline\_set | **curs\_border\_set**(3X) | | win\_wch | **curs\_in\_wch**(3X) | | win\_wchnstr | **curs\_in\_wchstr**(3X) | | win\_wchstr | **curs\_in\_wchstr**(3X) | | winch | **curs\_inch**(3X) | | winchnstr | **curs\_inchstr**(3X) | | winchstr | **curs\_inchstr**(3X) | | winnstr | **curs\_instr**(3X) | | winnwstr | **curs\_inwstr**(3X) | | wins\_nwstr | **curs\_ins\_wstr**(3X) | | wins\_wch | **curs\_ins\_wch**(3X) | | wins\_wstr | **curs\_ins\_wstr**(3X) | | winsch | **curs\_insch**(3X) | | winsdelln | **curs\_deleteln**(3X) | | winsertln | **curs\_deleteln**(3X) | | winsnstr | **curs\_insstr**(3X) | | winsstr | **curs\_insstr**(3X) | | winstr | **curs\_instr**(3X) | | winwstr | **curs\_inwstr**(3X) | | wmouse\_trafo | **curs\_mouse**(3X)\* | | wmove | **curs\_move**(3X) | | wnoutrefresh | **curs\_refresh**(3X) | | wprintw | **curs\_printw**(3X) | | wredrawln | **curs\_refresh**(3X) | | wrefresh | **curs\_refresh**(3X) | | wresize | **wresize**(3X)\* | | wscanw | **curs\_scanw**(3X) | | wscrl | **curs\_scroll**(3X) | | wsetscrreg | **curs\_outopts**(3X) | | wstandend | **curs\_attr**(3X) | | wstandout | **curs\_attr**(3X) | | wsyncdown | **curs\_window**(3X) | | wsyncup | **curs\_window**(3X) | | wtimeout | **curs\_inopts**(3X) | | wtouchln | **curs\_touch**(3X) | | wunctrl | **curs\_util**(3X) | | wvline | **curs\_border**(3X) | | wvline\_set | **curs\_border\_set**(3X) | *ncurses*'s *screen-pointer extension* **adds additional functions corresponding to many of the above,** **each with an “\_sp” suffix;** **see curs\_sp\_funcs(3X).** **The availability of some extensions is configurable when** *ncurses* **is compiled;** **see sections “ALTERNATE CONFIGURATIONS” and “EXTENSIONS”** **below.** ## RETURN VALUE **Unless otherwise noted,** **functions that return integers return the constants** **OK** **on success and** **ERR** **on failure;** **see curs\_variables(3X).** **Functions that return pointers return a null pointer on failure.** **Typically,** *ncurses* **treats a null pointer passed as a function parameter as a failure.** **Functions prefixed with “mv” first perform cursor movement and** **fail if the position** (*y*, *x*) **is outside the window boundaries.** ## ENVIRONMENT **The following symbols from the process environment customize the** **runtime behavior of** *ncurses* **applications.** **The library may be configured to disregard the variables** *TERMINFO*, *TERMINFO\_DIRS*, *TERMPATH*, **and** *HOME*, **if the user is the superuser (root),** **or the application uses** *setuid***(2) or** *setgid***(2).** ### *BAUDRATE* **The debugging library checks this variable when the application has** **redirected output to a file.** *ncurses* **interprets its integral value as the terminal's line speed** **in bits per second.** **If that value is absent or invalid,** *ncurses* **uses 9600.** **This feature allows developers to construct repeatable test cases** **that take into account optimization decisions that depend** **on the terminal's line speed.** ### *CC* (command character) **When set,** **the** **command\_character** (**cmdch**) **capability value of loaded** *terminfo* **entries changes to the value of this variable.** **Very few** *terminfo* **entries provide this feature.** **Because this name is also used in development environments to store the** **C compiler's name,** *ncurses* **ignores its value if it is not one character in length.** ### *COLUMNS* **This variable specifies the width of the screen in character cells.** **Applications running in a windowing environment usually are able to** **obtain the width of the window in which they are executing.** *ncurses* **enforces an upper limit of 512 when reading the value.** **If** *COLUMNS* **is not defined and the terminal's screen size is not available from the** **terminal driver,** *ncurses* **uses the size specified by the** **columns** (**cols**) **capability of the terminal type's entry in the** *terminfo* **database,** **if any.** **It is important that your application use the correct screen size.** **Automatic detection thereof is not always possible because an** **application may be running on a host that does not honor NAWS** **(Negotiations About Window Size)** **or as a different user ID than the owner of the terminal device file.** **Setting** *COLUMNS* **and/or** *LINES* **overrides the library's use of the screen size obtained from the** **operating system.** **The** *COLUMNS* **and** *LINES* **variables may be specified independently.** **This property is useful to circumvent misfeatures of legacy terminal** **type descriptions;** *xterm***(1) descriptions specifying 65 lines were once notorious.** **For best results,** **avoid specifying** **cols** **and** **lines** **capability codes in** *terminfo* **descriptions of terminal emulators.** **use\_env(3X) can disable use of the process environment** **in determining the screen size.** **use\_tioctl(3X) can update** *COLUMNS* **and** *LINES* **to match the screen size obtained from system calls or the terminal** **database.** ### *ESCDELAY* **For** *curses* **to distinguish the ESC character resulting from a user's press of the** **“Escape” key on the input device from one beginning an** *escape sequence* **(as commonly produced by function keys),** **it waits after receiving the escape character to see if further** **characters are available on the input stream within a short interval.** **A global variable** **ESCDELAY** **stores this interval in milliseconds.** **The default value of 1000** **(one second)** **is adequate for most uses.** **This environment variable overrides it;** *ncurses* **enforces an upper limit of 30,000** **(30 seconds)** **when reading the value.** **The most common instance where you may wish to change this value** **is to work with a remote host over a slow communication channel.** **If the host running a** *curses* **application does not receive the characters of an escape sequence in a** **timely manner,** **the library can interpret them as multiple key stroke events.** **Conversely,** **a fast typist on a low-latency connection who happens to input an ESC** **followed by characters that match an escape sequence may experience** **confusing application behavior.** *xterm***(1) mouse events are a form of escape sequence;** **therefore,** **if your application makes heavy use of multiple-clicking,** **you may wish to lengthen the default value because the delay applies** **to the composite multi-click event as well as the individual clicks.** **Portable applications should not rely upon the presence of** **ESCDELAY** **in either form,** **but setting the environment variable rather than the global variable** **does not create problems when compiling an application.** **If keypad(3X) is disabled for the** *curses* **window receiving input,** **ESCDELAY** **is irrelevant** **and a program must disambiguate escape sequences itself.** ### *HOME* *ncurses* **may read and write auxiliary terminal descriptions in** *.termcap* **and** *.terminfo* **files in the user's home directory.** ### *LINES* **This counterpart to** *COLUMNS* **specifies the height of the screen in characters.** **The corresponding** *terminfo* **capability and code is** **lines**. **See the description of the** *COLUMNS* **variable above.** ### *MOUSE\_BUTTONS\_123* **(OS/2 EMX port only)** **OS/2 numbers a three-button mouse inconsistently with other platforms,** **such that 1 is the left button,** **2 the right,** **and 3 the middle.** **This variable customizes the mouse button numbering.** **Its value must be three digits 1-3 in any order.** **By default,** *ncurses* **assumes a numbering of “132”.** ### *NCURSES\_ASSUMED\_COLORS* **If set,** **this variable overrides the** *ncurses* **library's compiled-in assumption that the terminal's default colors are** **white on black;** **see default\_colors(3X).** **Set the foreground and background color values with this environment** **variable by assigning it two integer values separated by a comma,** **indicating foregound and background color numbers,** **respectively.** **For example,** **to tell** *ncurses* **not to assume anything about the colors,** **use a value of “-1,-1”.** **To make the default color scheme green on black on a terminal** **that uses ANSI X3.64/ECMA-48/ISO 6429 color assignments,** **use “2,0”.** *ncurses* **accepts integral values from -1 up to the value of the** *terminfo* **max\_colors** (**colors**) **capability for the selected terminal type.** ### *NCURSES\_CONSOLE2* **(MinGW port only)** **The** *Console2* **program defectively handles the Microsoft Console API call** *CreateConsoleScreenBuffer*. **Applications that use it will hang.** **However,** **it is possible to simulate the action of this call by mapping** **coordinates,** **explicitly saving and restoring the original screen contents.** **Setting the environment variable** *NCGDB* **has the same effect.** ### *NCURSES\_GPM\_TERMS* **(Linux only)** **When** *ncurses* **is configured to use the GPM interface,** **this variable may list one or more terminal type names,** **delimited by vertical bars** (**\|**) **or colons** (**:**), **against which the** *TERM* **variable** **(see below)** **is matched.** **An empty value disables the GPM interface,** **using** *ncurses*'s **built-in support for** *xterm***(1) mouse protocols instead.** **If the variable is absent,** *ncurses* **attempts to open GPM if** *TERM* **contains “linux”.** ### *NCURSES\_NO\_HARD\_TABS* *ncurses* **may use tab characters in cursor movement optimization.** **In some cases,** **your terminal driver may not handle them properly.** **Set this environment variable to any value to disable the feature.** **You can also adjust your** *stty***(1) settings to avoid the problem.** ### *NCURSES\_NO\_MAGIC\_COOKIE* **Many terminals store video attributes as properties of a character cell,** **as** *curses* **does.** **Historically,** **some recorded changes in video attributes as data** **that logically** **(but invisibly)** *occupied* **character cells on the display,** **switching attributes on or off,** **similarly to tags in a markup language,** **which then had to be overprinted to depict the cells' desired contents;** **these are termed “magic cookies”.** **If the** *terminfo* **entry for your terminal type does not adequately describe its handling** **of magic cookies,** **set this variable to any value to instruct** *ncurses* **to disable attributes entirely.** ### *NCURSES\_NO\_PADDING* **Most terminal type descriptions in the** *terminfo* **database detail hardware devices.** **Many people use** *curses*-based **applications in terminal emulator programs that run in a windowing** **environment.** **These programs can duplicate all of the important features of a hardware** **terminal,** **but often lack their limitations.** **Chief among these absent drawbacks is the problem of data flow** **management;** **that is,** **limiting the speed of communication to what the hardware could handle.** **Unless a hardware terminal is interfaced into a terminal concentrator** **(which does flow control),** **an application must manage flow itself to prevent overruns and data** **loss.** **A solution that comes at no hardware cost** **is for an application to pause transmission** **after directing a terminal to execute an operation** **that it performs slowly,** **such as clearing the display.** **Many terminal type descriptions,** **including that for the VT100,** **embed delay specifications in capabilities.** **You may wish to use these terminal descriptions without paying the** **performance penalty.** **Set** *NCURSES\_NO\_PADDING* **to any value to disable all but mandatory padding.** **Mandatory padding is used by such terminal capabilities as** **flash\_screen** (**flash**). ### *NCURSES\_NO\_SETBUF* **(Obsolete)** **Prior to internal changes developed in** *ncurses* **5.9** **(patches 20120825 through 20130126),** **the library used** *setbuf***(3) to enable fully buffered output when** **initializing the terminal.** **This was done,** **as in SVr4** *curses*, **to increase performance.** **For testing purposes,** **both of** *ncurses* **and of certain applications,** **this feature was made optional.** **Setting this variable disabled output buffering,** **leaving the output stream in the original** **(usually line-buffered)** **mode.** **Nowadays,** *ncurses* **performs its own buffering and does not require this workaround;** **it does not modify the buffering of the standard output stream.** **This approach makes the library's handling of keyboard-initiated signals** **more robust.** **A drawback is that certain unconventional programs mixed** *stdio***(3) calls with** *ncurses* **calls and (usually)** **got the behavior they expected.** **This is no longer the case;** *ncurses* **does not write to the standard output file descriptor through a** *stdio*-buffered **stream.** **As a special case,** **low-level API calls such as putp(3X) still use the** **standard output stream.** **High-level** *curses* **calls such as printw(3X) do not.** ### *NCURSES\_NO\_UTF8\_ACS* **At initialization,** *ncurses* **inspects the** *TERM* **environment variable for special cases where VT100 forms-drawing** **characters** **(and the corresponding alternate character set** *terminfo* **capabilities)** **are known to be unsupported by terminal types that otherwise claim VT100** **compatibility.** **Specifically,** **when running in a UTF-8 locale,** **the Linux virtual console device and the GNU** *screen***(1)** **program ignore them.** **Set this variable to a nonzero value to instruct** *ncurses* **that the terminal's ACS support is broken;** **the library then outputs Unicode code points that correspond to the** **forms-drawing** **characters.** **Set it to zero** **(or a non-integer)** **to disable the special check for terminal type names matching** **“linux” or “screen”,** **directing** *ncurses* **to assume that the ACS feature works if the terminal type description** **advertises it.** **As an alternative to use of this variable,** *ncurses* **checks for an extended** *terminfo* **numeric capability U8** **that can be compiled using** “**tic -x**”. **Examples follow.** ``` # linux console, if patched to provide working # VT100 shift-in/shift-out, with corresponding font. linux-vt100|linux console with VT100 line-graphics, U8#0, use=linux, # uxterm with vt100Graphics resource set to false xterm-utf8|xterm relying on UTF-8 line-graphics, U8#1, use=xterm, ``` **The two-character name “U8” was chosen to permit its use via** *ncurses*'s *termcap* **interface.** ### *NCURSES\_TRACE* **At initialization,** *ncurses* **(in its debugging configuration)** **checks for this variable's presence.** **If defined with an integral value,** **the library calls curses\_trace(3X) with that value as the** **argument.** ### *TERM* **The** *TERM* **variable denotes the terminal type.** **Each is distinct,** **though many are similar.** **It is commonly set by terminal emulators to help applications find a** **workable terminal description.** **Some choose a popular approximation such as “ansi”,** **“vt100”, or “xterm” rather than an exact fit to their** **capabilities.** **Not infrequently,** **an application will have problems with that approach;** **for example,** **a key stroke may not operate correctly,** **or produce no effect but seeming garbage characters on the screen.** **Setting** *TERM* **has no effect on hardware operation;** **it affects the way applications communicate with the terminal.** **Likewise,** **as a general rule** **(***xterm***(1) being a rare exception),** **terminal emulators that allow you to specify** *TERM* **as a parameter or configuration value do not change their behavior to** **match that setting.** ### *TERMCAP* **If** *ncurses* **is configured with** *termcap* **support,** **it checks for a terminal type description in** *termcap* **format if one in** *terminfo* **format is not available.** **Setting this variable directs** *ncurses* **to ignore the usual** *termcap* **database location,** */etc/termcap*; **see** *TERMPATH* **below.** *TERMCAP* **should contain either a terminal description** **(with newlines stripped out),** **or a file name indicating where the information required by the** *TERM* **environment variable is stored.** ### *TERMINFO* *ncurses* **can be configured to read terminal type description databases in various** **locations using different formats.** **This variable overrides the default location.** - • **Descriptions in** *terminfo* **format are normally stored in a directory tree using subdirectories** **named for the common first letters of the terminal types named therein.** **System V used this scheme.** - • **If** *ncurses* **is configured to use hashed databases,** **then** *TERMINFO* **may name its location,** **such as** */usr/share/terminfo.db*, **rather than** */usr/share/terminfo/*. **The hashed database uses less disk space and is a little faster than the** **directory tree.** **However,** **some applications assume the existence of the directory tree** **and read it directly,** **ignoring the** *terminfo* **API.** - • **If** *ncurses* **is configured with** *termcap* **support,** **this variable may contain the location of a** *termcap* **file.** - • **If the value of** *TERMINFO* **begins with “hex:” or “b64:”,** *ncurses* **uses the remainder of the value as a compiled** *terminfo* **description.** **You might produce the base64 format using infocmp(1M).** - ``` TERMINFO=$(infocmp -0 -Q2 -q) export TERMINFO ``` - *ncurses* **uses the compiled description only if it corresponds** **to the terminal type identified by** *TERM*. **Setting** *TERMINFO* **is the simplest,** **but not the only,** **way to direct** *ncurses* **to a terminal database.** **The search path is as follows.** - • **the last terminal database to which the running** *ncurses* **application wrote,** **if any** - • **the location specified by the** *TERMINFO* **environment variable** - • *$HOME/.terminfo* - • **locations listed in the** *TERMINFO\_DIRS* **environment variable** - • **location(s) configured and compiled into** *ncurses* - • *@TERMINFO\_DIRS@* - • */usr/share/misc/terminfo* ### *TERMINFO\_DIRS* **This variable specifies a list of locations,** **akin to** *PATH*, **in which** *ncurses* **searches for the terminal type descriptions described by** *TERMINFO* **above.** **The list items are separated by colons on Unix** **and semicolons on OS/2 EMX.** **System V** *terminfo* **lacks a corresponding feature;** *TERMINFO\_DIRS* **is an** *ncurses* **extension.** ### *TERMPATH* **If** *TERMCAP* **does not hold a terminal type description or file name,** **then** *ncurses* **checks the contents of** *TERMPATH*, **a list of locations,** **akin to** *PATH*, **in which it searches for** *termcap* **terminal type descriptions.** **The list items are separated by colons on Unix** **and semicolons on OS/2 EMX.** **If both** *TERMCAP* **and** *TERMPATH* **are unset or invalid,** *ncurses* **searches for the files** */etc/termcap*, */usr/share/misc/termcap*, **and** *$HOME/.termcap*, **in that order.** ## ALTERNATE CONFIGURATIONS **Many different** *ncurses* **configurations are possible,** **determined by the options given to the** *configure* **script when building the library.** **Run the script with the** **--help** **option to peruse them all.** **A few are of particular significance to the application developer** **employing** *ncurses*. - **--disable-overwrite** **Avoid file name conflicts between** *ncurses* **and an existing** *curses* **installation on the system.** **The standard C preprocessor inclusion for the** *curses* **library is as follows.** ``` #include ``` **If** *ncurses* **is installed disabling overwrite,** **it puts its header files in a subdirectory.** **Here is an example.** ``` #include ``` **With** **--disable-overwrite**, **installation also omits a symbolic link that would cause the compiler's** **-lcurses** **option to link object files with** *ncurses* **instead of the system** *curses* **library.** **The directory used by this configuration of** *ncurses* **is shown in section “SYNOPSIS” above.** - **--enable-widec** **(default for ABI 6+ since 2023-10-21)** **Enable support for wide characters.** **The** *configure* **script renames the** *ncurses* **library** **(and the** *tinfo* **library,** **if** **--with-termlib** **is also specified),** **appending “w”.** **An application desirous of wide-character support then uses** **-lncursesw** **(or** **-ltinfow**) **instead of** **-lncurses** **(or** **-ltinfo**) **as its linker option.** **The** *ncurses++*, *panel*, *form*, **and** *menu* **libraries are renamed similarly.** - **An application must also** **define certain C preprocessor symbols** **to enable wide-character features** **in** *curses* **header files** **to use the extended (wide-character) functions.** **The symbol that enables these features has changed** **since X/Open Curses Issue 4.** - • **Originally,** **the wide-character feature required the symbol** *\_XOPEN\_SOURCE\_EXTENDED*, **but that was valid only for XPG4 (1996).** - • **Later,** **that was deemed conflicting with an** *\_XOPEN\_SOURCE* **value of 500.** - • **As of mid-2018,** **no** *ncurses* **feature requires a** *\_XOPEN\_SOURCE* **value greater than 600.** **However,** **X/Open Curses Issue 7 (2009) recommends defining it to 700.** - • **Alternatively,** **you can enable the feature by defining** **NCURSES\_WIDECHAR** **with the caveat that some header file other than** *curses.h* **may require a specific value for** *\_XOPEN\_SOURCE* **(or a system-specific symbol).** - **The** *curses.h* **header file installed** **for the wide-character library** **is designed to be compatible with the non-wide library's header.** **Only the size of the** *WINDOW* **structure differs;** **few applications require more than pointers to** *WINDOW*. - **If** *ncurses*'s **header files are installed allowing overwrite** **(the default,** **but see** **--disable-overwrite** **above),** **the wide-character library's headers should be installed last** **by packaging systems and similar,** **to allow applications to be built using either library** **from the same set of headers.** - **--with-pthread** **Enable support for multi-threaded applications.** **The** *configure* **script renames the** *ncurses* **library** **(and the** *tinfo* **library,** **if** **--with-termlib** **is also specified),** **appending “t”** **(before any “w” added by** **--enable-widec**). **An application desirous of support for multiple threads of execution** **then uses,** **for example,** **-lncursest** **(or** **-ltinfot**) **instead of** **-lncurses** **(or** **-ltinfo**) **as its linker option.** **The** *ncurses++*, *panel*, *form*, **and** *menu* **libraries are renamed similarly.** - *ncursest* **and** *ncursestw* **replace global variables such as** **LINES** **with macros allowing read-only access.** **At the same time,** **they provide functions to set these values.** **Very few applications require changes** **to work with this convention.** - **--with-shared** - **--with-normal** - **--with-debug** - **--with-profile** **Mandate compilation of the** *ncurses* **library** **(and the** *tinfo* **library,** **if** **--with-termlib** **is also specified)** **in the specified forms.** **The shared and normal (static) library names differ by their suffixes,** **as with** *libncurses.so* **and** *libncurses.a*. **The debugging and profiling libraries add a “\_g”** **and a “\_p” to the roots of these respective names,** **forming** *libncurses\_g.so* **and** *libncurses\_p.a*, **for example.** **The** *ncurses++*, *panel*, *form*, **and** *menu* **libraries are made available similarly.** - **--with-termlib** **Provide** *ncurses*'s **lower-level terminal interface functions** **(those that do not depend** **on the** *SCREEN* **and** *WINDOW* **abstractions)** **in a library named** *tinfo*. **This arrangement reduces an application's linking and/or loading times** **when it does not require** *curses*'s **higher-level features.** - **The following pages document** *curses* **functions provided by** *tinfo*. - • **curs\_extend(3X) - miscellaneous** *ncurses* **extensions** - • **curs\_inopts(3X) -** *curses* **input options** - • **curs\_kernel(3X) - low-level** *curses* **routines** - • **curs\_termattrs(3X) -** *curses* **environment query routines** - • **curs\_termcap(3X) -** *curses* **emulation of** *termcap* - • **curs\_terminfo(3X) -** *curses* **interface to** *terminfo* **database** - • **curs\_util(3X) - miscellaneous** *curses* **utility routines** - **--with-trace** **Expose the curses\_trace(3X) function** **in the** *ncurses(w)* **shared and static libraries.** **Normally,** **it is available only in the debugging library.** **(If** **--with-termlib** **is also specified,** *tinfo(w)* **rather than** *ncurses(w)* **supplies the deprecated trace(3X) function.)** **An application's configuration script should check** **for the function's existence** **rather than assuming its confinement to the debugging library.** ## FILES - */usr/share/tabset* **tab stop initialization database** - */usr/share/misc/terminfo* **compiled terminal capability database** ## NOTES **X/Open Curses permits most functions it specifies to be made available** **as macros as well.** *ncurses* **does so** - • **for functions that return values via their parameters,** - • **to support obsolete features,** - • **to reuse functions** **(for example,** **those that move the cursor before another operation),** **and** - • **in a few special cases.** **If the standard output file descriptor of an** *ncurses* **program is redirected to something that is not a terminal device,** **the library writes screen updates to the standard error file descriptor.** **This was an undocumented feature of SVr3** *curses*. **See subsection “Header Files” below regarding symbols exposed by** **inclusion of** *curses.h***.** ## EXTENSIONS *ncurses* **enables an application to capture mouse events from certain terminals,** **including** *xterm***(1);** **see curs\_mouse(3X).** *ncurses* **provides a means of responding to window resizing events,** **as when running in a GUI terminal emulator application such as** *xterm*; **see resizeterm(3X) and wresize(3X).** *ncurses* **allows an application to query the terminal for the presence of a wide** **variety of special keys;** **see has\_key(3X).** *ncurses* **extends the fixed set of function key capabilities specified by X/Open** **Curses by allowing the application programmer to define additional key** **events at runtime;** **see** **define\_key(3X),** **key\_defined(3X),** **keybound(3X),** **and** **keyok(3X).** *ncurses* **can exploit the capabilities of terminals implementing ISO 6429/ECMA-48** **SGR 39 and SGR 49 sequences,** **which allow an application to reset the terminal to its original** **foreground and background colors.** **From a user's perspective,** **the application is able to draw colored text on a background whose color** **is set independently,** **providing better control over color contrasts.** **See default\_colors(3X).** **An** *ncurses* **application can eschew knowledge of** *SCREEN* **and** *WINDOW* **structure internals,** **instead using accessor functions such as** **is\_cbreak(3X) and** **is\_scrollok(3X).** *ncurses* **enables an application to direct its output to a printer attached to the** **terminal device;** **see curs\_print(3X).** *ncurses* **offers slk\_attr(3X) as a counterpart of attr\_get(3X) for** **soft-label key lines,** **and extended\_slk\_color(3X) as a form of slk\_color(3X)** **that can gather color information from them when many colors are** **supported.** *ncurses* **permits modification of unctrl(3X)'s behavior;** **see use\_legacy\_coding(3X).** **Rudimentary support for multi-threaded applications may be available;** **see curs\_threads(3X).** **Functions that ease the management of multiple screens can be exposed;** **see curs\_sp\_funcs(3X).** **To aid applications to debug their memory usage,** *ncurses* **optionally offers functions to more aggressively free memory it** **dynamically allocates itself;** **see curs\_memleaks(3X).** **The library facilitates auditing and troubleshooting of its behavior;** **see curs\_trace(3X).** **Compiling** *ncurses* **with the option** **-DUSE\_GETCAP** **causes it to fall back to reading** */etc/termcap* **if the terminal setup code cannot find a** *terminfo* **entry corresponding to** *TERM*. **Use of this feature is not recommended,** **as it essentially includes an entire** *termcap* **compiler in the** *ncurses* **startup code,** **at a cost in memory usage and application launch latency.** *PDCurses* **and NetBSD** *curses* **incorporate some** *ncurses* **extensions.** **Individual man pages indicate where this is the case.** ## PORTABILITY **X/Open Curses defines two levels of conformance,** **“base” and “enhanced”.** **The latter includes several additional features,** **such as wide-character and color support.** *ncurses* **intends base-level conformance with X/Open Curses,** **and supports all features of its enhanced level** **except the** *untic* **utility.** **Differences between X/Open Curses and** *ncurses* **are documented in the “PORTABILITY” sections of applicable man** **pages.** ### Error Checking **In many cases, X/Open Curses is vague about error conditions,** **omitting some of the SVr4 documentation.** **Unlike other implementations,** *ncurses* **checks pointer parameters,** **such as those to** *WINDOW* **structures,** **to ensure that they are not null.** **This is done primarily to guard against programmer error.** **The standard interface does not provide a way for the library** **to tell an application which of several possible errors occurred.** **An application that relies on** *ncurses* **to check its function parameters for validity limits its portability and** **robustness.** ### Padding Differences **In historical** *curses* **implementations,** **delays embedded in the** *terminfo* **capabilities** **carriage\_return** (**cr**), **scroll\_forward** (**ind**), **cursor\_left** (**cub1**), **form\_feed** (**ff**), **and** **tab** (**ht**) **activated corresponding delay bits in the Unix terminal driver.** *ncurses* **performs all padding by sending NUL bytes to the device.** **This method is slightly more expensive,** **but narrows the interface to the Unix kernel significantly and** **correspondingly increases the package's portability.** ### Header Files **The header file** *curses.h* **itself includes the header files** *stdio.h* **and** *unctrl.h*. **X/Open Curses has more to say,** **The inclusion of** *curses.h* **may make visible all symbols from the headers** *stdio.h*, *term.h*, *termios.h*, **and** *wchar.h*. **but does not finish the story.** **A more complete account follows.** - • **The first** *curses*, **in 4BSD,** **provided a** *curses.h* **file.** - **BSD** *curses* **code included** *curses.h* **and** *unctrl.h* **from an internal header file** *curses.ext*, **where** **“ext” abbreviated “externs”.** - **The implementations of** *printw* **and** *scanw* **used undocumented internal functions of the standard I/O library** (*\_doprnt* **and** *\_doscan*), **but nothing in** *curses.h* **itself relied upon** *stdio.h*. - • **SVr2** *curses* **added** *newterm*, **which relies upon** *stdio.h* **because its function prototype employs the** *FILE* **type.** - **SVr4** *curses* **added** *putwin* **and** *getwin*, **which also use** *stdio.h*. - **X/Open Curses specifies all three of these functions.** - **SVr4** *curses* **and X/Open Curses do not require the developer to include** *stdio.h* **before** *curses.h*. **Both document use of** *curses* **as requiring only** *curses.h*. - **As a result,** **standard** *curses.h* **always includes** *stdio.h*. - • **X/Open Curses and SVr4** *curses* **are inconsistent with respect to** *unctrl.h*. - **As noted in curs\_util(3X),** *ncurses* **includes** *unctrl.h* **from** *curses.h* **(as SVr4 does).** - • **X/Open Curses's comments about** *term.h* **and** *termios.h* **may refer to HP-UX and AIX.** - **HP-UX** *curses* **includes** *term.h* **from** *curses.h* **to declare** *setupterm* **in** *curses.h*, **but** *ncurses* **and Solaris** *curses* **do not.** - **AIX** *curses* **includes** *term.h* **and** *termios.h*. **Again,** *ncurses* **and Solaris** *curses* **do not.** - • **X/Open Curses says that** *curses.h* **may** **include** *term.h*, **but does not require it to do so.** - **Some programs use functions declared in both** *curses.h* **and** *term.h*, **and must include both header files in the same translation unit.** - **The header files supplied by** *ncurses* **include the standard library headers required for its declarations,** **so** *ncurses*'s **own header files can be included in any order.** **For portability even to old AIX systems,** **include** *curses.h* **before** *term.h*. - • **X/Open Curses says “may make visible” because including a header** **file does not necessarily make visible all of the symbols in it** **(consider** **#ifdef** **and similar).** - **For instance,** *ncurses*'s *curses.h* **may** **include** *wchar.h* **if the proper symbol is defined,** **and if** *ncurses* **is configured for wide-character support.** **If** *wchar.h* **is included,** **its symbols** **may** **be made visible depending on the value of the** *\_XOPEN\_SOURCE* **feature test macro.** - • **X/Open Curses mandates an application's inclusion of one standard C** **library header in a special case:** *stdarg.h* **before** *curses.h* **to prototype the functions** *vw\_printw* **and** *vw\_scanw* **(as well as the obsolete** *vwprintw* **and** *vwscanw*). **Each of these takes a variadic argument list,** **a** *va\_list* **parameter,** **like that of** *printf***(3).** - **SVr3** *curses* **introduced** **the two obsolete functions,** **and X/Open Curses the others.** **In between,** **SVr4** *curses* **provided for the possibility that an application might include either** *varargs.h* **or** *stdarg.h*. **These represented contrasting approaches to handling variadic** **argument lists.** **The older interface,** *varargs.h*, **used a pointer to** *char* **for variadic functions'** *va\_list* **parameter.** **Later,** **the list acquired its own standard data type,** *va\_list*, **defined in** *stdarg.h*, **empowering the compiler to check the types of a function call's actual** **parameters against the formal ones declared in its prototype.** - **No conforming implementations of X/Open Curses require an application** **to include** *stdarg.h* **before** *curses.h* **because they either have allowed for a special type,** **or,** **like** *ncurses*, **they include** *stdarg.h* **themselves to provide a portable interface.** ## AUTHORS **Zeyd M. Ben-Halim,** **Eric S. Raymond,** **Thomas E. Dickey.** **Based on** *pcurses* **by Pavel Curtis.** ## SEE ALSO **curs\_variables(3X),** **[terminfo(5)](/terminfo/5.md),** **[user\_caps(5)](/user_caps/5.md)**