X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fncurses.3x.html;h=9b061acba0e03839b970fcddd8a32571e3a1a096;hb=HEAD;hp=adc7badbc8f5cfd41cf8e6a2aff30feeaa0d3800;hpb=e6725415d8e5cbb514b8d6056e0700152c540fa0;p=ncurses.git diff --git a/doc/html/man/ncurses.3x.html b/doc/html/man/ncurses.3x.html index adc7badb..af5f6612 100644 --- a/doc/html/man/ncurses.3x.html +++ b/doc/html/man/ncurses.3x.html @@ -28,24 +28,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: ncurses.3x,v 1.195 2024/01/05 21:46:58 tom Exp @ - * X/Open Curses Issue 7 assumes some optimization will be done, but - * does not mandate it in any way. - * See X/Open Curses Issue 4, Version 2, pp. 227-234. - * See X/Open Curses Issue 7, pp. 311-318. - * XXX: What's missing? GBR counts untic(1), and that's all. + * @Id: ncurses.3x,v 1.223 2024/06/08 20:45:43 tom Exp @ -->
-ncurses(3x) Library calls ncurses(3x) @@ -61,159 +56,157 @@
- The ncurses library routines give the user a terminal-independent - method of updating character screens with reasonable optimization. - This implementation is "new curses" (ncurses) and is the approved - replacement for 4.4BSD classic curses, which has been discontinued. - This describes ncurses version 6.4 (patch 20240106). - - The ncurses library emulates the curses library of System V Release 4 - Unix ("SVr4"), and XPG4 (X/Open Portability Guide) curses (also known - as XSI curses). XSI stands for X/Open System Interfaces Extension. - The ncurses library is freely redistributable in source form. - - ncurses man pages employ several sections to clarify matters of usage + The "new curses" library offers the programmer a terminal-independent + means of reading keyboard and mouse input and updating character-cell + terminals 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.5 (patch 20240615). + + ncurses permits control of the terminal screen's contents; abstraction + and subdivision thereof with windows and pads; acquisition of keyboard + and mouse events; control of terminal input and output options; + 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. - o "NOTES" describes matters 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 that will be significant to the programmer + o "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 that will be significant to the programmer but which are not standardized. - o "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 + o "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. o "PORTABILITY" discusses matters (beyond the exercise of extensions) - that should be considered when writing to a curses standard, or to + that should be considered when writing to a curses standard, or for multiple implementations. - o "HISTORY" examines points of detail in ncurses and other curses + o "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 program using these routines must be linked with the -lncurses - option, or (if it has been generated) with the debugging library - -lncurses_g. (Your system integrator may also have installed these - libraries under the names -lcurses and -lcurses_g.) The ncurses_g - library generates trace logs (in a file called "trace" in the current - directory) that describe curses actions. See section "ALTERNATE - CONFIGURATIONS" below. + 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 + generates trace logs (in a file called trace in the current directory) + that describe ncurses actions. See section "ALTERNATE CONFIGURATIONS" + below. - The ncurses package supports: overall screen, window and pad - manipulation; output to windows and pads; reading terminal input; - control over terminal and curses input and output options; environment - query routines; color manipulation; use of soft label keys; terminfo - capabilities; and access to low-level terminal-manipulation routines. +
+ A curses application uses information from the system locale; + setlocale(3) prepares it for curses library calls. -
- The library uses the locale which the calling program has initialized. - That is normally done with setlocale(3): - - setlocale(LC_ALL, ""); + setlocale(LC_ALL, ""); - If the locale is not initialized, the library assumes that characters - are printable as in ISO-8859-1, to work with certain legacy programs. - You should initialize the locale and not rely on specific details of - the library when the locale has not been setup. + 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. - The function initscr or newterm must be called to initialize the - library before any of the other routines that deal with windows and - screens are used. The routine endwin(3x) must be called before - exiting. + initscr(3x) or newterm(3x) must be called to initialize curses before + use of any functions that deal with windows and screens. - To get character-at-a-time input without echoing (most interactive, - screen oriented programs want this), the following sequence should be - used: + To get character-at-a-time input without echoing--most interactive, + screen-oriented programs want this--use the following sequence. - initscr(); cbreak(); noecho(); + initscr(); cbreak(); noecho(); - Most programs would additionally use the sequence: + Most applications would perform further setup as follows. - intrflush(stdscr, FALSE); - keypad(stdscr, TRUE); + noqiflush(); + keypad(stdscr, TRUE); - Before a curses program is run, the tab stops of the terminal should be - set and its initialization strings, if defined, must be output. This - can be done by executing the tput init command after the shell - environment variable TERM has been exported. (The BSD-style tset(1) - utility also performs this function.) See subsection "Tabs and - Initialization" of terminfo(5). + A curses program then often enters an event loop of some sort. Call + endwin(3x) before exiting.
- A curses library abstracts the terminal screen by representing all or - part of it as a WINDOW data structure. A window is a rectangular grid - of character cells, addressed by row and column coordinates (y, x), + A curses library abstracts the terminal screen by representing all or + part of it as a WINDOW data structure. 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, the same - size as the terminal screen, is always available. Create others with + size as the terminal screen, is always available. Create others with newwin(3x). - A curses library does not manage overlapping windows. (See panel(3x) - if you desire this.) 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 output operation will occur. - Among those, the most basic are move(3x) and addch(3x): these place the - cursor and write a character to stdscr, respectively. As a rule, - window-addressing functions feature names prefixed (or infixed, see - below) with "w"; these allow the user to specify a pointer to a WINDOW. - Counterparts not thus prefixed (or infixed) affect stdscr. Because - moving the cursor prior to another operation is so common, curses - generally also provides functions with a "mv" prefix as a convenience. - Thus, the library defines all of addch, waddch, mvaddch, and mvwaddch. - When both prefixes are present, the order of arguments is a WINDOW - pointer first, then a y and x coordinate pair. - - Updating the terminal screen with every curses call can cause - unpleasant flicker or inefficient use of the communications channel to - the device. 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. ncurses optimizes its output by computing a minimal number 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 windows - that are not constrained to the size of the terminal screen and whose - contents need not be completely displayed. See curs_pad(3x). - - In addition to drawing characters on the screen, rendering attributes - and colors may be supported, causing the characters to show up in such - modes as underlined, in reverse video, or in color on terminals that - support such display enhancements. See curs_attr(3x). - - curses predefines constants for a small set of line-drawing and other - graphics corresponding to the DEC Alternate Character Set (ACS), a - feature of VT100 and other terminals. See waddch(3x) and wadd_wch(3x). - - curses is implemented using the operating system's terminal driver; - keystroke events are received not as scan codes but as byte sequences. - Graphical keycaps (alphanumeric and punctuation keys, and the space) - appear as-is. Everything else, including the tab, enter/return, - keypad, arrow, and function keys, appears as a control character or a - multibyte escape sequence. curses translates these into unique key - codes. See getch(3x). - - -
- The selection of an approprate 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) - may assist with troubleshooting exotic situations. + 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_attr(3x). + + curses predefines constants for 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. Graphical + keycaps (alphanumeric and punctuation keys, and the space) appear as- + is. Everything else, including the tab, enter/return, keypad, arrow, + and function keys, appears 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. + + +
+ 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) may assist with troubleshooting exotic + situations. + + If you change the terminal type, export the shell's TERM variable, then + run tset(1) or the "tput init" command. See subsection "Tabs and + Initialization" of terminfo(5). If the environment variables LINES and COLUMNS are set, or if the curses program is executing in a graphical windowing environment, the @@ -222,106 +215,124 @@ 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 experimental type - descriptions or when write permission to /usr/share/terminfo is not - available. + identifies. TERMINFO is useful for developing type descriptions or + when write permission to /usr/share/terminfo is not available. See section "ENVIRONMENT" below.
- Many curses functions have two or more versions. Those prefixed with - "w" require a window argument. Four functions prefixed with "p" - require a pad argument. Those without a prefix generally operate on - stdscr. + 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. - In function synopses, ncurses man pages apply the following names to - parameters. + In function synopses, ncurses man pages apply the following names to + parameters. We introduce the character types in the next subsection. - bf bool (TRUE or FALSE) - win pointer to WINDOW - pad pointer to WINDOW that is a pad + 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
- This manual page describes functions that appear in any configuration - of the library. There are two common configurations; see section - "ALTERNATE CONFIGURATIONS" below. + This man page primarily surveys functions that appear in any + configuration of the library. There are two common configurations; 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 in a chtype datum, which is often an alias of int. - - Attributes alone (with no corresponding character) can be - stored in variables of chtype or attr_t type. In either - case, they are represented as an integral bit mask. - - Each cell of a WINDOW is stored as a chtype. - - ncursesw is the library in its "wide" configuration, which handles + eight-bit characters. It stores a character combined with + attributes and a color pair 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 selection (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. + + Each cell of a WINDOW is stored 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 adds about one third more - calls using additional data types that can store such - multibyte characters. - - cchar_t corresponds to the non-wide configuration's chtype. - It always a structure type, because it stores more - data than fits into an integral type. 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). Attributes and - color data are stored in separate fields of the - structure, not combined as in chtype. - - Each cell of a WINDOW is stored as a cchar_t. - - The setcchar(3x) and getcchar(3x) functions store and - retrieve the data from a cchar_t structure. 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. - - The wide library 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. + 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. (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: in the window background management functions, + configuration: the window background management function "bkgd" becomes "bkgrnd"; the window border-drawing and - -clearing functions are suffixed with "_set". + -clearing functions are suffixed with "_set"; and character + attribute manipulation functions like "attron" become + "attr_on". + + cchar_t corresponds to the non-wide 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 selection are stored in + separate fields of the structure, not combined into + an integer as in chtype. + + Each cell of a WINDOW is stored 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.
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 + 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) @@ -369,6 +380,7 @@ 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) @@ -388,13 +400,13 @@ 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) @@ -434,6 +446,7 @@ 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) @@ -455,7 +468,6 @@ 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)* @@ -500,10 +512,11 @@ 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_terminfo(3x) + mvcur curs_kernel(3x) mvdelch curs_delch(3x) mvderwin curs_window(3x) mvget_wch curs_get_wch(3x) @@ -522,7 +535,6 @@ 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) @@ -566,6 +578,7 @@ 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) @@ -589,7 +602,6 @@ 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) @@ -622,6 +634,8 @@ 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) @@ -630,6 +644,7 @@ 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) @@ -656,7 +671,6 @@ tgetent curs_termcap(3x) tgetflag curs_termcap(3x) tgetnum curs_termcap(3x) - tgetstr curs_termcap(3x) tgoto curs_termcap(3x) tigetflag curs_terminfo(3x) @@ -682,7 +696,9 @@ 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) @@ -694,6 +710,7 @@ 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) @@ -723,7 +740,6 @@ 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) @@ -760,6 +776,7 @@ 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) @@ -779,247 +796,240 @@ wvline curs_border(3x) wvline_set curs_border_set(3x) - Depending on the configuration, additional sets of functions may be - available: - - curs_memleaks(3x) - curses memory-leak checking - - curs_sp_funcs(3x) - curses screen-pointer extension + ncurses's screen-pointer extension adds additional functions + corresponding to many of the above, each with an "_sp" suffix; see + curs_sp_funcs(3x). - curs_threads(3x) - curses thread support - - curs_trace(3x) - curses debugging routines + The availability of some extensions is configurable when ncurses is + compiled; see sections "ALTERNATE CONFIGURATIONS" and "EXTENSIONS" + below.
- Unless otherwise noted, functions that return an integer return OK on - success and ERR on failure. Functions that return pointers return NULL - on failure. Typically, ncurses treats a null pointer passed as a - function parameter as a failure. - - Functions with a "mv" prefix first perform cursor movement using wmove - and fail if the position is outside the window, or (for "mvw" - functions) if the WINDOW pointer is null. + 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 NULL 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.
- The following environment symbols are useful for customizing the - runtime behavior of the ncurses library. The most important ones have - been already discussed in detail. + 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). -
- When set, change the command_character (cmdch) capability value of - loaded terminfo entries to the value of this variable. Very few term- - info entries provide this feature. +
+ The debugging library checks this variable when the application has + redirected output to a file. Its integral value is used for the baud + rate. 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 baud rate. - Because this name is also used in development environments to represent - the C compiler's name, ncurses ignores it if it does not happen to be a - single character. +
+ When set, the command_character (cmdch) capability value of loaded + terminfo entries changes to the value of this variable. Very few term- + info entries provide this feature. -
- The debugging library checks this environment variable when the - application has redirected output to a file. The variable's numeric - value is used for the baudrate. If no value is found, ncurses uses - 9600. This allows testers to construct repeatable test-cases that take - into account costs that depend on baudrate. + 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.
- Specify the width of the screen in characters. Applications running in - a windowing environment usually are able to obtain the width of the - window in which they are executing. If neither the COLUMNS value nor - the terminal's screen size is available, ncurses uses the size which - may be specified in the terminfo database (i.e., the cols capability). - - It is important that your application use a correct size for the - screen. This is not always possible because your application may be - running on a host which does not honor NAWS (Negotiations About Window - Size), or because you are temporarily running as another user. - However, setting COLUMNS and/or LINES overrides the library's use of - the screen size obtained from the operating system. - - Either COLUMNS or LINES symbols may be specified independently. This - is mainly useful to circumvent legacy misfeatures of terminal - descriptions, e.g., xterm which commonly specifies a 65 line screen. - For best results, lines and cols should not be specified in a terminal - description for terminals which are run as emulations. - - Use the use_env function to disable all use of external environment - (but not including system calls) to determine the screen size. Use the - use_tioctl function to update COLUMNS or LINES to match the screen size - obtained from system calls or the terminal database. + This variable specifies the width of the screen in characters. + Applications running in a windowing environment usually are able to + obtain the width of the window in which they are executing. 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. + ncurses enforces an upper limit of 512 on each when reading the value. + 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.
- Specifies the total time, in milliseconds, for which ncurses will await - a character sequence, e.g., a function key. The default value, 1000 - milliseconds, is enough for most uses. However, it is made a variable - to accommodate unusual applications. + 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 slow hosts, e.g., running on a network. If the host cannot - read characters rapidly enough, it will have the same effect as if the - terminal did not send characters rapidly enough. The library will - still see a timeout. + 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. - Note that xterm mouse events are built up from character sequences - received from the xterm. If your application makes heavy use of - multiple-clicking, you may wish to lengthen this default value because - the timeout applies to the composed multi-click event as well as the - individual clicks. + 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. - In addition to the environment variable, this implementation provides a - global variable with the same name. 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. + 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, a + program must disambiguate escape sequences itself. -
- Tells ncurses where your home directory is. That is where it may read - and write auxiliary terminal descriptions: - $HOME/.termcap - $HOME/.terminfo +
+ ncurses may read and write auxiliary terminal descriptions in .termcap + and .terminfo files in the user's home directory.
- Like COLUMNS, specify the height of the screen in characters. See - COLUMNS for a detailed description. + 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.
- This applies only to the OS/2 EMX port. It specifies the order of - buttons on the mouse. OS/2 numbers a 3-button mouse inconsistently - from other platforms: - - 1 = left - 2 = right - 3 = middle. - - This variable lets you customize the mouse. The variable must be three - numeric digits 1-3 in any order, e.g., 123 or 321. If it is not - specified, ncurses uses 132. + (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".
- Override the compiled-in assumption that the terminal's default colors - are white-on-black (see default_colors(3x)). You may set the - foreground and background color values with this environment variable - by proving a 2-element list: foreground,background. For example, to - tell ncurses to not assume anything about the colors, set this to - "-1,-1". To make it green-on-black, set it to "2,0". Any positive - value from zero to the terminfo max_colors value is allowed. + 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, use "2,0". ncurses accepts integral values from -1 up to the + value of the terminfo max_colors (colors) capability. -
- This applies only to the MinGW port of ncurses. - The Console2 program's handling of the Microsoft Console API call - CreateConsoleScreenBuffer is defective. Applications which use this - 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. +
+ (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.
- This applies only to ncurses configured to use the GPM interface. - - If present, the environment variable is a list of one or more terminal - names against which the TERM environment variable is matched. Setting - it to an empty value disables the GPM interface; using the built-in - support for xterm, etc. - - If the environment variable is absent, ncurses will attempt to open GPM - if TERM contains "linux". + (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 may use tabs as part of cursor movement optimization. In some - cases, your terminal driver may not handle these 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 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.
- Some terminals use a magic-cookie feature which requires special - handling to make highlighting and other video attributes display - properly. You can suppress the highlighting entirely for these - terminals by setting this environment variable to any value. + Many terminals store video attributes as a property of a character + cell, as curses does. Historically, some recorded changes in video + attributes as data that logically occupies character cells on the + display, switching attributes on or off, similarly to tags in a markup + language; these are termed "magic cookies", and must be subsequently + overprinted. 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.
- Most of the terminal descriptions in the terminfo database are written - for real "hardware" terminals. Many people use terminal emulators - which run in a windowing environment and use curses-based applications. - Terminal emulators can duplicate all of the important aspects of a - hardware terminal, but they do not have the same limitations. The - chief limitation of a hardware terminal from the standpoint of your - application is the management of dataflow, i.e., timing. Unless a - hardware terminal is interfaced into a terminal concentrator (which - does flow control), it (or your application) must manage dataflow, - preventing overruns. The cheapest solution (no hardware cost) is for - your program to do this by pausing after operations that the terminal - does slowly, such as clearing the display. - - As a result, many terminal descriptions (including the vt100) have - delay times embedded. You may wish to use these descriptions, but not - want to pay the performance penalty. - - Set the NCURSES_NO_PADDING environment variable to disable all but - mandatory padding. Mandatory padding is used as a part of special - control sequences such as flash. + 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 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).
- This setting is obsolete. Before changes - - o started with 5.9 patch 20120825 and - - o continued though 5.9 patch 20130126 - - ncurses enabled buffered output during terminal initialization. This - was done (as in SVr4 curses) for performance reasons. For testing - purposes, both of ncurses and certain applications, this feature was - made optional. Setting the NCURSES_NO_SETBUF variable disabled output - buffering, leaving the output in the original (usually line buffered) - mode. - - In the current implementation, ncurses performs its own buffering and - does not require this workaround. It does not modify the buffering of - the standard output. - - The reason for the change was to make the behavior for interrupts and - other signals more robust. One drawback is that certain - nonconventional programs would mix ordinary stdio(3) calls with ncurses - calls and (usually) work. This is no longer possible since ncurses is - not using the buffered standard output but its own output (to the same - file descriptor). As a special case, the low-level calls such as putp - still use the standard output. But high-level curses calls do not. + (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 signal handling, as for interrupts, 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.
- During initialization, the ncurses library checks for special cases - where VT100 line-drawing (and the corresponding alternate character set - capabilities) described in the terminfo are known to be missing. - Specifically, when running in a UTF-8 locale, the Linux console - emulator and the GNU screen program ignore these. ncurses checks the - TERM environment variable for these. For other special cases, you - should set this environment variable. Doing this tells ncurses to use - Unicode values which correspond to the VT100 line-drawing glyphs. That - works for the special cases cited, and is likely to work for terminal - emulators. - - When setting this variable, you should set it to a nonzero value. - Setting it to zero (or to a nonnumber) disables the special check for - "linux" and "screen". - - As an alternative to the environment variable, ncurses checks for an - extended terminfo capability U8. This is a numeric capability which - can be compiled using tic -x. For example + 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. @@ -1030,170 +1040,140 @@ xterm-utf8|xterm relying on UTF-8 line-graphics, U8#1, use=xterm, - The name "U8" is chosen to be two characters, to permit it to be used - by applications that use ncurses' termcap interface. + The two-character name "U8" was chosen to permit its use via ncurses's + termcap interface.
- During initialization, the ncurses debugging library checks the - NCURSES_TRACE environment variable. If it is defined, to a numeric - value, ncurses calls the trace function, using that value as the - argument. - - The argument values, which are defined in curses.h, provide several - types of information. When running with traces enabled, your - application will write the file trace to the current directory. - - See curs_trace(3x) for more information. + 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.
- Denotes your terminal type. Each terminal type is distinct, though - many are similar. - - TERM is commonly set by terminal emulators to help applications find a - workable terminal description. Some of those choose a popular - approximation, e.g., "ansi", "vt100", "xterm" rather than an exact fit. - Not infrequently, your application will have problems with that - approach, e.g., incorrect function-key definitions. - - If you set TERM in your environment, it has no effect on the operation - of the terminal emulator. It only affects the way applications work - within the terminal. Likewise, as a general rule (xterm(1) being a - rare exception), terminal emulators which allow you to specify TERM as - a parameter or configuration value do not change their behavior to - match that setting. + 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.
- If the ncurses library has been configured with termcap support, - ncurses will check for a terminal's description in termcap form if it - is not available in the terminfo database. - - The TERMCAP environment variable contains either a terminal description - (with newlines stripped out), or a file name telling where the - information denoted by the TERM environment variable exists. In either - case, setting it directs ncurses to ignore the usual place for this - information, e.g., /etc/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.
- ncurses can be configured to read from multiple terminal databases. - The TERMINFO variable overrides the location for the default terminal - database. Terminal descriptions (in terminal format) are stored in - terminal databases: - - o Normally these are stored in a directory tree, using subdirectories - named by the first letter of the terminal names therein. - - This is the scheme used in System V, which legacy Unix systems use, - and the TERMINFO variable is used by curses applications on those - systems to override the default location of the terminal database. - - o If ncurses is built to use hashed databases, then each entry in - this list may be the path of a hashed database file, e.g., - - /usr/share/terminfo.db + ncurses can be configured to read terminal type description databases + in various locations using different formats. This variable overrides + the default location. - rather than + o Descriptions in terminfo format are normally stored in a directory + tree using subdirectories named by the common first letters of the + terminal types named therein. This is the scheme used in System V. - /usr/share/terminfo/ + o 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, reading it directly rather than - using the terminfo library calls. + 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 rather than using the terminfo + API. - o If ncurses is built with a support for reading termcap files - directly, then an entry in this list may be the path of a termcap - file. + o If ncurses is configured with termcap support, this variable may + contain the location of a termcap file. - o If the TERMINFO variable begins with "hex:" or "b64:", ncurses uses - the remainder of that variable as a compiled terminal description. - You might produce the base64 format using infocmp(1m): + o 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 + TERMINFO=$(infocmp -0 -Q2 -q) + export TERMINFO - The compiled description is used if it corresponds to the terminal - identified by the TERM variable. + The compiled description is used only if it corresponds to the + terminal type identified by TERM. - Setting TERMINFO is the simplest, but not the only way to set location - of the default terminal database. The complete list of database - locations in order follows: + Setting TERMINFO is the simplest, but not the only, way to direct + ncurses to a terminal database. The search path is as follows. - o the last terminal database to which ncurses wrote, if any, is - searched first + o the last terminal database to which the running ncurses application + wrote, if any - o the location specified by the TERMINFO environment variable + o the location specified by the TERMINFO environment variable - o $HOME/.terminfo + o $HOME/.terminfo - o locations listed in the TERMINFO_DIRS environment variable + o locations listed in the TERMINFO_DIRS environment variable - o one or more locations whose names are configured and compiled - into the ncurses library, i.e., + o location(s) configured and compiled into ncurses - o /usr/share/terminfo (corresponding to the TERMINFO_DIRS - variable) - - o /usr/share/terminfo (corresponding to the TERMINFO variable) + o /usr/share/terminfo
- Specifies a list of locations to search for terminal descriptions. - Each location in the list is a terminal database as described in the - section on the TERMINFO variable. The list is separated by colons - (i.e., ":") on Unix, semicolons on OS/2 EMX. - - There is no corresponding feature in System V terminfo; it is an - extension developed for ncurses. + 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.
- If TERMCAP does not hold a file name then ncurses checks the TERMPATH - environment variable. This is a list of filenames separated by spaces - or colons (i.e., ":") on Unix, semicolons on OS/2 EMX. - - If the TERMPATH environment variable is not set, ncurses looks in the - files - - /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap, - - in that order. + 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. - The library may be configured to disregard the following variables when - the current user is the superuser (root), or if the application uses - setuid or setgid permissions: - - $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME. + 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.
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. + particular significance to the application developer employing ncurses. - --disable-overwrite - The standard include for ncurses is as noted in SYNOPSIS: + --disable-overwrite + The standard C preprocessor inclusion for the curses library is as + follows. #include <curses.h> - This option is used to avoid filename conflicts when ncurses is - not the main implementation of curses of the computer. If ncurses - is installed disabling overwrite, it puts its headers in a - subdirectory, e.g., + This option is used to avoid file name conflicts between ncurses + and an existing curses installation on the system. If ncurses is + installed disabling overwrite, it puts its header files in a + subdirectory. Here is an example. #include <ncurses/curses.h> - It also omits a symbolic link which would allow you to use - -lcurses to build executables. + 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 - The configure script renames the library and (if the - --disable-overwrite option is used) puts the header files in a - different subdirectory. All of the library names have a "w" + --enable-widec + The configure script renames the library and (if the + --disable-overwrite option is used) puts the header files in a + different subdirectory. All of the library names have a "w" appended to them, i.e., instead of -lncurses @@ -1202,65 +1182,62 @@ -lncursesw - You must also enable the wide-character features in the header - file when compiling for the wide-character library to use the - extended (wide-character) functions. The symbol which enables - these features has changed since XSI Curses, Issue 4: + You must also enable the wide-character features in the header + file when compiling for the wide-character library to use the + extended (wide-character) functions. The symbol which enables + these features has changed since X/Open Curses, Issue 4: - o Originally, the wide-character feature required the symbol + o Originally, the wide-character feature required the symbol _XOPEN_SOURCE_EXTENDED but that was only valid for XPG4 (1996). - o Later, that was deemed conflicting with _XOPEN_SOURCE defined + o Later, that was deemed conflicting with _XOPEN_SOURCE defined to 500. - o As of mid-2018, none of the features in this implementation - require a _XOPEN_SOURCE feature greater than 600. However, + o As of mid-2018, none of the features in this implementation + require a _XOPEN_SOURCE feature greater than 600. However, X/Open Curses, Issue 7 (2009) recommends defining it to 700. - o Alternatively, you can enable the feature by defining - NCURSES_WIDECHAR with the caveat that some other header file - than curses.h may require a specific value for _XOPEN_SOURCE + o Alternatively, you can enable the feature by defining + NCURSES_WIDECHAR with the caveat that some other header file + 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 + 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 WINDOWs. If the headers are installed allowing overwrite, the wide- - character library's headers should be installed last, to allow + character library's headers should be installed last, to allow applications to be built using either library from the same set of headers. - --with-pthread - The configure script renames the library. All of the library - names have a "t" appended to them (before any "w" added by + --with-pthread + The configure script renames the library. All of the library + names have a "t" appended to them (before any "w" added by --enable-widec). The global variables such as LINES are replaced by macros to allow read-only access. At the same time, setter-functions are provided - to set these values. Some applications (very few) may require + to set these values. Some applications (very few) may require changes to work with this convention. - --with-shared - - --with-normal - - --with-debug - - --with-profile - The shared and normal (static) library names differ by their - suffixes, e.g., libncurses.so and libncurses.a. The debug and - profiling libraries add a "_g" and a "_p" to the root names + --with-shared + --with-normal + --with-debug + --with-profile + The shared and normal (static) library names differ by their + suffixes, e.g., libncurses.so and libncurses.a. The debug and + profiling libraries add a "_g" and a "_p" to the root names respectively, e.g., libncurses_g.a and libncurses_p.a. - --with-termlib - Low-level functions which do not depend upon whether the library + --with-termlib + Low-level functions which do not depend upon whether the library supports wide-characters, are provided in the tinfo library. - By doing this, it is possible to share the tinfo library between - wide/normal configurations as well as reduce the size of the + By doing this, it is possible to share the tinfo library between + wide/normal configurations as well as reduce the size of the library when only low-level functions are needed. Those functions are described in these pages: @@ -1279,9 +1256,9 @@ o curs_util(3x) - miscellaneous curses utility routines - --with-trace - The trace function normally resides in the debug library, but it - is sometimes useful to configure this in the shared library. + --with-trace + The trace function normally resides in the debug library, but it + is sometimes useful to configure this in the shared library. Configure scripts should check for the function's existence rather than assuming it is always in the debug library. @@ -1295,87 +1272,94 @@
- X/Open Curses permits most functions it specifies to be made available + X/Open Curses permits most functions it specifies to be made available as macros as well. ncurses does so o for functions that return values via their parameters, o to support obsolete features, - o to reuse functions (for example, those that move the cursor before + o to reuse functions (for example, those that move the cursor before another operation), and - o a few special cases. + o 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. + 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 + See subsection "Header Files" below regarding symbols exposed by inclusion of curses.h.
- ncurses enables an application to capture mouse events on certain - terminals, including xterm; see curs_mouse(3x). + ncurses enables an application to capture mouse events on 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 + 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 sequences at runtime; see define_key(3x), - key_defined(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, + 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 choose to hide the internal details of - WINDOW structures, instead using accessor functions such as - is_scrollok(3x). + An ncurses application can eschew knowledge of WINDOW structure + internals, instead using accessor functions such as is_scrollok(3x). - ncurses enables an application to direct application output to a - printer attached to the terminal device; see curs_print(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. - Some extensions are only available if ncurses is compiled to support - them; see section "ALTERNATE CONFIGURATIONS" above. + ncurses permits modification of unctrl(3x)'s behavior; see + use_legacy_coding(3x). - o Rudimentary support for multi-threaded applications may be - available; see curs_threads(3x). + Rudimentary support for multi-threaded applications may be available; + see curs_threads(3x). - o Functions that ease the management of multiple screens can be - exposed; see curs_sp_funcs(3x). + Functions that ease the management of multiple screens can be exposed; + see curs_sp_funcs(3x). - o The compiler option -DUSE_GETCAP causes the library to fall back to - reading /etc/termcap if the terminal setup code cannot find a term- - info 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. + 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). - PDCurses and NetBSD curses incorporate some ncurses extensions. + 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 term- + info 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.
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 nearly all its enhanced features. + 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. @@ -1385,113 +1369,116 @@ In many cases, X/Open Curses is vague about error conditions, omitting some of the SVr4 documentation. - Unlike other implementations, this one checks parameters such as - pointers to WINDOW structures to ensure they are not null. The main - reason for providing this behavior is 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 were detected. - Relying on this (or some other) extension will adversely affect the - portability of curses applications. + 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.
- In historic curses versions, delays embedded in the capabilities cr, - ind, cub1, ff and tab activated corresponding delay bits in the Unix - tty driver. In this implementation, all padding is done by sending NUL - bytes. This method is slightly more expensive, but narrows the - interface to the Unix kernel significantly and increases the package's - portability correspondingly. + 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.
- The header file curses.h itself includes the header files stdio.h and + The header file curses.h itself includes the header files stdio.h and unctrl.h. - X/Open Curses has more to say, but does not finish the story: + 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>. + The inclusion of curses.h may make visible all symbols from the + headers stdio.h, term.h, termios.h, and wchar.h. - Here is a more complete story: + but does not finish the story. A more complete account follows. - o Starting with BSD curses, all implementations have included - <stdio.h>. + o The first curses, in 4BSD, provided a curses.h file. - BSD curses included <curses.h> and <unctrl.h> from an internal - header file curses.ext ("ext" abbreviated "externs"). + BSD curses code included curses.h and unctrl.h from an internal + header file curses.ext, where "ext" abbreviated "externs". - BSD curses used <stdio.h> internally (for printw and scanw), but - nothing in <curses.h> itself relied upon <stdio.h>. + 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. - o SVr2 curses added newterm(3x), which relies upon <stdio.h>. That - is, the function prototype uses FILE. + o 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>. + SVr4 curses added putwin and getwin, which also use stdio.h. - X/Open Curses documents all three of these functions. + 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 including <curses.h>. Both document - curses showing <curses.h> as the only required header. + 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> will always include <stdio.h>. + As a result, standard curses.h always includes stdio.h. - o X/Open Curses is inconsistent with respect to SVr4 regarding - <unctrl.h>. + o 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> (like SVr4). + As noted in curs_util(3x), ncurses includes unctrl.h from curses.h + (as SVr4 does). - o X/Open's comments about <term.h> and <termios.h> may refer to HP-UX - and AIX: + o 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. + 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. + AIX curses includes term.h and termios.h. Again, ncurses and + Solaris curses do not. - o X/Open says that <curses.h> may include <term.h>, but there is no - requirement that it do that. + o 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 headers in the same module. Very - old versions of AIX curses required including <curses.h> before - including <term.h>. + Some programs use functions declared in both curses.h and term.h, + and must include both header files in the same module. Very old + versions of AIX curses required inclusion of curses.h before + term.h. - Because ncurses header files include the headers needed to define - datatypes used in the headers, ncurses header files can be included - in any order. But for portability, you should include <curses.h> - before <term.h>. + 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. But for portability, you + should include curses.h before term.h. - o X/Open Curses says "may make visible" because including a header - file does not necessarily make all symbols in it visible (there are - ifdef's to consider). + o 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, in ncurses <wchar.h> may be included if the proper - symbol is defined, and if ncurses is configured for wide-character - support. If the header is included, its symbols may be made - visible. That depends on the value used for _XOPEN_SOURCE feature - test macro. + 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. - o X/Open Curses documents one required header, in a special case: - <stdarg.h> before <curses.h> to prototype the vw_printw and - vw_scanw functions (as well as the obsolete the vwprintw and - vwscanw functions). Each of those uses a va_list parameter. + o 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). - The two obsolete functions were introduced in SVr3. The other - functions were introduced in X/Open Curses. In between, SVr4 - curses provided for the possibility that an application might - include either <varargs.h> or <stdarg.h>. Initially, that was done - by using void* for the va_list parameter. Later, a special type - (defined in <stdio.h>) was introduced, to allow for compiler type- - checking. That special type is always available, because <stdio.h> - is always included by <curses.h>. + 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. - None of the X/Open Curses implementations require an application to - include <stdarg.h> before <curses.h> because they either have - allowed for a special type, or (like ncurses) include <stdarg.h> - directly to provide a portable interface. + 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.
@@ -1504,7 +1491,7 @@ -ncurses 6.4 2024-01-05 ncurses(3x) +ncurses 6.5 2024-06-08 ncurses(3x)