- 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-
+ 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, getmaxyx. The
- return values of setscrreg, wsetscrreg, getyx, getbegyx,
- and getmaxyx are undefined (i.e., these should not be used
+ 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 customiz-
- ing the runtime behavior of the ncurses library. The most
+ 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 ter-
+ (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 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. 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,
+ 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 char-
- acter 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:
@@ -602,13 +838,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
@@ -616,10 +851,36 @@
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
+ default_colors(3x)). You may set the foreground and
+ background color values with this environment vari-
+ able by proving a 2-element list: foreground,back-
+ ground. 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 posi-
+ tive value from zero to the terminfo max_colors 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.
@@ -645,53 +906,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 ter-
+ 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
+ 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 term-
- cap 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
@@ -701,162 +981,211 @@
- one or more directories whose names are configured
and compiled into the ncurses library, e.g.,
- @DATADIR@/terminfo
+ /usr/share/terminfo
TERMINFO_DIRS
- Specifies a list of directories to search for termi-
- nal 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
+ If TERMCAP does not hold a file name then ncurses
checks the TERMPATH symbol. This is a list of file-
- names separated by colons (i.e., ":"). If the
- TERMPATH symbol is not set, ncurses looks in the
- files /etc/termcap, /usr/share/misc/termcap and
- $HOME/.termcap, in that order.
+ names 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
+ 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.
+
+
+
+
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
+ structure 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 libn-
+ curses.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/term-
+ 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
+ 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
+ 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 ncurses library includes facilities for capturing
+ mouse events on certain terminals (including xterm). See
+ 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 termi-
+ 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 use_default_colors(3x) manual page for details.
+ ored text on a background whose color is set
+ independently, providing better control over color con-
+ trasts. 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.
+ 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, addnw-
- str, 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, kill-
- wchar, mvadd_wch, mvadd_wchnstr, mvadd_wchstr, mvaddnwstr,
- mvaddwstr, mvget_wch, mvget_wstr, mvgetn_wstr, mvh-
- line_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, mvwv-
- line_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,
+ The ncurses library is intended to be BASE-level confor-
+ mant with XSI Curses. The EXTENDED XSI Curses functional-
+ ity (including color support) is supported.
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
+ 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.
+ This implementation also contains several extensions:
- The routine slk_attr is not part of XPG4, nor is it pre-
- sent in SVr4. See the curs_slk(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 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 slk_attr is not part of XPG4, nor is it
+ present in SVr4. See the curs_slk(3x) manual page
+ for details.
- The routine mcprint was not present in any previous curses
- implementation. See the curs_print(3x) manual page for
- details.
+ The routines getmouse, mousemask, ungetmouse, mou-
+ seinterval, and wenclose relating to mouse interfac-
+ ing 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 details.
- The routine wresize is not part of XPG4, nor is it present
- in SVr4. See the wresize(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.
+
+ The WINDOW structure's internal details can be hidden
+ from application programs. See curs_opaque(3x) for
+ the discussion of is_scrollok, etc.
In historic curses versions, delays embedded in the capa-
- bilities cr, ind, cub1, ff and tab activated corresponding
+ 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.
-
- 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 declara-
- tion 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.
+ tion, all padding is done by sending NUL bytes. This
+ method is slightly more expensive, but narrows the inter-
+ face 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
+ 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.
@@ -869,25 +1198,7 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+ ncurses(3x)