- Routines that return an integer return ERR upon failure
- and an integer value other than ERR upon successful
- completion, unless otherwise noted in the routine
- descriptions.
-
- All macros return the value of the w version, except
- setscrreg, wsetscrreg, getyx, getbegyx, getmaxyx. The
- return values of setscrreg, wsetscrreg, getyx, getbegyx,
- and getmaxyx are undefined (i.e., these should not be used
+ Routines that return an integer return ERR upon failure
+ and an integer value other than ERR upon successful com-
+ pletion, unless otherwise noted in the routine descrip-
+ tions.
+
+ All macros return the value of the w version, except
+ setscrreg, wsetscrreg, getyx, getbegyx, and getmaxyx. The
+ return values of setscrreg, wsetscrreg, getyx, getbegyx,
+ and getmaxyx are undefined (i.e., these should not be used
as the right-hand side of assignment statements).
- Routines that return pointers return NULL on error.
+ Routines that return pointers return NULL on error.
ENVIRONMENT
- The following environment symbols are useful for
- customizing the runtime behavior of the ncurses library.
- The most important ones have been already discussed in
- detail.
+ The following environment symbols are useful for customiz-
+ ing the runtime behavior of the ncurses library. The most
+ important ones have been already discussed in detail.
BAUDRATE
- The debugging library checks this environment symbol
+ The debugging library checks this environment symbol
when the application has redirected output to a file.
- The symbol's numeric value is used for the baudrate.
- If no value is found ncurses uses 9600. This allows
- testers to construct repeatable test-cases that take
+ The symbol's numeric value is used for the baudrate.
+ If no value is found, ncurses uses 9600. This allows
+ testers to construct repeatable test-cases that take
into account costs that depend on baudrate.
CC When set, change occurrences of the command_character
- (i.e., the cmdch capability) of the loaded terminfo
- entries to the value of this symbol. Very few
- terminfo entries provide this feature.
+ (i.e., the cmdch capability) of the loaded terminfo
+ entries to the value of this symbol. Very few ter-
+ minfo entries provide this feature.
COLUMNS
Specify the width of the screen in characters.
- Applications running in a windowing environment
- usually are able to obtain the width of the window in
- which they are executing. If neither the $COLUMNS
- value nor the terminal's screen size is available,
- ncurses uses the size which may be specified in the
- terminfo database (i.e., the cols capability).
-
- It is important that your application use a correct
- size for the screen. However, 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.
-
- Either COLUMNS or LINES symbols may be specified
- independently. This is mainly useful to circumvent
- legacy misfeatures of terminal descriptions, e.g.,
+ Applications running in a windowing environment usu-
+ ally are able to obtain the width of the window in
+ which they are executing. If neither the COLUMNS
+ value nor the terminal's screen size is available,
+ ncurses uses the size which may be specified in the
+ terminfo database (i.e., the cols capability).
+
+ It is important that your application use a correct
+ size for the screen. This is not always possible
+ because your application may be running on a host
+ which does not honor NAWS (Negotiations About Window
+ Size), or because you are temporarily running as
+ another user. However, setting COLUMNS and/or LINES
+ overrides the library's use of the screen size
+ obtained from the operating system.
+
+ Either COLUMNS or LINES symbols may be specified
+ independently. This is mainly useful to circumvent
+ legacy misfeatures of terminal descriptions, e.g.,
xterm which commonly specifies a 65 line screen. For
- best results, lines and cols should not be specified
+ best results, lines and cols should not be specified
in a terminal description for terminals which are run
as emulations.
- Use the use_env function to disable this feature.
+ Use the use_env function to disable all use of exter-
+ nal environment (including system calls) to determine
+ the screen size.
ESCDELAY
- 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.
+ 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 vari-
+ able to accommodate unusual applications.
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.
+ 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
+ Note that xterm mouse events are built up from char-
+ acter 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
+ may wish to lengthen this default value because the
+ timeout applies to the composed multi-click event as
well as the individual clicks.
- HOME Tells ncurses where your home directory is. That is
+ In addition to the environment variable, this imple-
+ mentation 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 applica-
+ tion.
+
+ HOME Tells ncurses where your home directory is. That is
where it may read and write auxiliary terminal
descriptions:
@@ -604,12 +754,12 @@
$HOME/.terminfo
LINES
- Like COLUMNS, specify the height of the screen in
- characters. See COLUMNS for a detailed description.
+ Like COLUMNS, specify the height of the screen in
+ characters. See COLUMNS for a detailed description.
MOUSE_BUTTONS_123
This applies only to the OS/2 EMX port. It specifies
- the order of buttons on the mouse. OS/2 numbers a
+ the order of buttons on the mouse. OS/2 numbers a
3-button mouse inconsistently from other platforms:
1 = left
@@ -617,27 +767,53 @@
3 = middle.
This symbol lets you customize the mouse. The symbol
- must be three numeric digits 1-3 in any order, e.g.,
- 123 or 321. If it is not specified, ncurses uses
+ must be three numeric digits 1-3 in any order, e.g.,
+ 123 or 321. If it is not specified, ncurses uses
132.
+ NCURSES_ASSUMED_COLORS
+ Override the compiled-in assumption that the termi-
+ nal's default colors are white-on-black (see
+ assume_default_colors(3x)). You may set the fore-
+ ground and background color values with this environ-
+ ment variable by proving a 2-element list:
+ foreground,background. For example, to tell ncurses
+ to not assume anything about the colors, set this to
+ "-1,-1". To make it green-on-black, set it to "2,0".
+ Any positive value from zero to the terminfo max_col-
+ ors value is allowed.
+
+ NCURSES_NO_HARD_TABS
+ Ncurses 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 stty settings to avoid the problem.
+
+ NCURSES_NO_MAGIC_COOKIES
+ 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 termi-
+ nals by setting this environment variable.
+
NCURSES_NO_PADDING
Most of the terminal descriptions in the terminfo
database are written for real "hardware" terminals.
Many people use terminal emulators which run in a
- windowing environment and use curses-based
- applications. Terminal emulators can duplicate all
- of the important aspects of a hardware terminal, but
- they do not have the same limitations. The chief
- limitation of a hardware terminal from the standpoint
- of your application is the management of dataflow,
- i.e., timing. Unless a hardware terminal is
- interfaced into a terminal concentrator (which does
- flow control), it (or your application) must manage
- dataflow, preventing overruns. The cheapest solution
- (no hardware cost) is for your program to do this by
- pausing after operations that the terminal does
- slowly, such as clearing the display.
+ windowing environment and use curses-based applica-
+ tions. 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., tim-
+ ing. Unless a hardware terminal is interfaced into a
+ terminal concentrator (which does flow control), it
+ (or your application) must manage dataflow, prevent-
+ ing 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
@@ -646,53 +822,72 @@
Set the NCURSES_NO_PADDING symbol to disable all but
mandatory padding. Mandatory padding is used as a
- part of special control sequences such as flash.
+ part of special control sequences such as flash.
NCURSES_NO_SETBUF
- Normally ncurses enables buffered output during
- terminal initialization. This is done (as in SVr4
- curses) for performance reasons. For testing
- purposes, both of ncurses and certain applications,
- this feature is made optional. Setting the
+ Normally ncurses enables buffered output during ter-
+ minal initialization. This is done (as in SVr4
+ curses) for performance reasons. For testing pur-
+ poses, both of ncurses and certain applications, this
+ feature is made optional. Setting the
NCURSES_NO_SETBUF variable disables output buffering,
leaving the output in the original (usually line
buffered) mode.
+ NCURSES_NO_UTF8_ACS
+ During initialization, the ncurses library checks for
+ special cases where VT100 line-drawing (and the cor-
+ responding alternate character set capabilities)
+ described in the terminfo are known to be missing.
+ Specifically, when running in a UTF-8 locale, the
+ Linux console emulator and the GNU screen program
+ ignore these. Ncurses checks the TERM environment
+ variable for these. For other special cases, you
+ should set this environment variable. Doing this
+ tells ncurses to use Unicode values which correspond
+ to the VT100 line-drawing glyphs. That works for the
+ special cases cited, and is likely to work for termi-
+ nal emulators.
+
+ When setting this variable, you should set it to a
+ nonzero value. Setting it to zero (or to a nonnum-
+ ber) disables the special check for Linux and screen.
+
NCURSES_TRACE
- During initialization, the ncurses debugging library
- checks the NCURSES_TRACE symbol. If it is defined,
- to a numeric value, ncurses calls the trace function,
+ During initialization, the ncurses debugging library
+ checks the NCURSES_TRACE symbol. If it is defined,
+ to a numeric value, ncurses calls the trace function,
using that value as the argument.
- The argument values, which are defined in curses.h,
- provide several types of information. When running
- with traces enabled, your application will write the
- file trace to the current directory.
+ The argument values, which are defined in curses.h,
+ provide several types of information. When running
+ with traces enabled, your application will write the
+ file trace to the current directory.
- TERM Denotes your terminal type. Each terminal type is
+ TERM Denotes your terminal type. Each terminal type is
distinct, though many are similar.
TERMCAP
- If the ncurses library has been configured with
- termcap support, ncurses will check for a terminal's
+ If the ncurses library has been configured with term-
+ cap support, ncurses will check for a terminal's
description in termcap form if it is not available in
the terminfo database.
- The TERMCAP symbol contains either a terminal
- description (with newlines stripped out), or a file
- name telling where the information denoted by the
- TERM symbol exists. In either case, setting it
- directs ncurses to ignore the usual place for this
+ The TERMCAP symbol contains either a terminal
+ description (with newlines stripped out), or a file
+ name telling where the information denoted by the
+ TERM symbol exists. In either case, setting it
+ directs ncurses to ignore the usual place for this
information, e.g., /etc/termcap.
TERMINFO
- Overrides the directory in which ncurses searches for
+ Overrides the directory in which ncurses searches for
your terminal description. This is the simplest, but
- not the only way to change the list of directories.
+ not the only way to change the list of directories.
The complete list of directories in order follows:
- - the last directory to which ncurses wrote, if any,
- is searched first.
+ - the last directory to which ncurses wrote, if any,
+ is searched first
- the directory specified by the TERMINFO symbol
@@ -705,19 +900,20 @@
/usr/share/terminfo
TERMINFO_DIRS
- Specifies a list of directories to search for
- terminal descriptions. The list is separated by
- colons (i.e., ":"). All of the terminal descriptions
- are in terminfo form, which makes a subdirectory
- named for the first letter of the terminal names
- therein.
+ Specifies a list of directories to search for termi-
+ nal descriptions. The list is separated by colons
+ (i.e., ":") on Unix, semicolons on OS/2 EMX. All of
+ the terminal descriptions are in terminfo form, which
+ makes a subdirectory named for the first letter of
+ the terminal names therein.
TERMPATH
- If TERMCAP does not hold a file name then ncurses
- checks the TERMPATH symbol. This is a list of
- filenames separated by colons (i.e., ":"). If the
- TERMPATH symbol is not set, ncurses looks in the
- files /etc/termcap, /usr/share/misc/termcap and
+ If TERMCAP does not hold a file name then ncurses
+ checks the TERMPATH symbol. This is a list of
+ filenames separated by spaces or colons (i.e., ":")
+ on Unix, semicolons on OS/2 EMX. If the TERMPATH
+ symbol is not set, ncurses 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
@@ -726,169 +922,190 @@
$TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
+
+
ALTERNATE CONFIGURATIONS
+ Several different configurations are possible, depending
+ on the configure script options used when building
+ ncurses. There are a few main options whose effects are
+ visible to the applications developer using ncurses:
+
+ --disable-overwrite
+ The standard include for ncurses is as noted in SYN-
+ OPSIS:
+
+ #include<curses.h>
+
+ This option is used to avoid filename conflicts when
+ ncurses is not the main implementation of curses of
+ the computer. If ncurses is installed disabling
+ overwrite, it puts its headers in a subdirectory,
+ e.g.,
+
+ #include<ncurses/curses.h>
+
+ It also omits a symbolic link which would allow you
+ to use -lcurses to build executables.
+
+ --enable-widec
+ The configure script renames the library and (if the
+ --disable-overwrite option is used) puts the header
+ files in a different subdirectory. All of the
+ library names have a "w" appended to them, i.e.,
+ instead of
+
+ -lncurses
+
+ you link with
+
+ -lncursesw
+
+ You must also define _XOPEN_SOURCE_EXTENDED when com-
+ piling for the wide-character library to use the
+ extended (wide-character) functions. The curses.h
+ 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 WINDOW struc-
+ ture differs, and very few applications require more
+ than a pointer to WINDOWs. If the headers are
+ installed allowing overwrite, the wide-character
+ library's headers should be installed last, to allow
+ applications to be built using either library from
+ the same set of headers.
+
+ --with-shared
+
+ --with-normal
+
+ --with-debug
+
+ --with-profile
+ The shared and normal (static) library names differ
+ by their suffixes, e.g., libncurses.so and
+ libncurses.a. The debug and profiling libraries add
+ a "_g" and a "_p" to the root names respectively,
+ e.g., libncurses_g.a and libncurses_p.a.
+
+ --with-trace
+ The trace function normally resides in the debug
+ library, but it is sometimes useful to configure this
+ in the shared library. Configure scripts should
+ check for the function's existence rather than assum-
+ ing it is always in the debug library.
+
+
- terminfo(5) and 3x pages whose names begin "curs_" for
- detailed routine descriptions.
+ terminfo(5) and related pages whose names begin "curs_"
+ for detailed routine descriptions.
EXTENSIONS
- The ncurses library can be compiled with an option
- (-DUSE_GETCAP) that falls back to the old-style
- /etc/termcap file if the terminal setup code cannot find a
- terminfo entry corresponding to TERM. Use of this feature
- is not recommended, as it essentially includes an entire
- termcap compiler in the ncurses startup code, at
- significant cost in core and startup cycles.
-
- The ncurses library includes facilities for capturing
+ The ncurses library can be compiled with an option
+ (-DUSE_GETCAP) that falls back to the old-style /etc/term-
+ cap file if the terminal setup code cannot find a terminfo
+ entry corresponding to TERM. Use of this feature is not
+ recommended, as it essentially includes an entire termcap
+ compiler in the ncurses startup code, at significant cost
+ in core and startup cycles.
+
+ The ncurses library includes facilities for capturing
mouse events on certain terminals (including xterm). See
- the curs_mouse(3x) manual page for details.
+ the curs_mouse(3x) manual page for details.
- The ncurses library includes facilities for responding to
+ The ncurses library includes facilities for responding to
window resizing events, e.g., when running in an xterm.
- See the resizeterm(3x) and wresize(3x) manual pages for
+ See the resizeterm(3x) and wresize(3x) manual pages for
details. In addition, the library may be configured with
a SIGWINCH handler.
- The ncurses library extends the fixed set of function key
+ The ncurses 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 define_key(3x) and keyok(3x) manual pages for
- details.
+ See the define_key(3x)key_defined(3x), and keyok(3x) man-
+ ual pages for details.
- The ncurses 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 use_default_colors(3x) manual page for
- details.
- The ncurses library includes a function for directing
- application output to a printer attached to the terminal
- device. See the curs_print(3x) manual page for details.
+ The ncurses library can exploit the capabilities of termi-
+ nals which implement the ISO-6429 SGR 39 and SGR 49 con-
+ trols, 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 col-
+ ored text on a background whose color is set indepen-
+ dently, providing better control over color contrasts.
+ See the default_colors(3x) manual page for details.
+
+ The ncurses library includes a function for directing
+ application output to a printer attached to the terminal
+ device. See the curs_print(3x) manual page for details.
PORTABILITY
- The ncurses library is intended to be BASE-level
- conformant with the XSI Curses standard. Certain portions
- of the EXTENDED XSI Curses functionality (including color
- support) are supported. The following EXTENDED XSI Curses
- calls in support of wide (multibyte) characters are not
- yet implemented: add_wch, add_wchnstr, add_wchstr,
- addnwstr, addwstr, bkgrnd, bkgrndset, border_set, box_set,
- echo_wchar, erasewchar, get_wch, get_wstr, getbkgrnd,
- getcchar, getn_wstr, getwchtype, hline_set, in_wch,
- in_wchnstr, in_wchstr, innwstr, ins_nwstr, ins_wch,
- ins_wstr, inwchnstr, inwchstr, inwstr, key_name,
- killwchar, mvadd_wch, mvadd_wchnstr, mvadd_wchstr,
- mvaddnwstr, mvaddwstr, mvget_wch, mvget_wstr, mvgetn_wstr,
- mvhline_set, mvin_wch, mvinnwstr, mvins_nwstr, mvins_wch,
- mvins_wstr, mvinwchnstr, mvinwchstr, mvinwchstr, mvinwstr,
- mvvline_set, mvwadd_wch, mvwadd_wchnstr, mvwadd_wchstr,
- mvwaddnwstr, mvwaddwstr, mvwget_ch, mvwget_wch,
- mvwget_wstr, mvwgetn_wstr, mvwhline_set, mvwin_wch,
- mvwin_wchnstr, mvwin_wchstr, mvwinnwstr, mvwins_nwstr,
- mvwins_wch, mvwins_wstr, mvwinwchnstr. mvwinwstr,
- mvwvline_set, pecho_wchar, setcchar, slk_wset, term_attrs,
- unget_wch, vhline_set, vid_attr, vid_puts, vline_set,
- wadd_wch, wadd_wchnstr, wadd_wchstr, waddnwstr, waddwstr,
- waddwstr, wbkgrnd, wbkgrndset, wbkgrndset, wborder_set,
- wecho_wchar, wecho_wchar, wget_wch, wget_wstr, wgetbkgrnd,
- wgetn_wstr, whline_set, win_wch, win_wchnstr, win_wchstr,
- winnwstr, wins_nwstr, wins_wch, wins_wstr, winwchnstr,
- winwchstr, winwstr, wunctrl, wvline_set,
-
- A small number of local differences (that is, individual
- differences between the XSI Curses and ncurses calls) are
- described in PORTABILITY sections of the library man
+ The ncurses library is intended to be BASE-level confor-
+ mant with the XSI Curses standard. The EXTENDED XSI
+ Curses functionality (including color support) is sup-
+ ported.
+
+ A small number of local differences (that is, individual
+ differences between the XSI Curses and ncurses calls) are
+ described in PORTABILITY sections of the library man
pages.
- The routine has_key is not part of XPG4, nor is it present
- in SVr4. See the curs_getch(3x) manual page for details.
+ The routine has_key is not part of XPG4, nor is it present
+ in SVr4. See the curs_getch(3x) manual page for details.
- The routine slk_attr is not part of XPG4, nor is it
- present in SVr4. See the curs_slk(3x) manual page for
+ The routine slk_attr is not part of XPG4, nor is it
+ present in SVr4. See the curs_slk(3x) manual page for
details.
- The routines getmouse, mousemask, ungetmouse,
- mouseinterval, and wenclose relating to mouse interfacing
- are not part of XPG4, nor are they present in SVr4. See
- the curs_mouse(3x) manual page for details.
+ The routines getmouse, mousemask, ungetmouse, mouseinter-
+ val, and wenclose relating to mouse interfacing are not
+ part of XPG4, nor are they present in SVr4. See the
+ curs_mouse(3x) manual page for details.
- The routine mcprint was not present in any previous curses
- implementation. See the curs_print(3x) manual page for
+ The routine mcprint was not present in any previous curses
+ implementation. See the curs_print(3x) manual page for
details.
- The routine wresize is not part of XPG4, nor is it present
- in SVr4. See the wresize(3x) manual page for details.
-
- In historic curses versions, delays embedded in the
- capabilities cr, ind, cub1, ff and tab activated
- corresponding delay bits in the UNIX tty driver. In this
- implementation, all padding is done by NUL sends. This
- method is slightly more expensive, but narrows the
- interface to the UNIX kernel significantly and increases
- the package's portability correspondingly.
-
- In the XSI standard and SVr4 manual pages, many entry
- points have prototype arguments of the for char*const (or
- cchar_t*const, or wchar_t*const, or void*const).
- Depending on one's interpretation of the ANSI C standard
- (see section 3.5.4.1), these declarations are either (a)
- meaningless, or (b) meaningless and illegal. The
- declaration constchar*x is a modifiable pointer to
- unmodifiable data, but char*constx' is an unmodifiable
- pointer to modifiable data. Given that C passes arguments
- by value, <type>*const as a formal type is at best
- dubious. Some compilers choke on the prototypes.
- Therefore, in this implementation, they have been changed
- to const<type>* globally.
+
+ The routine wresize is not part of XPG4, nor is it present
+ in SVr4. See the wresize(3x) manual page for details.
+
+ In historic curses versions, delays embedded in the capa-
+ bilities cr, ind, cub1, ff and tab activated corresponding
+ delay bits in the UNIX tty driver. In this implementa-
+ tion, all padding is done by NUL sends. This method is
+ slightly more expensive, but narrows the interface to the
+ UNIX kernel significantly and increases the package's
+ portability correspondingly.
NOTES
- The header file <curses.h> automatically includes the
- header files <stdio.h> and <unctrl.h>.
+ The header file <curses.h> automatically includes the
+ header files <stdio.h> and <unctrl.h>.
- If standard output from a ncurses 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.
+ If standard output from a ncurses program is re-directed
+ to something which is not a tty, screen updates will be
+ directed to standard error. This was an undocumented fea-
+ ture of AT&T System V Release 3 curses.
AUTHORS
- Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
+ Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
Based on pcurses by Pavel Curtis.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+ ncurses(3x)