diff options
Diffstat (limited to 'doc/html/man/ncurses.3x.html')
| -rw-r--r-- | doc/html/man/ncurses.3x.html | 1628 |
1 files changed, 814 insertions, 814 deletions
diff --git a/doc/html/man/ncurses.3x.html b/doc/html/man/ncurses.3x.html index 64cc934b441d..9b061acba0e0 100644 --- a/doc/html/man/ncurses.3x.html +++ b/doc/html/man/ncurses.3x.html @@ -1,7 +1,7 @@ -<!-- +<!-- * t **************************************************************************** - * Copyright 2018-2020,2021 Thomas E. Dickey * + * Copyright 2018-2023,2024 Thomas E. Dickey * * Copyright 1998-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,27 +28,27 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: ncurses.3x,v 1.152 2021/01/09 11:07:55 tom Exp @ + * @Id: ncurses.3x,v 1.214 2024/04/27 17:55:43 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>ncurses 3x</TITLE> +<TITLE>ncurses 3x 2024-04-27 ncurses 6.5 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + </HEAD> <BODY> -<H1 class="no-header">ncurses 3x</H1> +<H1 class="no-header">ncurses 3x 2024-04-27 ncurses 6.5 Library calls</H1> <PRE> -<STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> +<STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> Library calls <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>ncurses</STRONG> - CRT screen handling and optimization package + <STRONG>ncurses</STRONG> - character-cell terminal interface with optimized output </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> @@ -56,237 +56,275 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - The <STRONG>ncurses</STRONG> 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 <STRONG>ncurses</STRONG> version 6.2 (patch 20210109). - - The <STRONG>ncurses</STRONG> library emulates the curses library of System V Release 4 - UNIX, and XPG4 (X/Open Portability Guide) curses (also known as XSI - curses). XSI stands for X/Open System Interfaces Extension. The - <STRONG>ncurses</STRONG> library is freely redistributable in source form. Differences - from the SVr4 curses are summarized under the <STRONG>EXTENSIONS</STRONG> and - <STRONG>PORTABILITY</STRONG> sections below and described in detail in the respective - <STRONG>EXTENSIONS</STRONG>, <STRONG>PORTABILITY</STRONG> and <STRONG>BUGS</STRONG> sections of individual man pages. - - The <STRONG>ncurses</STRONG> library also provides many useful extensions, i.e., - features which cannot be implemented by a simple add-on library but - which require access to the internals of the library. - - A program using these routines must be linked with the <STRONG>-lncurses</STRONG> - option, or (if it has been generated) with the debugging library - <STRONG>-lncurses_g</STRONG>. (Your system integrator may also have installed these - libraries under the names <STRONG>-lcurses</STRONG> and <STRONG>-lcurses_g</STRONG>.) The ncurses_g - library generates trace logs (in a file called 'trace' in the current - directory) that describe curses actions. See also the section on - <STRONG>ALTERNATE</STRONG> <STRONG>CONFIGURATIONS</STRONG>. - - The <STRONG>ncurses</STRONG> package supports: overall screen, window and pad - manipulation; output to windows and pads; reading terminal input; - control over terminal and <STRONG>curses</STRONG> input and output options; environment - query routines; color manipulation; use of soft label keys; terminfo - capabilities; and access to low-level terminal-manipulation routines. - - -</PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE> - The library uses the locale which the calling program has initialized. - That is normally done with <STRONG>setlocale</STRONG>: - - <STRONG>setlocale(LC_ALL,</STRONG> <STRONG>"");</STRONG> - - 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. - - The function <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> must be called to initialize the - library before any of the other routines that deal with windows and - screens are used. The routine <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG> must be called before - exiting. - - To get character-at-a-time input without echoing (most interactive, - screen oriented programs want this), the following sequence should be - used: - - <STRONG>initscr();</STRONG> <STRONG>cbreak();</STRONG> <STRONG>noecho();</STRONG> - - Most programs would additionally use the sequence: - - <STRONG>intrflush(stdscr,</STRONG> <STRONG>FALSE);</STRONG> - <STRONG>keypad(stdscr,</STRONG> <STRONG>TRUE);</STRONG> - - Before a <STRONG>curses</STRONG> 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 <STRONG>tput</STRONG> <STRONG>init</STRONG> command after the shell - environment variable <STRONG>TERM</STRONG> has been exported. <STRONG>tset(1)</STRONG> is usually - responsible for doing this. [See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for further details.] - - -</PRE><H3><a name="h3-Datatypes">Datatypes</a></H3><PRE> - The <STRONG>ncurses</STRONG> library permits manipulation of data structures, called - <EM>windows</EM>, which can be thought of as two-dimensional arrays of - characters representing all or part of a CRT screen. A default window - called <STRONG>stdscr</STRONG>, which is the size of the terminal screen, is supplied. - Others may be created with <STRONG>newwin</STRONG>. - - Note that <STRONG>curses</STRONG> does not handle overlapping windows, that's done by - the <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG> library. This means that you can either use <STRONG>stdscr</STRONG> or - divide the screen into tiled windows and not using <STRONG>stdscr</STRONG> at all. - Mixing the two will result in unpredictable, and undesired, effects. - - Windows are referred to by variables declared as <STRONG>WINDOW</STRONG> <STRONG>*</STRONG>. These data - structures are manipulated with routines described here and elsewhere - in the <STRONG>ncurses</STRONG> manual pages. Among those, the most basic routines are - <STRONG>move</STRONG> and <STRONG>addch</STRONG>. More general versions of these routines are included - with names beginning with <STRONG>w</STRONG>, allowing the user to specify a window. - The routines not beginning with <STRONG>w</STRONG> affect <STRONG>stdscr</STRONG>. - - After using routines to manipulate a window, <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> is called, - telling <STRONG>curses</STRONG> to make the user's CRT screen look like <STRONG>stdscr</STRONG>. The - characters in a window are actually of type <STRONG>chtype</STRONG>, (character and - attribute data) so that other information about the character may also - be stored with each character. + 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. <EM>ncurses</EM> + replaces the <EM>curses</EM> libraries from System V Release 4 Unix ("SVr4") and + 4.4BSD Unix, the development of which ceased in the 1990s. This + document describes <EM>ncurses</EM> version 6.5 (patch 20240427). + + <EM>ncurses</EM> permits control of the terminal screen's contents; abstraction + and subdivision thereof with <EM>windows</EM> and <EM>pads</EM>; the reading of terminal + input; control of terminal input and output options; environment query + routines; color manipulation; the definition and use of <EM>soft</EM> <EM>label</EM> + keys; <EM>terminfo</EM> capability access; a <EM>termcap</EM> compatibility interface; + and an abstraction of the system's API for manipulating the terminal + (such as <STRONG>termios(3)</STRONG>). + + <EM>ncurses</EM> implements the standard interface described by X/Open Curses + Issue 7. In many behavioral details not standardized by X/Open, + <EM>ncurses</EM> emulates the <EM>curses</EM> library of SVr4 and provides numerous + useful extensions. + + <EM>ncurses</EM> man pages employ several sections to clarify matters of usage + and interoperability with other <EM>curses</EM> implementations. + + <STRONG>o</STRONG> "NOTES" describes issues and caveats of which any user of the + <EM>ncurses</EM> 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. + + <STRONG>o</STRONG> "EXTENSIONS" presents <EM>ncurses</EM> innovations beyond the X/Open Curses + standard and/or the SVr4 <EM>curses</EM> implementation. They are termed + <EM>extensions</EM> to indicate that they cannot be implemented solely by + using the library API, but require access to the library's internal + state. + + <STRONG>o</STRONG> "PORTABILITY" discusses matters (beyond the exercise of extensions) + that should be considered when writing to a <EM>curses</EM> standard, or for + multiple implementations. + + <STRONG>o</STRONG> "HISTORY" examines points of detail in <EM>ncurses</EM> and other <EM>curses</EM> + 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 <EM>curses</EM> application must be linked with the library; use the <STRONG>-lncurses</STRONG> + option to your compiler or linker. A debugging version of the library + may be available; if so, link with it using <STRONG>-lncurses_g</STRONG>. (Your system + integrator may have installed these libraries such that you can use the + options <STRONG>-lcurses</STRONG> and <STRONG>-lcurses_g</STRONG>, respectively.) The <EM>ncurses</EM><STRONG>_</STRONG><EM>g</EM> library + generates trace logs (in a file called <EM>trace</EM> in the current directory) + that describe <EM>ncurses</EM> actions. See section "ALTERNATE CONFIGURATIONS" + below. + + +</PRE><H3><a name="h3-Application-Structure">Application Structure</a></H3><PRE> + A <EM>curses</EM> application uses information from the system locale; + <STRONG>setlocale(3)</STRONG> prepares it for <EM>curses</EM> 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. + + <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> must be called to initialize <EM>curses</EM> 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--use the following sequence. + + initscr(); cbreak(); noecho(); + + Most applications perform further setup as follows. + + intrflush(stdscr, FALSE); + keypad(stdscr, TRUE); + + A <EM>curses</EM> program then often enters an event loop of some sort. Call + <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG> before exiting. + + +</PRE><H3><a name="h3-Overview">Overview</a></H3><PRE> + A <EM>curses</EM> library abstracts the terminal screen by representing all or + part of it as a <EM>WINDOW</EM> data structure. A <EM>window</EM> is a rectangular grid + of character cells, addressed by row and column coordinates (<EM>y</EM>, <EM>x</EM>), + with the upper left corner as (0, 0). A window called <STRONG>stdscr</STRONG>, the same + size as the terminal screen, is always available. Create others with + <STRONG><A HREF="curs_window.3x.html">newwin(3x)</A></STRONG>. + + A <EM>curses</EM> library does not manage overlapping windows (but see below). + You can either use <STRONG>stdscr</STRONG> to manage one screen-filling window, or tile + the screen into non-overlapping windows and not use <STRONG>stdscr</STRONG> at all. + Mixing the two approaches will result in unpredictable and undesired + effects. + + Functions permit manipulation of a window and the <EM>cursor</EM> identifying + the cell within it at which the next output operation will occur. + Among those, the most basic are <STRONG><A HREF="curs_move.3x.html">move(3x)</A></STRONG> and <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>: these place the + cursor and write a character to <STRONG>stdscr</STRONG>, respectively. + + Frequent changes to the terminal screen can cause unpleasant flicker or + inefficient use of the communication channel to the device, so the + library does not generally update it automatically. Therefore, after + using <EM>curses</EM> functions to accumulate a set of desired updates that make + sense to present together, call <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> to tell the library to make + the user's screen look like <STRONG>stdscr</STRONG>. The library <EM>optimizes</EM> 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 <STRONG><A HREF="curs_terminfo.3x.html">terminfo(3x)</A></STRONG> + API, a feature of every standard <EM>curses</EM> implementation. Special windows called <EM>pads</EM> may also be manipulated. These are windows - which are not constrained to the size of the screen and whose contents - need not be completely displayed. See <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG> for more - information. + that are not constrained to the size of the terminal screen and whose + contents need not be completely displayed. See <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>. - In addition to drawing characters on the screen, video attributes and - colors may be supported, causing the characters to show up in such + 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. Line drawing characters may be - specified to be output. On input, <STRONG>curses</STRONG> is also able to translate - arrow and function keys that transmit escape sequences into single - values. The video attributes, line drawing characters, and input - values use names, defined in <STRONG><curses.h></STRONG>, such as <STRONG>A_REVERSE</STRONG>, <STRONG>ACS_HLINE</STRONG>, - and <STRONG>KEY_LEFT</STRONG>. - - -</PRE><H3><a name="h3-Environment-variables">Environment variables</a></H3><PRE> - If the environment variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> are set, or if the - program is executing in a window environment, line and column - information in the environment will override information read by - <EM>terminfo</EM>. This would affect a program running in an AT&T 630 layer, - for example, where the size of a screen is changeable (see - <STRONG>ENVIRONMENT</STRONG>). - - If the environment variable <STRONG>TERMINFO</STRONG> is defined, any program using - <STRONG>curses</STRONG> checks for a local terminal definition before checking in the - standard place. For example, if <STRONG>TERM</STRONG> is set to <STRONG>att4424</STRONG>, then the - compiled terminal definition is found in - - <STRONG>/usr/share/terminfo/a/att4424</STRONG>. - - (The <STRONG>a</STRONG> is copied from the first letter of <STRONG>att4424</STRONG> to avoid creation of - huge directories.) However, if <STRONG>TERMINFO</STRONG> is set to <STRONG>$HOME/myterms</STRONG>, - <STRONG>curses</STRONG> first checks - - <STRONG>$HOME/myterms/a/att4424</STRONG>, - - and if that fails, it then checks - - <STRONG>/usr/share/terminfo/a/att4424</STRONG>. - - This is useful for developing experimental definitions or when write - permission in <STRONG>/usr/share/terminfo</STRONG> is not available. - - The integer variables <STRONG>LINES</STRONG> and <STRONG>COLS</STRONG> are defined in <STRONG><curses.h></STRONG> and will - be filled in by <STRONG>initscr</STRONG> with the size of the screen. The constants - <STRONG>TRUE</STRONG> and <STRONG>FALSE</STRONG> have the values <STRONG>1</STRONG> and <STRONG>0</STRONG>, respectively. - - The <STRONG>curses</STRONG> routines also define the <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> variable <STRONG>curscr</STRONG> which is - used for certain low-level operations like clearing and redrawing a - screen containing garbage. The <STRONG>curscr</STRONG> can be used in only a few - routines. - - -</PRE><H3><a name="h3-Routine-and-Argument-Names">Routine and Argument Names</a></H3><PRE> - Many <STRONG>curses</STRONG> routines have two or more versions. The routines prefixed - with <STRONG>w</STRONG> require a window argument. The routines prefixed with <STRONG>p</STRONG> require - a pad argument. Those without a prefix generally use <STRONG>stdscr</STRONG>. - - The routines prefixed with <STRONG>mv</STRONG> require a <EM>y</EM> and <EM>x</EM> coordinate to move to - before performing the appropriate action. The <STRONG>mv</STRONG> routines imply a call - to <STRONG>move</STRONG> before the call to the other routine. The coordinate <EM>y</EM> always - refers to the row (of the window), and <EM>x</EM> always refers to the column. - The upper left-hand corner is always (0,0), not (1,1). - - The routines prefixed with <STRONG>mvw</STRONG> take both a window argument and <EM>x</EM> and <EM>y</EM> - coordinates. The window argument is always specified before the - coordinates. - - In each case, <EM>win</EM> is the window affected, and <EM>pad</EM> is the pad affected; - <EM>win</EM> and <EM>pad</EM> are always pointers to type <STRONG>WINDOW</STRONG>. - - Option setting routines require a Boolean flag <EM>bf</EM> with the value <STRONG>TRUE</STRONG> - or <STRONG>FALSE</STRONG>; <EM>bf</EM> is always of type <STRONG>bool</STRONG>. Most of the data types used in - the library routines, such as <STRONG>WINDOW</STRONG>, <STRONG>SCREEN</STRONG>, <STRONG>bool</STRONG>, and <STRONG>chtype</STRONG> are - defined in <STRONG><curses.h></STRONG>. Types used for the terminfo routines such as - <STRONG>TERMINAL</STRONG> are defined in <STRONG><term.h></STRONG>. - - This manual page describes functions which may appear in any - configuration of the library. There are two common configurations of - the library: - - <EM>ncurses</EM> - the "normal" library, which handles 8-bit characters. The - normal (8-bit) library stores characters combined with - attributes in <STRONG>chtype</STRONG> data. - - Attributes alone (no corresponding character) may be stored in - <STRONG>chtype</STRONG> or the equivalent <STRONG>attr_t</STRONG> data. In either case, the data - is stored in something like an integer. - - Each cell (row and column) in a <STRONG>WINDOW</STRONG> is stored as a <STRONG>chtype</STRONG>. - - <EM>ncursesw</EM> - the so-called "wide" library, which handles multibyte - characters (see the section on <STRONG>ALTERNATE</STRONG> <STRONG>CONFIGURATIONS</STRONG>). The - "wide" library includes all of the calls from the "normal" - library. It adds about one third more calls using data types - which store multibyte characters: - - <STRONG>cchar_t</STRONG> - corresponds to <STRONG>chtype</STRONG>. However it is a structure, because - more data is stored than can fit into an integer. The - characters are large enough to require a full integer - value - and there may be more than one character per cell. - The video attributes and color are stored in separate - fields of the structure. - - Each cell (row and column) in a <STRONG>WINDOW</STRONG> is stored as a - <STRONG>cchar_t</STRONG>. - - The <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG> and <STRONG><A HREF="curs_getcchar.3x.html">getcchar(3x)</A></STRONG> functions store and - retrieve the data from a <STRONG>cchar_t</STRONG> structure. + support such display enhancements. See <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>. - <STRONG>wchar_t</STRONG> - stores a "wide" character. Like <STRONG>chtype</STRONG>, this may be an - integer. + <EM>curses</EM> 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 <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG>. - <STRONG>wint_t</STRONG> - stores a <STRONG>wchar_t</STRONG> or <STRONG>WEOF</STRONG> - not the same, though both may - have the same size. + <EM>curses</EM> 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 <EM>escape</EM> <EM>sequence.</EM> <EM>curses</EM> translates these into unique <EM>key</EM> + <EM>codes.</EM> See <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>. - The "wide" library provides new functions which are analogous - to functions in the "normal" library. There is a naming - convention which relates many of the normal/wide variants: a - "_w" is inserted into the name. For example, <STRONG>waddch</STRONG> becomes - <STRONG>wadd_wch</STRONG>. + <EM>ncurses</EM> provides reimplementations of the SVr4 <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG>, and + <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> libraries to ease construction of user interfaces with <EM>curses</EM>. -</PRE><H3><a name="h3-Routine-Name-Index">Routine Name Index</a></H3><PRE> - The following table lists the <STRONG>curses</STRONG> routines provided in the "normal" - and "wide" libraries and the names of the manual pages on which they - are described. Routines flagged with "*" are ncurses-specific, not - described by XPG4 or present in SVr4. - - <STRONG>curses</STRONG> Routine Name Manual Page Name +</PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE> + The selection of an appropriate value of <EM>TERM</EM> in the process + environment is essential to correct <EM>curses</EM> and <EM>terminfo</EM> library + operation. A well-configured system selects a correct <EM>TERM</EM> value + automatically; <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> may assist with troubleshooting exotic + situations. + + If you change the terminal type, export the <EM>TERM</EM> environment variable + in the shell, then run <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> or the "<STRONG>tput</STRONG> <STRONG>init</STRONG>" command. See + subsection "Tabs and Initialization" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. + + If the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM> are set, or if the + <EM>curses</EM> program is executing in a graphical windowing environment, the + information obtained thence overrides that obtained by <EM>terminfo</EM>. An + <EM>ncurses</EM> extension supports resizable terminals; see <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG>. + + If the environment variable <EM>TERMINFO</EM> is defined, a <EM>curses</EM> program + checks first for a terminal type description in the location it + identifies. <EM>TERMINFO</EM> is useful for developing experimental type + descriptions or when write permission to <EM>/usr/share/terminfo</EM> is not + available. + + See section "ENVIRONMENT" below. + + +</PRE><H3><a name="h3-Naming-Conventions">Naming Conventions</a></H3><PRE> + <EM>curses</EM> 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 <EM>WINDOW</EM> pointer argument; those with a "mv" prefix first + perform cursor movement using <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG>; a "mvw" prefix indicates both. + The "w" function is typically the elemental one; the removal of this + prefix usually indicates operation on <STRONG>stdscr</STRONG>. + + Four functions prefixed with "p" require a pad argument. + + In function synopses, <EM>ncurses</EM> man pages apply the following names to + parameters. + + <EM>bf</EM> <EM>bool</EM> (<STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>) + <EM>c</EM> a <EM>char</EM> or <EM>int</EM> + <EM>ch</EM> a <EM>chtype</EM> + <EM>wc</EM> a <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> or <EM>wint</EM><STRONG>_</STRONG><EM>t</EM> + <EM>wch</EM> a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> + <EM>win</EM> pointer to a <EM>WINDOW</EM> + <EM>pad</EM> pointer to a <EM>WINDOW</EM> that is a pad + + +</PRE><H3><a name="h3-Wide-and-Non-wide-Character-Configurations">Wide and Non-wide Character Configurations</a></H3><PRE> + This manual page describes functions that appear in any configuration + of the library. There are two common configurations; see section + "ALTERNATE CONFIGURATIONS" below. + + <EM>ncurses</EM> is the library in its "non-wide" configuration, handling only + eight-bit characters. It stores a character combined with + attributes in a <EM>chtype</EM> datum, which is often an alias of <EM>int</EM>. + + Attributes alone (with no corresponding character) can be + stored in variables of <EM>chtype</EM> or <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> type. In either + case, they are represented as an integral bit mask. + + Each cell of a <EM>WINDOW</EM> is stored as a <EM>chtype</EM>. + + <EM>ncursesw</EM> is the library in its "wide" configuration, which handles + character encodings requiring a larger data type than <EM>char</EM> (a + byte-sized type) can represent. It adds about one third more + calls using additional data types that can store such + <EM>multibyte</EM> characters. + + <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> corresponds to the non-wide configuration's <EM>chtype</EM>. + It always a structure type, because it stores more + data than fit into a standard scalar type. A + character code may not be representable as a <EM>char</EM>, + and moreover more than one character may occupy a + cell (as with accent marks and other diacritics). + Each character is of type <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>; 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 <EM>chtype</EM>. + + Each cell of a <EM>WINDOW</EM> is stored as a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>. + + <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG> and <STRONG><A HREF="curs_getcchar.3x.html">getcchar(3x)</A></STRONG> store and retrieve <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> + data. The wide library API of <EM>ncurses</EM> depends on two data + types standardized by ISO C95. + + <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> stores a wide character. Like <EM>chtype</EM>, it may be an + alias of <EM>int</EM>. Depending on the character encoding, + a wide character may be <EM>spacing</EM>, meaning that it + occupies a character cell by itself and typically + accompanies cursor advancement, or <EM>non-spacing</EM>, + 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. + + <EM>wint</EM><STRONG>_</STRONG><EM>t</EM> can store a <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> or the constant <STRONG>WEOF</STRONG>, + analogously to the <EM>int</EM>-sized character manipulation + functions of ISO C and its constant <STRONG>EOF</STRONG>. + + 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, <STRONG>waddch</STRONG> becomes <STRONG>wadd_wch</STRONG>. + (Exceptions that add only "w" comprise <STRONG>addwstr</STRONG>, <STRONG>inwstr</STRONG>, 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". + + +</PRE><H3><a name="h3-Function-Name-Index">Function Name Index</a></H3><PRE> + The following table lists the <EM>curses</EM> functions provided in the non-wide + and wide APIs and the corresponding man pages that describe them. + Those flagged with "*" are <EM>ncurses</EM>-specific, neither described by + X/Open Curses nor present in SVr4. + + <STRONG><EM>curses</EM></STRONG> Function Name Man Page --------------------------------------------- COLOR_PAIR <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> - PAIR_NUMBER <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> + PAIR_NUMBER <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> add_wch <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> add_wchnstr <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG> add_wchstr <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG> @@ -313,7 +351,6 @@ bkgrnd <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG> bkgrndset <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG> border <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG> - border_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG> box <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG> box_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG> @@ -343,6 +380,7 @@ doupdate <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG> dupwin <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG> echo <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> + echo_wchar <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> echochar <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> endwin <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG> @@ -359,6 +397,7 @@ flash <STRONG><A HREF="curs_beep.3x.html">curs_beep(3x)</A></STRONG> flushinp <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> free_pair <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG>* + get_escdelay <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>* get_wch <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> get_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG> getattrs <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> @@ -379,7 +418,6 @@ getnstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG> getparx <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>* getpary <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>* - getparyx <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG> getstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG> getsyx <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG> @@ -408,6 +446,7 @@ init_pair <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> initscr <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG> innstr <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG> + innwstr <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG> ins_nwstr <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG> ins_wch <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG> @@ -420,16 +459,20 @@ instr <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG> intrflush <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> inwstr <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG> + is_cbreak <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>* is_cleared <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>* + is_echo <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>* is_idcok <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>* is_idlok <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>* is_immedok <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>* is_keypad <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>* is_leaveok <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>* is_linetouched <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG> + is_nl <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>* is_nodelay <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>* is_notimeout <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>* is_pad <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>* + is_raw <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>* is_scrollok <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>* is_subwin <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>* is_syncok <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>* @@ -445,7 +488,6 @@ killchar <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG> killwchar <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG> leaveok <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> - longname <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG> mcprint <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG>* meta <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> @@ -470,6 +512,7 @@ mvget_wch <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> mvget_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG> mvgetch <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> + mvgetn_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG> mvgetnstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG> mvgetstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG> @@ -511,7 +554,6 @@ mvwget_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG> mvwgetch <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> mvwgetn_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG> - mvwgetnstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG> mvwgetstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG> mvwhline <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG> @@ -536,6 +578,7 @@ mvwprintw <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG> mvwscanw <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG> mvwvline <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG> + mvwvline_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG> napms <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG> newpad <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG> @@ -553,7 +596,7 @@ overlay <STRONG><A HREF="curs_overlay.3x.html">curs_overlay(3x)</A></STRONG> overwrite <STRONG><A HREF="curs_overlay.3x.html">curs_overlay(3x)</A></STRONG> pair_content <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> - pecho_wchar <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>* + pecho_wchar <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG> pechochar <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG> pnoutrefresh <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG> prefresh <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG> @@ -577,12 +620,13 @@ scr_dump <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG> scr_init <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG> scr_restore <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG> - scr_set <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG> scrl <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG> scroll <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG> scrollok <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> set_curterm <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> + set_escdelay <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>* + set_tabsize <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>* set_term <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG> setcchar <STRONG><A HREF="curs_getcchar.3x.html">curs_getcchar(3x)</A></STRONG> setscrreg <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> @@ -600,11 +644,12 @@ slk_init <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> slk_label <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> slk_noutrefresh <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> + slk_refresh <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> slk_restore <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> slk_set <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> slk_touch <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> - slk_wset <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>* + slk_wset <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> standend <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> standout <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> start_color <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> @@ -623,7 +668,9 @@ tigetnum <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> tigetstr <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> timeout <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> - tiparm <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>* + tiparm <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> + tiparm_s <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>* + tiscan_s <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>* touchline <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG> touchwin <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG> tparm <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> @@ -640,10 +687,11 @@ use_env <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> use_extended_names <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG>* use_legacy_coding <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG>* + use_screen <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>* use_tioctl <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>* + use_window <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>* vid_attr <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> vid_puts <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> - vidattr <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> vidputs <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> vline <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG> @@ -662,6 +710,7 @@ waddnwstr <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG> waddstr <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG> waddwstr <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG> + wattr_get <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> wattr_off <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> wattr_on <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> @@ -709,7 +758,6 @@ winnwstr <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG> wins_nwstr <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG> wins_wch <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG> - wins_wstr <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG> winsch <STRONG><A HREF="curs_insch.3x.html">curs_insch(3x)</A></STRONG> winsdelln <STRONG><A HREF="curs_deleteln.3x.html">curs_deleteln(3x)</A></STRONG> @@ -728,6 +776,7 @@ wscanw <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG> wscrl <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG> wsetscrreg <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> + wstandend <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> wstandout <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> wsyncdown <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG> @@ -738,259 +787,237 @@ wvline <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG> wvline_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG> - Depending on the configuration, additional sets of functions may be - available: - - <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG> - curses memory-leak checking - - <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG> - curses screen-pointer extension + <EM>ncurses</EM>'s <EM>screen-pointer</EM> <EM>extension</EM> adds additional functions + corresponding to many of the above, each with an "_sp" suffix; see + <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>. - <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> - curses thread support - - <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG> - curses debugging routines + The availability of some extensions is configurable when <EM>ncurses</EM> is + compiled; see sections "ALTERNATE CONFIGURATIONS" and "EXTENSIONS" + below. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Routines that return an integer return <STRONG>ERR</STRONG> upon failure and an integer - value other than <STRONG>ERR</STRONG> upon successful completion, unless otherwise noted - in the routine descriptions. - - As a general rule, routines check for null pointers passed as - parameters, and handle this as an error. - - All macros return the value of the <STRONG>w</STRONG> version, except <STRONG>setscrreg</STRONG>, - <STRONG>wsetscrreg</STRONG>, <STRONG>getyx</STRONG>, <STRONG>getbegyx</STRONG>, and <STRONG>getmaxyx</STRONG>. The return values of - <STRONG>setscrreg</STRONG>, <STRONG>wsetscrreg</STRONG>, <STRONG>getyx</STRONG>, <STRONG>getbegyx</STRONG>, and <STRONG>getmaxyx</STRONG> are undefined - (i.e., these should not be used as the right-hand side of assignment - statements). + Unless otherwise noted, functions that return an integer return <STRONG>OK</STRONG> on + success and <STRONG>ERR</STRONG> on failure. Functions that return pointers return <STRONG>NULL</STRONG> + on failure. Typically, <EM>ncurses</EM> 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 (<EM>y</EM>, <EM>x</EM>) is outside the + window boundaries. - Functions with a "mv" prefix first perform a cursor movement using - <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if - the window pointer is null. Most "mv"-prefixed functions (except - variadic functions such as <STRONG>mvprintw</STRONG>) are provided both as macros and - functions. - Routines that return pointers return <STRONG>NULL</STRONG> on error. +</PRE><H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE> + The following symbols from the process environment customize the + runtime behavior of <EM>ncurses</EM> applications. The library may be + configured to disregard the variables <EM>TERMINFO</EM>, <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM>, + <EM>TERMPATH</EM>, and <EM>HOME</EM>, if the user is the superuser (root), or the + application uses <STRONG>setuid(2)</STRONG> or <STRONG>setgid(2)</STRONG>. -</PRE><H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE> - The following environment symbols are useful for customizing the - runtime behavior of the <STRONG>ncurses</STRONG> library. The most important ones have - been already discussed in detail. +</PRE><H3><a name="h3-BAUDRATE"><EM>BAUDRATE</EM></a></H3><PRE> + 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, <EM>ncurses</EM> uses 9600. This + feature allows testers to construct repeatable test cases that take + into account optimization decisions that depend on baud rate. -</PRE><H3><a name="h3-CC-command-character">CC command-character</a></H3><PRE> - When set, change occurrences of the command_character (i.e., the <STRONG>cmdch</STRONG> - capability) of the loaded terminfo entries to the value of this - variable. Very few terminfo entries provide this feature. +</PRE><H3><a name="h3-CC-_command-character_"><EM>CC</EM> (command character)</a></H3><PRE> + When set, the <STRONG>command_character</STRONG> (<STRONG>cmdch</STRONG>) capability value of loaded + <EM>terminfo</EM> entries changes to the value of this variable. Very few <EM>term-</EM> + <EM>info</EM> entries provide this feature. Because this name is also used in development environments to represent - the C compiler's name, <STRONG>ncurses</STRONG> ignores it if it does not happen to be a - single character. - - -</PRE><H3><a name="h3-BAUDRATE">BAUDRATE</a></H3><PRE> - 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, <STRONG>ncurses</STRONG> uses - 9600. This allows testers to construct repeatable test-cases that take - into account costs that depend on baudrate. - - -</PRE><H3><a name="h3-COLUMNS">COLUMNS</a></H3><PRE> - 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 <STRONG>COLUMNS</STRONG> value nor - the terminal's screen size is available, <STRONG>ncurses</STRONG> uses the size which - may be specified in the terminfo database (i.e., the <STRONG>cols</STRONG> 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 <STRONG>COLUMNS</STRONG> and/or <STRONG>LINES</STRONG> overrides the library's use of - the screen size obtained from the operating system. - - Either <STRONG>COLUMNS</STRONG> or <STRONG>LINES</STRONG> 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, <STRONG>lines</STRONG> and <STRONG>cols</STRONG> should not be specified in a terminal - description for terminals which are run as emulations. - - Use the <STRONG>use_env</STRONG> function to disable all use of external environment - (but not including system calls) to determine the screen size. Use the - <STRONG>use_tioctl</STRONG> function to update <STRONG>COLUMNS</STRONG> or <STRONG>LINES</STRONG> to match the screen size - obtained from system calls or the terminal database. - - -</PRE><H3><a name="h3-ESCDELAY">ESCDELAY</a></H3><PRE> - 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. + the C compiler's name, <EM>ncurses</EM> ignores its value if it is not one + character in length. + + +</PRE><H3><a name="h3-COLUMNS"><EM>COLUMNS</EM></a></H3><PRE> + 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 <EM>COLUMNS</EM> + is not defined and the terminal's screen size is not available from the + terminal driver, <EM>ncurses</EM> uses the size specified by the <STRONG>columns</STRONG> (<STRONG>cols</STRONG>) + capability of the terminal type's entry in the <EM>terminfo</EM> 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 <EM>COLUMNS</EM> and/or <EM>LINES</EM> + overrides the library's use of the screen size obtained from the + operating system. + + The <EM>COLUMNS</EM> and <EM>LINES</EM> variables may be specified independently. This + property is useful to circumvent misfeatures of legacy terminal type + descriptions; <STRONG>xterm(1)</STRONG> descriptions specifying 65 lines were once + notorious. For best results, avoid specifying <STRONG>cols</STRONG> and <STRONG>lines</STRONG> + capability codes in <EM>terminfo</EM> descriptions of terminal emulators. + + <STRONG><A HREF="curs_util.3x.html">use_env(3x)</A></STRONG> can disable use of the process environment in determining + the screen size. <STRONG><A HREF="curs_util.3x.html">use_tioctl(3x)</A></STRONG> can update <EM>COLUMNS</EM> and <EM>LINES</EM> to match + the screen size obtained from system calls or the terminal database. + + +</PRE><H3><a name="h3-ESCDELAY"><EM>ESCDELAY</EM></a></H3><PRE> + For <EM>curses</EM> to distinguish the ESC character resulting from a user's + press of the "Escape" key on the input device from one beginning an + <EM>escape</EM> <EM>sequence</EM> (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 <STRONG>ESCDELAY</STRONG> stores this interval in milliseconds. The default + value of 1000 (one second) is adequate for most uses. This environment + variable overrides it. 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. - - 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. - - 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. - - -</PRE><H3><a name="h3-HOME">HOME</a></H3><PRE> - Tells <STRONG>ncurses</STRONG> where your home directory is. That is where it may read - and write auxiliary terminal descriptions: - - $HOME/.termcap - $HOME/.terminfo - - -</PRE><H3><a name="h3-LINES">LINES</a></H3><PRE> - Like COLUMNS, specify the height of the screen in characters. See - COLUMNS for a detailed description. - - -</PRE><H3><a name="h3-MOUSE_BUTTONS_123">MOUSE_BUTTONS_123</a></H3><PRE> - 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, <STRONG>ncurses</STRONG> uses 132. - - -</PRE><H3><a name="h3-NCURSES_ASSUMED_COLORS">NCURSES_ASSUMED_COLORS</a></H3><PRE> - Override the compiled-in assumption that the terminal's default colors - are white-on-black (see <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>). 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 <STRONG>max_colors</STRONG> value is allowed. - - -</PRE><H3><a name="h3-NCURSES_CONSOLE2">NCURSES_CONSOLE2</a></H3><PRE> - This applies only to the MinGW port of ncurses. - - The <STRONG>Console2</STRONG> program's handling of the Microsoft Console API call - <STRONG>CreateConsoleScreenBuffer</STRONG> 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 <STRONG>NCGDB</STRONG> has the same - effect. - - -</PRE><H3><a name="h3-NCURSES_GPM_TERMS">NCURSES_GPM_TERMS</a></H3><PRE> - 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 <STRONG>TERM</STRONG> 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 <STRONG>TERM</STRONG> contains "linux". - - -</PRE><H3><a name="h3-NCURSES_NO_HARD_TABS">NCURSES_NO_HARD_TABS</a></H3><PRE> - <STRONG>Ncurses</STRONG> may use tabs as part of the cursor movement optimization. In - some cases, your terminal driver may not handle these properly. Set - this environment variable to disable the feature. You can also adjust - your <STRONG>stty</STRONG> settings to avoid the problem. - - -</PRE><H3><a name="h3-NCURSES_NO_MAGIC_COOKIE">NCURSES_NO_MAGIC_COOKIE</a></H3><PRE> - 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. - - -</PRE><H3><a name="h3-NCURSES_NO_PADDING">NCURSES_NO_PADDING</a></H3><PRE> - 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 + work with a remote host over a slow communication channel. If the host + running a <EM>curses</EM> application does not receive the characters of an + escape sequence in a timely manner, the library can interpret them as + multiple key stroke events. + + <STRONG>xterm(1)</STRONG> 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 <STRONG>ESCDELAY</STRONG> in + either form, but setting the environment variable rather than the + global variable does not create problems when compiling an application. + + If <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG> is disabled for the <EM>curses</EM> window receiving input, a + program must disambiguate escape sequences itself. + + +</PRE><H3><a name="h3-HOME"><EM>HOME</EM></a></H3><PRE> + <EM>ncurses</EM> may read and write auxiliary terminal descriptions in <EM>.termcap</EM> + and <EM>.terminfo</EM> files in the user's home directory. + + +</PRE><H3><a name="h3-LINES"><EM>LINES</EM></a></H3><PRE> + This counterpart to <EM>COLUMNS</EM> specifies the height of the screen in + characters. The corresponding <EM>terminfo</EM> capability and code is <STRONG>lines</STRONG>. + See the description of the <EM>COLUMNS</EM> variable above. + + +</PRE><H3><a name="h3-MOUSE_BUTTONS_123"><EM>MOUSE_BUTTONS_123</EM></a></H3><PRE> + (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, <EM>ncurses</EM> + assumes a numbering of "132". + + +</PRE><H3><a name="h3-NCURSES_ASSUMED_COLORS"><EM>NCURSES_ASSUMED_COLORS</EM></a></H3><PRE> + If set, this variable overrides the <EM>ncurses</EM> library's compiled-in + assumption that the terminal's default colors are white on black; see + <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>. 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 <EM>ncurses</EM> 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". <EM>ncurses</EM> accepts integral values from -1 up to the + value of the <EM>terminfo</EM> <STRONG>max_colors</STRONG> (<STRONG>colors</STRONG>) capability. + + +</PRE><H3><a name="h3-NCURSES_CONSOLE2"><EM>NCURSES_CONSOLE2</EM></a></H3><PRE> + (MinGW port only) The <EM>Console2</EM> program defectively handles the + Microsoft Console API call <EM>CreateConsoleScreenBuffer</EM>. 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 <EM>NCGDB</EM> + has the same effect. + + +</PRE><H3><a name="h3-NCURSES_GPM_TERMS"><EM>NCURSES_GPM_TERMS</EM></a></H3><PRE> + (Linux only) When <EM>ncurses</EM> is configured to use the GPM interface, this + variable may list one or more terminal names against which the <EM>TERM</EM> + variable (see below) is matched. An empty value disables the GPM + interface, using <EM>ncurses</EM>'s built-in support for <STRONG>xterm(1)</STRONG> mouse + protocols instead. If the variable is absent, <EM>ncurses</EM> attempts to open + GPM if <EM>TERM</EM> contains "linux". + + +</PRE><H3><a name="h3-NCURSES_NO_HARD_TABS"><EM>NCURSES_NO_HARD_TABS</EM></a></H3><PRE> + <EM>ncurses</EM> 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 <STRONG>stty(1)</STRONG> settings to avoid the problem. + + +</PRE><H3><a name="h3-NCURSES_NO_MAGIC_COOKIE"><EM>NCURSES_NO_MAGIC_COOKIE</EM></a></H3><PRE> + Many terminals store video attributes as a property of a character + cell, as <EM>curses</EM> does. Historically, some recorded changes in video + attributes as data that logically <EM>occupies</EM> 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 <EM>terminfo</EM> entry for your terminal type does not + adequately describe its handling of magic cookies, set this variable to + any value to instruct <EM>ncurses</EM> to disable attributes entirely. + + +</PRE><H3><a name="h3-NCURSES_NO_PADDING"><EM>NCURSES_NO_PADDING</EM></a></H3><PRE> + Most terminal type descriptions in the <EM>terminfo</EM> database detail + hardware devices. Many people use <EM>curses</EM>-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), 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 <EM>flash</EM>. - - -</PRE><H3><a name="h3-NCURSES_NO_SETBUF">NCURSES_NO_SETBUF</a></H3><PRE> - This setting is obsolete. Before changes - - <STRONG>o</STRONG> started with 5.9 patch 20120825 and - - <STRONG>o</STRONG> continued though 5.9 patch 20130126 - - <STRONG>ncurses</STRONG> enabled buffered output during terminal initialization. This - was done (as in SVr4 curses) for performance reasons. For testing - purposes, both of <STRONG>ncurses</STRONG> 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 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 <STRONG>putp</STRONG> - still use the standard output. But high-level curses calls do not. - - -</PRE><H3><a name="h3-NCURSES_NO_UTF8_ACS">NCURSES_NO_UTF8_ACS</a></H3><PRE> - During initialization, the <STRONG>ncurses</STRONG> 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 - <STRONG>TERM</STRONG> 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 <STRONG>U8</STRONG>. This is a numeric capability which - can be compiled using <STRONG>tic</STRONG> <STRONG>-x</STRONG>. For example + does flow control), an application must manage flow control 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 <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>PADDING</EM> to any + value to disable all but mandatory padding. Mandatory padding is used + by such terminal capabilities as <STRONG>flash_screen</STRONG> (<STRONG>flash</STRONG>). + + +</PRE><H3><a name="h3-NCURSES_NO_SETBUF"><EM>NCURSES_NO_SETBUF</EM></a></H3><PRE> + (Obsolete) Prior to internal changes developed in <EM>ncurses</EM> 5.9 (patches + 20120825 through 20130126), the library used <STRONG>setbuf(3)</STRONG> to enable fully + buffered output when initializing the terminal. This was done, as in + SVr4 <EM>curses</EM>, to increase performance. For testing purposes, both of + <EM>ncurses</EM> 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, <EM>ncurses</EM> 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 + <STRONG>stdio(3)</STRONG> calls with <EM>ncurses</EM> calls and (usually) got the behavior they + expected. This is no longer the case; <EM>ncurses</EM> does not write to the + standard output file descriptor through a <EM>stdio</EM>-buffered stream. + + As a special case, low-level API calls such as <STRONG><A HREF="curs_terminfo.3x.html">putp(3x)</A></STRONG> still use the + standard output stream. High-level <EM>curses</EM> calls such as <STRONG><A HREF="curs_printw.3x.html">printw(3x)</A></STRONG> do + not. + + +</PRE><H3><a name="h3-NCURSES_NO_UTF8_ACS"><EM>NCURSES_NO_UTF8_ACS</EM></a></H3><PRE> + At initialization, <EM>ncurses</EM> inspects the <EM>TERM</EM> environment variable for + special cases where VT100 forms-drawing characters (and the + corresponding alternate character set <EM>terminfo</EM> 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 <STRONG>screen(1)</STRONG> program ignore them. Set + this variable to a nonzero value to instruct <EM>ncurses</EM> 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 <EM>ncurses</EM> to assume that the ACS + feature works if the terminal type description advertises it. + + As an alternative to use of this variable, <EM>ncurses</EM> checks for an + extended <EM>terminfo</EM> numeric capability <STRONG>U8</STRONG> that can be compiled using "<STRONG>tic</STRONG> + <STRONG>-x</STRONG>". Examples follow. # linux console, if patched to provide working # VT100 shift-in/shift-out, with corresponding font. @@ -1001,170 +1028,135 @@ 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 <EM>ncurses</EM>'s + <EM>termcap</EM> interface. -</PRE><H3><a name="h3-NCURSES_TRACE">NCURSES_TRACE</a></H3><PRE> - During initialization, the <STRONG>ncurses</STRONG> debugging library checks the - NCURSES_TRACE environment variable. If it is defined, to a numeric - value, <STRONG>ncurses</STRONG> calls the <STRONG>trace</STRONG> function, using that value as the - argument. - The argument values, which are defined in <STRONG>curses.h</STRONG>, provide several - types of information. When running with traces enabled, your - application will write the file <STRONG>trace</STRONG> to the current directory. +</PRE><H3><a name="h3-NCURSES_TRACE"><EM>NCURSES_TRACE</EM></a></H3><PRE> + At initialization, <EM>ncurses</EM> (in its debugging configuration) checks for + this variable's presence. If defined with an integral value, the + library calls <STRONG><A HREF="curs_trace.3x.html">curses_trace(3x)</A></STRONG> with that value as the argument. - See <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG> for more information. +</PRE><H3><a name="h3-TERM"><EM>TERM</EM></a></H3><PRE> + The <EM>TERM</EM> 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. -</PRE><H3><a name="h3-TERM">TERM</a></H3><PRE> - Denotes your terminal type. Each terminal type is distinct, though - many are similar. + Setting <EM>TERM</EM> has no effect on hardware operation; it affects the way + applications communicate with the terminal. Likewise, as a general + rule (<STRONG>xterm(1)</STRONG> being a rare exception), terminal emulators that allow + you to specify <EM>TERM</EM> as a parameter or configuration value do not change + their behavior to match that setting. - <STRONG>TERM</STRONG> 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 <STRONG>TERM</STRONG> 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 (<STRONG>xterm</STRONG> being a rare - exception), terminal emulators which allow you to specify <STRONG>TERM</STRONG> as a - parameter or configuration value do not change their behavior to match - that setting. +</PRE><H3><a name="h3-TERMCAP"><EM>TERMCAP</EM></a></H3><PRE> + If <EM>ncurses</EM> is configured with <EM>termcap</EM> support, it checks for a terminal + type description in <EM>termcap</EM> format if one in <EM>terminfo</EM> format is not + available. Setting this variable directs <EM>ncurses</EM> to ignore the usual + <EM>termcap</EM> database location, <EM>/etc/termcap</EM>; see <EM>TERMPATH</EM> below. <EM>TERMCAP</EM> + should contain either a terminal description (with newlines stripped + out), or a file name indicating where the information required by the + <EM>TERM</EM> environment variable is stored. -</PRE><H3><a name="h3-TERMCAP">TERMCAP</a></H3><PRE> - If the <STRONG>ncurses</STRONG> library has been configured with <EM>termcap</EM> support, - <STRONG>ncurses</STRONG> will check for a terminal's description in termcap form if it - is not available in the terminfo database. +</PRE><H3><a name="h3-TERMINFO"><EM>TERMINFO</EM></a></H3><PRE> + <EM>ncurses</EM> can be configured to read terminal type description databases + in various locations using different formats. This variable overrides + the default location. - The <STRONG>TERMCAP</STRONG> environment variable contains either a terminal description - (with newlines stripped out), or a file name telling where the - information denoted by the <STRONG>TERM</STRONG> environment variable exists. In either - case, setting it directs <STRONG>ncurses</STRONG> to ignore the usual place for this - information, e.g., /etc/termcap. + <STRONG>o</STRONG> Descriptions in <EM>terminfo</EM> 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. + <STRONG>o</STRONG> If <EM>ncurses</EM> is configured to use hashed databases, then <EM>TERMINFO</EM> may + name its location, such as <EM>/usr/share/terminfo.db</EM>, rather than + <EM>/usr/share/terminfo/</EM>. -</PRE><H3><a name="h3-TERMINFO">TERMINFO</a></H3><PRE> - <STRONG>ncurses</STRONG> can be configured to read from multiple terminal databases. - The <STRONG>TERMINFO</STRONG> variable overrides the location for the default terminal - database. Terminal descriptions (in terminal format) are stored in - terminal databases: + 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 <EM>terminfo</EM> + API. - <STRONG>o</STRONG> Normally these are stored in a directory tree, using subdirectories - named by the first letter of the terminal names therein. + <STRONG>o</STRONG> If <EM>ncurses</EM> is configured with <EM>termcap</EM> support, this variable may + contain the location of a <EM>termcap</EM> file. - This is the scheme used in System V, which legacy Unix systems use, - and the <STRONG>TERMINFO</STRONG> variable is used by <EM>curses</EM> applications on those - systems to override the default location of the terminal database. + <STRONG>o</STRONG> If the value of <EM>TERMINFO</EM> begins with "hex:" or "b64:", <EM>ncurses</EM> uses + the remainder of the value as a compiled <EM>terminfo</EM> description. You + might produce the base64 format using <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>. - <STRONG>o</STRONG> If <STRONG>ncurses</STRONG> is built to use hashed databases, then each entry in - this list may be the path of a hashed database file, e.g., + TERMINFO=$(infocmp -0 -Q2 -q) + export TERMINFO - /usr/share/terminfo.db + The compiled description is used only if it corresponds to the + terminal type identified by <EM>TERM</EM>. - rather than + Setting <EM>TERMINFO</EM> is the simplest, but not the only, way to direct + <EM>ncurses</EM> to a terminal database. The search path is as follows. - /usr/share/terminfo/ + <STRONG>o</STRONG> the last terminal database to which the running <EM>ncurses</EM> application + wrote, if any - 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. + <STRONG>o</STRONG> the location specified by the <EM>TERMINFO</EM> environment variable - <STRONG>o</STRONG> If <STRONG>ncurses</STRONG> is built with a support for reading termcap files - directly, then an entry in this list may be the path of a termcap - file. + <STRONG>o</STRONG> <EM>$HOME/.terminfo</EM> - <STRONG>o</STRONG> If the <STRONG>TERMINFO</STRONG> variable begins with "hex:" or "b64:", <STRONG>ncurses</STRONG> uses - the remainder of that variable as a compiled terminal description. - You might produce the base64 format using <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>: + <STRONG>o</STRONG> locations listed in the <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> environment variable - TERMINFO="$(infocmp -0 -Q2 -q)" - export TERMINFO + <STRONG>o</STRONG> location(s) configured and compiled into <EM>ncurses</EM> - The compiled description is used if it corresponds to the terminal - identified by the <STRONG>TERM</STRONG> variable. + <STRONG>o</STRONG> <EM>/usr/share/terminfo</EM> - Setting <STRONG>TERMINFO</STRONG> 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: - <STRONG>o</STRONG> the last terminal database to which <STRONG>ncurses</STRONG> wrote, if any, is - searched first +</PRE><H3><a name="h3-TERMINFO_DIRS"><EM>TERMINFO_DIRS</EM></a></H3><PRE> + This variable specifies a list of locations, akin to <EM>PATH</EM>, in which + <EM>ncurses</EM> searches for the terminal type descriptions described by + <EM>TERMINFO</EM> above. The list items are separated by colons on Unix and + semicolons on OS/2 EMX. System V <EM>terminfo</EM> lacks a corresponding + feature; <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> is an <EM>ncurses</EM> extension. - <STRONG>o</STRONG> the location specified by the TERMINFO environment variable - <STRONG>o</STRONG> $HOME/.terminfo +</PRE><H3><a name="h3-TERMPATH"><EM>TERMPATH</EM></a></H3><PRE> + If <EM>TERMCAP</EM> does not hold a terminal type description or file name, then + <EM>ncurses</EM> checks the contents of <EM>TERMPATH</EM>, a list of locations, akin to + <EM>PATH</EM>, in which it searches for <EM>termcap</EM> terminal type descriptions. The + list items are separated by colons on Unix and semicolons on OS/2 EMX. - <STRONG>o</STRONG> locations listed in the TERMINFO_DIRS environment variable - - <STRONG>o</STRONG> one or more locations whose names are configured and compiled - into the ncurses library, i.e., - - <STRONG>o</STRONG> no default value (corresponding to the TERMINFO_DIRS - variable) - - <STRONG>o</STRONG> /usr/share/terminfo (corresponding to the TERMINFO variable) - - -</PRE><H3><a name="h3-TERMINFO_DIRS">TERMINFO_DIRS</a></H3><PRE> - 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 <STRONG>TERMINFO</STRONG> 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 <STRONG>ncurses</STRONG>. - - -</PRE><H3><a name="h3-TERMPATH">TERMPATH</a></H3><PRE> - If <STRONG>TERMCAP</STRONG> does not hold a file name then <STRONG>ncurses</STRONG> checks the <STRONG>TERMPATH</STRONG> - environment variable. This is a list of filenames separated by spaces - or colons (i.e., ":") on Unix, semicolons on OS/2 EMX. - - If the <STRONG>TERMPATH</STRONG> environment variable is not set, <STRONG>ncurses</STRONG> looks in the - files - - /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap, - - in that order. - - 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 <EM>TERMCAP</EM> and <EM>TERMPATH</EM> are unset or invalid, <EM>ncurses</EM> searches for + the files <EM>/etc/termcap</EM>, <EM>/usr/share/misc/termcap</EM>, and <EM>$HOME/.termcap</EM>, in + that order. </PRE><H2><a name="h2-ALTERNATE-CONFIGURATIONS">ALTERNATE CONFIGURATIONS</a></H2><PRE> - Several different configurations are possible, depending on the - configure script options used when building <STRONG>ncurses</STRONG>. There are a few - main options whose effects are visible to the applications developer - using <STRONG>ncurses</STRONG>: + Many different <EM>ncurses</EM> configurations are possible, determined by the + options given to the <EM>configure</EM> script when building the library. Run + the script with the <STRONG>--help</STRONG> option to peruse them all. A few are of + particular significance to the application developer employing <EM>ncurses</EM>. - --disable-overwrite - The standard include for <STRONG>ncurses</STRONG> is as noted in <STRONG>SYNOPSIS</STRONG>: + <STRONG>--disable-overwrite</STRONG> + The standard include for <EM>ncurses</EM> is as noted in <STRONG>SYNOPSIS</STRONG>: <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - This option is used to avoid filename conflicts when <STRONG>ncurses</STRONG> is - not the main implementation of curses of the computer. If <STRONG>ncurses</STRONG> - is installed disabling overwrite, it puts its headers in a + This option is used to avoid filename conflicts when <EM>ncurses</EM> is + not the main implementation of curses of the computer. If <EM>ncurses</EM> + is installed disabling overwrite, it puts its headers in a subdirectory, e.g., <STRONG>#include</STRONG> <STRONG><ncurses/curses.h></STRONG> - It also omits a symbolic link which would allow you to use + It also omits a symbolic link which would allow you to use <STRONG>-lcurses</STRONG> to build executables. - --enable-widec - The configure script renames the library and (if the - <STRONG>--disable-overwrite</STRONG> option is used) puts the header files in a - different subdirectory. All of the library names have a "w" + <STRONG>--enable-widec</STRONG> + The configure script renames the library and (if the + <STRONG>--disable-overwrite</STRONG> 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 <STRONG>-lncurses</STRONG> @@ -1173,310 +1165,318 @@ <STRONG>-lncursesw</STRONG> - 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: - <STRONG>o</STRONG> Originally, the wide-character feature required the symbol + <STRONG>o</STRONG> Originally, the wide-character feature required the symbol <STRONG>_XOPEN_SOURCE_EXTENDED</STRONG> but that was only valid for XPG4 (1996). - <STRONG>o</STRONG> Later, that was deemed conflicting with <STRONG>_XOPEN_SOURCE</STRONG> defined + <STRONG>o</STRONG> Later, that was deemed conflicting with <STRONG>_XOPEN_SOURCE</STRONG> defined to 500. - <STRONG>o</STRONG> As of mid-2018, none of the features in this implementation - require a <STRONG>_XOPEN_SOURCE</STRONG> feature greater than 600. However, + <STRONG>o</STRONG> As of mid-2018, none of the features in this implementation + require a <STRONG>_XOPEN_SOURCE</STRONG> feature greater than 600. However, X/Open Curses, Issue 7 (2009) recommends defining it to 700. - <STRONG>o</STRONG> Alternatively, you can enable the feature by defining - <STRONG>NCURSES_WIDECHAR</STRONG> with the caveat that some other header file - than <STRONG>curses.h</STRONG> may require a specific value for <STRONG>_XOPEN_SOURCE</STRONG> + <STRONG>o</STRONG> Alternatively, you can enable the feature by defining + <STRONG>NCURSES_WIDECHAR</STRONG> with the caveat that some other header file + than <STRONG>curses.h</STRONG> may require a specific value for <STRONG>_XOPEN_SOURCE</STRONG> (or a system-specific symbol). - The <STRONG>curses.h</STRONG> file which is installed for the wide-character - library is designed to be compatible with the normal library's - header. Only the size of the <STRONG>WINDOW</STRONG> structure differs, and very - few applications require more than a pointer to <STRONG>WINDOW</STRONG>s. + The <EM>curses.h</EM> 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 <EM>WINDOW</EM> structure differs; few applications + require more than pointers to <EM>WINDOW</EM>s. 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 + <STRONG>--with-pthread</STRONG> + The configure script renames the library. All of the library + names have a "t" appended to them (before any "w" added by <STRONG>--enable-widec</STRONG>). The global variables such as <STRONG>LINES</STRONG> 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., <STRONG>libncurses.so</STRONG> and <STRONG>libncurses.a</STRONG>. The debug and - profiling libraries add a "_g" and a "_p" to the root names + <STRONG>--with-shared</STRONG> + <STRONG>--with-normal</STRONG> + <STRONG>--with-debug</STRONG> + <STRONG>--with-profile</STRONG> + The shared and normal (static) library names differ by their + suffixes, e.g., <STRONG>libncurses.so</STRONG> and <STRONG>libncurses.a</STRONG>. The debug and + profiling libraries add a "_g" and a "_p" to the root names respectively, e.g., <STRONG>libncurses_g.a</STRONG> and <STRONG>libncurses_p.a</STRONG>. - --with-termlib - Low-level functions which do not depend upon whether the library + <STRONG>--with-termlib</STRONG> + 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: - <STRONG>o</STRONG> <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG> - miscellaneous curses extensions + <STRONG>o</STRONG> <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG> - miscellaneous <EM>curses</EM> extensions - <STRONG>o</STRONG> <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> - <STRONG>curses</STRONG> input options + <STRONG>o</STRONG> <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> - <EM>curses</EM> input options - <STRONG>o</STRONG> <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG> - low-level <STRONG>curses</STRONG> routines + <STRONG>o</STRONG> <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG> - low-level <EM>curses</EM> routines - <STRONG>o</STRONG> <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG> - <STRONG>curses</STRONG> environment query routines + <STRONG>o</STRONG> <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG> - <EM>curses</EM> environment query routines - <STRONG>o</STRONG> <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG> - <STRONG>curses</STRONG> emulation of termcap + <STRONG>o</STRONG> <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG> - <EM>curses</EM> emulation of <EM>termcap</EM> - <STRONG>o</STRONG> <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> - <STRONG>curses</STRONG> interfaces to terminfo database + <STRONG>o</STRONG> <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> - <EM>curses</EM> interface to <EM>terminfo</EM> database - <STRONG>o</STRONG> <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> - miscellaneous <STRONG>curses</STRONG> utility routines + <STRONG>o</STRONG> <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> - miscellaneous <EM>curses</EM> utility routines - --with-trace - The <STRONG>trace</STRONG> function normally resides in the debug library, but it - is sometimes useful to configure this in the shared library. + <STRONG>--with-trace</STRONG> + The <STRONG>trace</STRONG> 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. </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE> - /usr/share/tabset - directory containing initialization files for the terminal - capability database /usr/share/terminfo terminal capability - database + <EM>/usr/share/tabset</EM> + tab stop initialization database + <EM>/usr/share/terminfo</EM> + compiled terminal capability database -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> and related pages whose names begin "curs_" for detailed - routine descriptions. - <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> - <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> for user-defined capabilities + +</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> + X/Open Curses permits most functions it specifies to be made available + as macros as well. <EM>ncurses</EM> does so + + <STRONG>o</STRONG> for functions that return values via their parameters, + + <STRONG>o</STRONG> to support obsolete features, + + <STRONG>o</STRONG> to reuse functions (for example, those that move the cursor before + another operation), and + + <STRONG>o</STRONG> a few special cases. + + If the standard output file descriptor of an <EM>ncurses</EM> 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 <EM>curses</EM>. + + See subsection "Header Files" below regarding symbols exposed by + inclusion of <EM>curses.h</EM>. </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> - The <STRONG>ncurses</STRONG> library can be compiled with an option (<STRONG>-DUSE_GETCAP</STRONG>) that - falls back to the old-style /etc/termcap file if the terminal setup - code cannot find a terminfo entry corresponding to <STRONG>TERM</STRONG>. Use of this - feature is not recommended, as it essentially includes an entire - termcap compiler in the <STRONG>ncurses</STRONG> startup code, at significant cost in - core and startup cycles. - - The <STRONG>ncurses</STRONG> library includes facilities for capturing mouse events on - certain terminals (including xterm). See the <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> manual - page for details. - - The <STRONG>ncurses</STRONG> library includes facilities for responding to window - resizing events, e.g., when running in an xterm. See the - <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> and <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> manual pages for details. In addition, - the library may be configured with a <STRONG>SIGWINCH</STRONG> handler. - - The <STRONG>ncurses</STRONG> library extends the fixed set of function key capabilities - of terminals by allowing the application designer to define additional - key sequences at runtime. See the <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>, and - <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG> manual pages for details. - - The <STRONG>ncurses</STRONG> library can exploit the capabilities of terminals which - implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an - application to reset the terminal to its original foreground and - background colors. From the users' perspective, the application is - able to draw colored text on a background whose color is set - independently, providing better control over color contrasts. See the - <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG> manual page for details. + <EM>ncurses</EM> enables an application to capture mouse events on certain + terminals, including <STRONG>xterm(1)</STRONG>; see <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>. - The <STRONG>ncurses</STRONG> library includes a function for directing application - output to a printer attached to the terminal device. See the - <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> manual page for details. + <EM>ncurses</EM> provides a means of responding to window resizing events, as + when running in a GUI terminal emulator application such as <EM>xterm</EM>; see + <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> and <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG>. + <EM>ncurses</EM> allows an application to query the terminal for the presence of + a wide variety of special keys; see <STRONG><A HREF="curs_getch.3x.html">has_key(3x)</A></STRONG>. -</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - The <STRONG>ncurses</STRONG> library is intended to be BASE-level conformant with XSI - Curses. The EXTENDED XSI Curses functionality (including color - support) is supported. + <EM>ncurses</EM> 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 <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>, <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>, + <STRONG><A HREF="keybound.3x.html">keybound(3x)</A></STRONG>, and <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG>. + + <EM>ncurses</EM> 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 <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>. - A small number of local differences (that is, individual differences - between the XSI Curses and <STRONG>ncurses</STRONG> calls) are described in <STRONG>PORTABILITY</STRONG> - sections of the library man pages. + An <EM>ncurses</EM> application can eschew knowledge of <EM>WINDOW</EM> structure + internals, instead using accessor functions such as <STRONG><A HREF="curs_opaque.3x.html">is_scrollok(3x)</A></STRONG>. + <EM>ncurses</EM> enables an application to direct application output to a + printer attached to the terminal device; see <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG>. -</PRE><H3><a name="h3-Error-checking">Error checking</a></H3><PRE> - In many cases, X/Open Curses is vague about error conditions, omitting - some of the SVr4 documentation. + <EM>ncurses</EM> offers <STRONG><A HREF="curs_slk.3x.html">slk_attr(3x)</A></STRONG> as a counterpart of <STRONG><A HREF="curs_attr.3x.html">attr_get(3x)</A></STRONG> for soft- + label key lines, and <STRONG><A HREF="curs_slk.3x.html">extended_slk_color(3x)</A></STRONG> as a form of <STRONG><A HREF="curs_slk.3x.html">slk_color(3x)</A></STRONG> + that can gather color information from them when many colors are + supported. - 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. + Some extensions are available only if <EM>ncurses</EM> permits modification of + <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>'s behavior; see <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG>. <EM>ncurses</EM> is compiled + to support them; section "ALTERNATE CONFIGURATIONS" describes how. + <STRONG>o</STRONG> Rudimentary support for multi-threaded applications may be + available; see <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>. -</PRE><H3><a name="h3-Extensions-versus-portability">Extensions versus portability</a></H3><PRE> - Most of the extensions provided by ncurses have not been standardized. - Some have been incorporated into other implementations, such as - PDCurses or NetBSD curses. Here are a few to consider: + <STRONG>o</STRONG> Functions that ease the management of multiple screens can be + exposed; see <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>. - <STRONG>o</STRONG> The routine <STRONG>has_key</STRONG> is not part of XPG4, nor is it present in SVr4. - See the <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> manual page for details. + <STRONG>o</STRONG> To aid applications to debug their memory usage, <EM>ncurses</EM> optionally + offers functions to more aggressively free memory it dynamically + allocates itself; see <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>. - <STRONG>o</STRONG> The routine <STRONG>slk_attr</STRONG> is not part of XPG4, nor is it present in - SVr4. See the <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> manual page for details. + <STRONG>o</STRONG> The library facilitates auditing and troubleshooting of its + behavior; see <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>. - <STRONG>o</STRONG> The routines <STRONG>getmouse</STRONG>, <STRONG>mousemask</STRONG>, <STRONG>ungetmouse</STRONG>, <STRONG>mouseinterval</STRONG>, and - <STRONG>wenclose</STRONG> relating to mouse interfacing are not part of XPG4, nor - are they present in SVr4. See the <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> manual page for - details. + <STRONG>o</STRONG> The compiler option <STRONG>-DUSE_GETCAP</STRONG> causes the library to fall back to + reading <EM>/etc/termcap</EM> if the terminal setup code cannot find a <EM>term-</EM> + <EM>info</EM> entry corresponding to <EM>TERM</EM>. Use of this feature is not + recommended, as it essentially includes an entire <EM>termcap</EM> compiler + in the <EM>ncurses</EM> startup code, at a cost in memory usage and + application launch latency. - <STRONG>o</STRONG> The routine <STRONG>mcprint</STRONG> was not present in any previous curses - implementation. See the <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> manual page for details. + <EM>PDCurses</EM> and NetBSD <EM>curses</EM> incorporate some <EM>ncurses</EM> extensions. + Individual man pages indicate where this is the case. - <STRONG>o</STRONG> The routine <STRONG>wresize</STRONG> is not part of XPG4, nor is it present in SVr4. - See the <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> manual page for details. - <STRONG>o</STRONG> The WINDOW structure's internal details can be hidden from - application programs. See <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> for the discussion of - <STRONG>is_scrollok</STRONG>, etc. +</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> + X/Open Curses defines two levels of conformance, "base" and "enhanced". + The latter includes several additional features, such as wide-character + and color support. <EM>ncurses</EM> intends base-level conformance with X/Open + Curses, and supports all features of its enhanced level except the + <STRONG>untic</STRONG> utility. - <STRONG>o</STRONG> This implementation can be configured to provide rudimentary - support for multi-threaded applications. See <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> for - details. + Differences between X/Open Curses and <EM>ncurses</EM> are documented in the + "PORTABILITY" sections of applicable man pages. - <STRONG>o</STRONG> This implementation can also be configured to provide a set of - functions which improve the ability to manage multiple screens. - See <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG> for details. +</PRE><H3><a name="h3-Error-Checking">Error Checking</a></H3><PRE> + In many cases, X/Open Curses is vague about error conditions, omitting + some of the SVr4 documentation. -</PRE><H3><a name="h3-Padding-differences">Padding differences</a></H3><PRE> - In historic curses versions, delays embedded in the capabilities <STRONG>cr</STRONG>, - <STRONG>ind</STRONG>, <STRONG>cub1</STRONG>, <STRONG>ff</STRONG> and <STRONG>tab</STRONG> 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. + Unlike other implementations, <EM>ncurses</EM> checks pointer parameters, such + as those to <EM>WINDOW</EM> 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. Relying on this (or some + other) extension adversely affects the portability of <EM>curses</EM> + applications. -</PRE><H3><a name="h3-Header-files">Header files</a></H3><PRE> - The header file <STRONG><curses.h></STRONG> automatically includes the header files - <STRONG><stdio.h></STRONG> and <STRONG><unctrl.h></STRONG>. +</PRE><H3><a name="h3-Padding-Differences">Padding Differences</a></H3><PRE> + In historical <EM>curses</EM> implementations, delays embedded in the <EM>terminfo</EM> + capabilities <STRONG>carriage_return</STRONG> (<STRONG>cr</STRONG>), <STRONG>scroll_forward</STRONG> (<STRONG>ind</STRONG>), <STRONG>cursor_left</STRONG> + (<STRONG>cub1</STRONG>), <STRONG>form_feed</STRONG> (<STRONG>ff</STRONG>), and <STRONG>tab</STRONG> (<STRONG>ht</STRONG>) activated corresponding delay bits + in the Unix terminal driver. <EM>ncurses</EM> 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. - X/Open Curses has more to say, but does not finish the story: - The inclusion of <curses.h> may make visible all symbols from the - headers <stdio.h>, <term.h>, <termios.h>, and <wchar.h>. +</PRE><H3><a name="h3-Header-Files">Header Files</a></H3><PRE> + The header file <EM>curses.h</EM> itself includes the header files <EM>stdio.h</EM> and + <EM>unctrl.h</EM>. - Here is a more complete story: + X/Open Curses has more to say, - <STRONG>o</STRONG> Starting with BSD curses, all implementations have included - <stdio.h>. + The inclusion of <EM>curses.h</EM> may make visible all symbols from the + headers <EM>stdio.h</EM>, <EM>term.h</EM>, <EM>termios.h</EM>, and <EM>wchar.h</EM>. - BSD curses included <curses.h> and <unctrl.h> from an internal - header "curses.ext" ("ext" was a short name for <EM>externs</EM>). + but does not finish the story. A more complete account follows. - BSD curses used <stdio.h> internally (for <STRONG>printw</STRONG> and <STRONG>scanw</STRONG>), but - nothing in <curses.h> itself relied upon <stdio.h>. + <STRONG>o</STRONG> Starting with 4BSD <EM>curses</EM> (1980) all implementations have provided + a <EM>curses.h</EM> file. - <STRONG>o</STRONG> SVr2 curses added <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>, which relies upon <stdio.h>. That - is, the function prototype uses <STRONG>FILE</STRONG>. + BSD <EM>curses</EM> code included <EM>curses.h</EM> and <EM>unctrl.h</EM> from an internal + header file <EM>curses.ext</EM>, where "ext" abbreviated "externs". - SVr4 curses added <STRONG>putwin</STRONG> and <STRONG>getwin</STRONG>, which also use <stdio.h>. + The implementations of <EM>printw</EM> and <EM>scanw</EM> used undocumented internal + functions of the standard I/O library (<STRONG>_</STRONG><EM>doprnt</EM> and <STRONG>_</STRONG><EM>doscan</EM>), but + nothing in <EM>curses.h</EM> itself relied upon <EM>stdio.h</EM>. - X/Open Curses documents all three of these functions. + <STRONG>o</STRONG> SVr2 <EM>curses</EM> added <EM>newterm</EM>, which relies upon <EM>stdio.h</EM> because its + function prototype employs the <EM>FILE</EM> type. - 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 <EM>curses</EM> added <EM>putwin</EM> and <EM>getwin</EM>, which also use <EM>stdio.h</EM>. - As a result, standard <curses.h> will always include <stdio.h>. + X/Open Curses specifies all three of these functions. - <STRONG>o</STRONG> X/Open Curses is inconsistent with respect to SVr4 regarding - <unctrl.h>. + SVr4 <EM>curses</EM> and X/Open Curses do not require the developer to + include <EM>stdio.h</EM> before <EM>curses.h</EM>. Both document use of <EM>curses</EM> as + requiring only <EM>curses.h</EM>. - As noted in <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, ncurses includes <unctrl.h> from - <curses.h> (like SVr4). + As a result, standard <EM>curses.h</EM> always includes <EM>stdio.h</EM>. - <STRONG>o</STRONG> X/Open's comments about <term.h> and <termios.h> may refer to HP-UX - and AIX: + <STRONG>o</STRONG> X/Open Curses and SVr4 <EM>curses</EM> are inconsistent with respect to + <EM>unctrl.h</EM>. - HP-UX curses includes <term.h> from <curses.h> to declare <STRONG>setupterm</STRONG> - in curses.h, but ncurses (and Solaris curses) do not. + As noted in <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, <EM>ncurses</EM> includes <EM>unctrl.h</EM> from <EM>curses.h</EM> + (as SVr4 does). - AIX curses includes <term.h> and <termios.h>. Again, ncurses (and - Solaris curses) do not. + <STRONG>o</STRONG> X/Open Curses's comments about <EM>term.h</EM> and <EM>termios.h</EM> may refer to + HP-UX and AIX. - <STRONG>o</STRONG> X/Open says that <curses.h> <EM>may</EM> include <term.h>, but there is no - requirement that it do that. + HP-UX <EM>curses</EM> includes <EM>term.h</EM> from <EM>curses.h</EM> to declare <EM>setupterm</EM> in + <EM>curses.h</EM>, but <EM>ncurses</EM> and Solaris <EM>curses</EM> do not. - 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>. + AIX <EM>curses</EM> includes <EM>term.h</EM> and termios.h<EM>.</EM> Again, <EM>ncurses</EM> and + Solaris <EM>curses</EM> do not. - 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>. + <STRONG>o</STRONG> X/Open Curses says that <EM>curses.h</EM> <STRONG>may</STRONG> include <EM>term.h</EM>, but does not + require it to do so. - <STRONG>o</STRONG> X/Open Curses says <EM>"may</EM> <EM>make</EM> <EM>visible"</EM> because including a header - file does not necessarily make all symbols in it visible (there are - ifdef's to consider). + Some programs use functions declared in both <EM>curses.h</EM> and <EM>term.h</EM>, + and must include both header files in the same module. Very old + versions of AIX <EM>curses</EM> required inclusion of <EM>curses.h</EM> before + <EM>term.h</EM>. - For instance, in ncurses <wchar.h> <EM>may</EM> 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 <STRONG>_XOPEN_SOURCE</STRONG> feature - test macro. + The header files supplied by <EM>ncurses</EM> include the standard library + headers required for its declarations, so <EM>ncurses</EM>'s own header + files can be included in any order. But for portability, you + should include <EM>curses.h</EM> before <EM>term.h</EM>. - <STRONG>o</STRONG> X/Open Curses documents one required header, in a special case: - <stdarg.h> before <curses.h> to prototype the <STRONG>vw_printw</STRONG> and - <STRONG>vw_scanw</STRONG> functions (as well as the obsolete the <STRONG>vwprintw</STRONG> and - <STRONG>vwscanw</STRONG> functions). Each of those uses a <STRONG>va_list</STRONG> parameter. + <STRONG>o</STRONG> X/Open Curses says "may make visible" because including a header + file does not necessarily make visible all of the symbols in it + (consider <STRONG>#ifdef</STRONG> and similar). - 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 <STRONG>void*</STRONG> for the <STRONG>va_list</STRONG> 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>. + For instance, <EM>ncurses</EM>'s <EM>curses.h</EM> <STRONG>may</STRONG> include <EM>wchar.h</EM> if the proper + symbol is defined, and if <EM>ncurses</EM> is configured for wide-character + support. If <EM>wchar.h</EM> is included, its symbols <STRONG>may</STRONG> be made visible + depending on the value of the <STRONG>_XOPEN_SOURCE</STRONG> feature test macro. - 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. + <STRONG>o</STRONG> X/Open Curses mandates an application's inclusion of one standard C + library header in a special case: <EM>stdarg.h</EM> before <EM>curses.h</EM> to + prototype the functions <EM>vw</EM><STRONG>_</STRONG><EM>printw</EM> and <EM>vw</EM><STRONG>_</STRONG><EM>scanw</EM> (as well as the + obsolete <EM>vwprintw</EM> and <EM>vwscanw</EM>). Each of these takes a variadic + argument list, a <EM>va</EM><STRONG>_</STRONG><EM>list</EM> parameter, like that of <STRONG>printf(3)</STRONG>. + SVr3 <EM>curses</EM> introduced the two obsolete functions, and X/Open + Curses the others. In between, SVr4 <EM>curses</EM> provided for the + possibility that an application might include either <EM>varargs.h</EM> or + <EM>stdarg.h</EM>. These represented contrasting approaches to handling + variadic argument lists. The older interface, <EM>varargs.h</EM>, used a + pointer to <EM>char</EM> for variadic functions' <EM>va</EM><STRONG>_</STRONG><EM>list</EM> parameter. Later, + the list acquired its own standard data type, <EM>va</EM><STRONG>_</STRONG><EM>list</EM>, defined in + <EM>stdarg.h</EM>, empowering the compiler to check the types of a function + call's actual parameters against the formal ones declared in its + prototype. -</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - If standard output from a <STRONG>ncurses</STRONG> program is re-directed to something - which is not a tty, screen updates will be directed to standard error. - This was an undocumented feature of AT&T System V Release 3 curses. + No conforming implementations of X/Open Curses require an + application to include <EM>stdarg.h</EM> before <EM>curses.h</EM> because they either + have allowed for a special type, or, like <EM>ncurses</EM>, they include + <EM>stdarg.h</EM> themselves to provide a portable interface. </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> - Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. Based on pcurses + Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. Based on <EM>pcurses</EM> by Pavel Curtis. +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> + - <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> + +ncurses 6.5 2024-04-27 <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -1484,18 +1484,19 @@ <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> <li><a href="#h2-DESCRIPTION">DESCRIPTION</a> <ul> +<li><a href="#h3-Application-Structure">Application Structure</a></li> +<li><a href="#h3-Overview">Overview</a></li> <li><a href="#h3-Initialization">Initialization</a></li> -<li><a href="#h3-Datatypes">Datatypes</a></li> -<li><a href="#h3-Environment-variables">Environment variables</a></li> -<li><a href="#h3-Routine-and-Argument-Names">Routine and Argument Names</a></li> -<li><a href="#h3-Routine-Name-Index">Routine Name Index</a></li> +<li><a href="#h3-Naming-Conventions">Naming Conventions</a></li> +<li><a href="#h3-Wide-and-Non-wide-Character-Configurations">Wide and Non-wide Character Configurations</a></li> +<li><a href="#h3-Function-Name-Index">Function Name Index</a></li> </ul> </li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-ENVIRONMENT">ENVIRONMENT</a> <ul> -<li><a href="#h3-CC-command-character">CC command-character</a></li> <li><a href="#h3-BAUDRATE">BAUDRATE</a></li> +<li><a href="#h3-CC-_command-character_">CC (command character)</a></li> <li><a href="#h3-COLUMNS">COLUMNS</a></li> <li><a href="#h3-ESCDELAY">ESCDELAY</a></li> <li><a href="#h3-HOME">HOME</a></li> @@ -1519,18 +1520,17 @@ </li> <li><a href="#h2-ALTERNATE-CONFIGURATIONS">ALTERNATE CONFIGURATIONS</a></li> <li><a href="#h2-FILES">FILES</a></li> -<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> +<li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a> <ul> -<li><a href="#h3-Error-checking">Error checking</a></li> -<li><a href="#h3-Extensions-versus-portability">Extensions versus portability</a></li> -<li><a href="#h3-Padding-differences">Padding differences</a></li> -<li><a href="#h3-Header-files">Header files</a></li> +<li><a href="#h3-Error-Checking">Error Checking</a></li> +<li><a href="#h3-Padding-Differences">Padding Differences</a></li> +<li><a href="#h3-Header-Files">Header Files</a></li> </ul> </li> -<li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-AUTHORS">AUTHORS</a></li> +<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> </BODY> |