1558 lines
56 KiB
Plaintext
1558 lines
56 KiB
Plaintext
'\" t
|
|
.\"***************************************************************************
|
|
.\" Copyright 2018-2020,2021 Thomas E. Dickey *
|
|
.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. *
|
|
.\" *
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining a *
|
|
.\" copy of this software and associated documentation files (the *
|
|
.\" "Software"), to deal in the Software without restriction, including *
|
|
.\" without limitation the rights to use, copy, modify, merge, publish, *
|
|
.\" distribute, distribute with modifications, sublicense, and/or sell *
|
|
.\" copies of the Software, and to permit persons to whom the Software is *
|
|
.\" furnished to do so, subject to the following conditions: *
|
|
.\" *
|
|
.\" The above copyright notice and this permission notice shall be included *
|
|
.\" in all copies or substantial portions of the Software. *
|
|
.\" *
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
|
|
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
|
|
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
|
|
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
|
|
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
|
|
.\" *
|
|
.\" Except as contained in this notice, the name(s) of the above copyright *
|
|
.\" holders shall not be used in advertising or otherwise to promote the *
|
|
.\" 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 $
|
|
.hy 0
|
|
.TH ncurses 3X ""
|
|
.ie \n(.g .ds `` \(lq
|
|
.el .ds `` ``
|
|
.ie \n(.g .ds '' \(rq
|
|
.el .ds '' ''
|
|
.de bP
|
|
.ie n .IP \(bu 4
|
|
.el .IP \(bu 2
|
|
..
|
|
.de NS
|
|
.ie n .sp
|
|
.el .sp .5
|
|
.ie n .in +4
|
|
.el .in +2
|
|
.nf
|
|
.ft C \" Courier
|
|
..
|
|
.de NE
|
|
.fi
|
|
.ft R
|
|
.ie n .in -4
|
|
.el .in -2
|
|
..
|
|
.ds n 5
|
|
.ds d @TERMINFO@
|
|
.SH NAME
|
|
\fBncurses\fR \- CRT screen handling and optimization package
|
|
.SH SYNOPSIS
|
|
\fB#include <curses.h>\fR
|
|
.br
|
|
.SH DESCRIPTION
|
|
The \fBncurses\fR 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 \fBncurses\fR
|
|
version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
|
|
.PP
|
|
The \fBncurses\fR 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 \fBncurses\fR library is freely redistributable in source form.
|
|
Differences from the SVr4
|
|
curses are summarized under the
|
|
\fBEXTENSIONS\fP and \fBPORTABILITY\fP sections below and
|
|
described in detail in the respective
|
|
\fBEXTENSIONS\fP, \fBPORTABILITY\fP and \fBBUGS\fP sections
|
|
of individual man pages.
|
|
.PP
|
|
The \fBncurses\fR 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.
|
|
.PP
|
|
A program using these routines must be linked with the \fB\-lncurses\fR option,
|
|
or (if it has been generated) with the debugging library \fB\-lncurses_g\fR.
|
|
(Your system integrator may also have installed these libraries under
|
|
the names \fB\-lcurses\fR and \fB\-lcurses_g\fR.)
|
|
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 \fBALTERNATE CONFIGURATIONS\fP.
|
|
.PP
|
|
The \fBncurses\fR package supports: overall screen, window and pad
|
|
manipulation; output to windows and pads; reading terminal input; control over
|
|
terminal and \fBcurses\fR input and output options; environment query
|
|
routines; color manipulation; use of soft label keys; terminfo capabilities;
|
|
and access to low-level terminal-manipulation routines.
|
|
.SS Initialization
|
|
.PP
|
|
The library uses the locale which the calling program has initialized.
|
|
That is normally done with \fBsetlocale\fP:
|
|
.NS
|
|
\fBsetlocale(LC_ALL, "");\fP
|
|
.NE
|
|
.PP
|
|
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.
|
|
.PP
|
|
The function \fBinitscr\fR or \fBnewterm\fR
|
|
must be called to initialize the library
|
|
before any of the other routines that deal with windows
|
|
and screens are used.
|
|
The routine \fBendwin\fR(3X) must be called before exiting.
|
|
.PP
|
|
To get character-at-a-time input without echoing (most
|
|
interactive, screen oriented programs want this), the following
|
|
sequence should be used:
|
|
.NS
|
|
\fBinitscr(); cbreak(); noecho();\fR
|
|
.NE
|
|
.PP
|
|
Most programs would additionally use the sequence:
|
|
.NS
|
|
\fBintrflush(stdscr, FALSE);\fR
|
|
\fBkeypad(stdscr, TRUE);\fR
|
|
.NE
|
|
.PP
|
|
Before a \fBcurses\fR 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 \fB@TPUT@ init\fR command
|
|
after the shell environment variable \fBTERM\fR has been exported.
|
|
\fB@TSET@(1)\fR is usually responsible for doing this.
|
|
[See \fBterminfo\fR(\*n) for further details.]
|
|
.SS Datatypes
|
|
.PP
|
|
The \fBncurses\fR library permits manipulation of data structures,
|
|
called \fIwindows\fR, which can be thought of as two-dimensional
|
|
arrays of characters representing all or part of a CRT screen.
|
|
A default window called \fBstdscr\fR, which is the size of the terminal
|
|
screen, is supplied.
|
|
Others may be created with \fBnewwin\fR.
|
|
.PP
|
|
Note that \fBcurses\fR does not handle overlapping windows, that's done by
|
|
the \fBpanel\fR(3X) library.
|
|
This means that you can either use
|
|
\fBstdscr\fR or divide the screen into tiled windows and not using
|
|
\fBstdscr\fR at all.
|
|
Mixing the two will result in unpredictable, and undesired, effects.
|
|
.PP
|
|
Windows are referred to by variables declared as \fBWINDOW *\fR.
|
|
These data structures are manipulated with routines described here and
|
|
elsewhere in the \fBncurses\fR manual pages.
|
|
Among those, the most basic
|
|
routines are \fBmove\fR and \fBaddch\fR.
|
|
More general versions of
|
|
these routines are included with names beginning with \fBw\fR,
|
|
allowing the user to specify a window.
|
|
The routines not beginning
|
|
with \fBw\fR affect \fBstdscr\fR.
|
|
.PP
|
|
After using routines to manipulate a window, \fBrefresh\fR(3X) is called,
|
|
telling \fBcurses\fR to make the user's CRT screen look like
|
|
\fBstdscr\fR.
|
|
The characters in a window are actually of type
|
|
\fBchtype\fR, (character and attribute data) so that other information
|
|
about the character may also be stored with each character.
|
|
.PP
|
|
Special windows called \fIpads\fR 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 \fBcurs_pad\fR(3X) for more information.
|
|
.PP
|
|
In addition to drawing characters on the screen, video 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, \fBcurses\fR 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 \fB<curses.h>\fR,
|
|
such as \fBA_REVERSE\fR, \fBACS_HLINE\fR, and \fBKEY_LEFT\fR.
|
|
.SS Environment variables
|
|
.PP
|
|
If the environment variables \fBLINES\fR and \fBCOLUMNS\fR are set, or if the
|
|
program is executing in a window environment, line and column information in
|
|
the environment will override information read by \fIterminfo\fR.
|
|
This would affect a program running in an AT&T 630 layer,
|
|
for example, where the size of a
|
|
screen is changeable (see \fBENVIRONMENT\fR).
|
|
.PP
|
|
If the environment variable \fBTERMINFO\fR is defined, any program using
|
|
\fBcurses\fR checks for a local terminal definition before checking in the
|
|
standard place.
|
|
For example, if \fBTERM\fR is set to \fBatt4424\fR, then the
|
|
compiled terminal definition is found in
|
|
.NS
|
|
\fB\*d/a/att4424\fR.
|
|
.NE
|
|
.PP
|
|
(The \fBa\fR is copied from the first letter of \fBatt4424\fR to avoid
|
|
creation of huge directories.) However, if \fBTERMINFO\fR is set to
|
|
\fB$HOME/myterms\fR, \fBcurses\fR first checks
|
|
.NS
|
|
\fB$HOME/myterms/a/att4424\fR,
|
|
.NE
|
|
.PP
|
|
and if that fails, it then checks
|
|
.NS
|
|
\fB\*d/a/att4424\fR.
|
|
.NE
|
|
.PP
|
|
This is useful for developing experimental definitions or when write
|
|
permission in \fB\*d\fR is not available.
|
|
.PP
|
|
The integer variables \fBLINES\fR and \fBCOLS\fR are defined in
|
|
\fB<curses.h>\fR and will be filled in by \fBinitscr\fR with the size of the
|
|
screen.
|
|
The constants \fBTRUE\fR and \fBFALSE\fR have the values \fB1\fR and
|
|
\fB0\fR, respectively.
|
|
.PP
|
|
The \fBcurses\fR routines also define the \fBWINDOW *\fR variable \fBcurscr\fR
|
|
which is used for certain low-level operations like clearing and redrawing a
|
|
screen containing garbage.
|
|
The \fBcurscr\fR can be used in only a few routines.
|
|
.\"
|
|
.SS Routine and Argument Names
|
|
Many \fBcurses\fR routines have two or more versions.
|
|
The routines prefixed with \fBw\fR require a window argument.
|
|
The routines prefixed with \fBp\fR require a pad argument.
|
|
Those without a prefix generally use \fBstdscr\fR.
|
|
.PP
|
|
The routines prefixed with \fBmv\fR require a \fIy\fR and \fIx\fR
|
|
coordinate to move to before performing the appropriate action.
|
|
The \fBmv\fR routines imply a call to \fBmove\fR before the call to the
|
|
other routine.
|
|
The coordinate \fIy\fR always refers to the row (of
|
|
the window), and \fIx\fR always refers to the column.
|
|
The upper left-hand corner is always (0,0), not (1,1).
|
|
.PP
|
|
The routines prefixed with \fBmvw\fR take both a window argument and
|
|
\fIx\fR and \fIy\fR coordinates.
|
|
The window argument is always specified before the coordinates.
|
|
.PP
|
|
In each case, \fIwin\fR is the window affected, and \fIpad\fR is the
|
|
pad affected; \fIwin\fR and \fIpad\fR are always pointers to type
|
|
\fBWINDOW\fR.
|
|
.PP
|
|
Option setting routines require a Boolean flag \fIbf\fR with the value
|
|
\fBTRUE\fR or \fBFALSE\fR; \fIbf\fR is always of type \fBbool\fR.
|
|
Most of the data types used in the library routines,
|
|
such as \fBWINDOW\fR, \fBSCREEN\fR, \fBbool\fR, and \fBchtype\fR
|
|
are defined in \fB<curses.h>\fR.
|
|
Types used for the terminfo routines such as
|
|
\fBTERMINAL\fR are defined in \fB<term.h>\fR.
|
|
.PP
|
|
This manual page describes functions which may appear in any configuration
|
|
of the library.
|
|
There are two common configurations of the library:
|
|
.RS 3
|
|
.TP 5
|
|
.I ncurses
|
|
the \*(``normal\*('' library, which handles 8-bit characters.
|
|
The normal (8-bit) library stores characters combined with attributes
|
|
in \fBchtype\fP data.
|
|
.IP
|
|
Attributes alone (no corresponding character) may be stored in \fBchtype\fP
|
|
or the equivalent \fBattr_t\fP data.
|
|
In either case, the data is stored in something like an integer.
|
|
.IP
|
|
Each cell (row and column) in a \fBWINDOW\fP is stored as a \fBchtype\fP.
|
|
.TP 5
|
|
.I ncursesw
|
|
the so-called \*(``wide\*('' library, which handles multibyte characters
|
|
(see the section on \fBALTERNATE CONFIGURATIONS\fP).
|
|
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:
|
|
.RS 5
|
|
.TP 5
|
|
.B cchar_t
|
|
corresponds to \fBchtype\fP.
|
|
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.
|
|
.IP
|
|
Each cell (row and column) in a \fBWINDOW\fP is stored as a \fBcchar_t\fP.
|
|
.IP
|
|
The \fBsetcchar\fP(3X) and \fBgetcchar\fP(3X)
|
|
functions store and retrieve the data from
|
|
a \fBcchar_t\fP structure.
|
|
.TP 5
|
|
.B wchar_t
|
|
stores a \*(``wide\*('' character.
|
|
Like \fBchtype\fP, this may be an integer.
|
|
.TP 5
|
|
.B wint_t
|
|
stores a \fBwchar_t\fP or \fBWEOF\fP \- not the same, though both may have
|
|
the same size.
|
|
.RE
|
|
.IP
|
|
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, \fBwaddch\fP becomes \fBwadd_wch\fP.
|
|
.RE
|
|
.PP
|
|
.\"
|
|
.SS Routine Name Index
|
|
The following table lists the \fBcurses\fR 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.
|
|
.PP
|
|
.TS
|
|
center tab(/);
|
|
l l
|
|
l l .
|
|
\fBcurses\fR Routine Name/Manual Page Name
|
|
=
|
|
COLOR_PAIR/\fBcurs_color\fR(3X)
|
|
PAIR_NUMBER/\fBcurs_attr\fR(3X)
|
|
add_wch/\fBcurs_add_wch\fR(3X)
|
|
add_wchnstr/\fBcurs_add_wchstr\fR(3X)
|
|
add_wchstr/\fBcurs_add_wchstr\fR(3X)
|
|
addch/\fBcurs_addch\fR(3X)
|
|
addchnstr/\fBcurs_addchstr\fR(3X)
|
|
addchstr/\fBcurs_addchstr\fR(3X)
|
|
addnstr/\fBcurs_addstr\fR(3X)
|
|
addnwstr/\fBcurs_addwstr\fR(3X)
|
|
addstr/\fBcurs_addstr\fR(3X)
|
|
addwstr/\fBcurs_addwstr\fR(3X)
|
|
alloc_pair/\fBnew_pair\fR(3X)*
|
|
assume_default_colors/\fBdefault_colors\fR(3X)*
|
|
attr_get/\fBcurs_attr\fR(3X)
|
|
attr_off/\fBcurs_attr\fR(3X)
|
|
attr_on/\fBcurs_attr\fR(3X)
|
|
attr_set/\fBcurs_attr\fR(3X)
|
|
attroff/\fBcurs_attr\fR(3X)
|
|
attron/\fBcurs_attr\fR(3X)
|
|
attrset/\fBcurs_attr\fR(3X)
|
|
baudrate/\fBcurs_termattrs\fR(3X)
|
|
beep/\fBcurs_beep\fR(3X)
|
|
bkgd/\fBcurs_bkgd\fR(3X)
|
|
bkgdset/\fBcurs_bkgd\fR(3X)
|
|
bkgrnd/\fBcurs_bkgrnd\fR(3X)
|
|
bkgrndset/\fBcurs_bkgrnd\fR(3X)
|
|
border/\fBcurs_border\fR(3X)
|
|
border_set/\fBcurs_border_set\fR(3X)
|
|
box/\fBcurs_border\fR(3X)
|
|
box_set/\fBcurs_border_set\fR(3X)
|
|
can_change_color/\fBcurs_color\fR(3X)
|
|
cbreak/\fBcurs_inopts\fR(3X)
|
|
chgat/\fBcurs_attr\fR(3X)
|
|
clear/\fBcurs_clear\fR(3X)
|
|
clearok/\fBcurs_outopts\fR(3X)
|
|
clrtobot/\fBcurs_clear\fR(3X)
|
|
clrtoeol/\fBcurs_clear\fR(3X)
|
|
color_content/\fBcurs_color\fR(3X)
|
|
color_set/\fBcurs_attr\fR(3X)
|
|
copywin/\fBcurs_overlay\fR(3X)
|
|
curs_set/\fBcurs_kernel\fR(3X)
|
|
curses_trace/\fBcurs_trace\fR(3X)*
|
|
curses_version/\fBcurs_extend\fR(3X)*
|
|
def_prog_mode/\fBcurs_kernel\fR(3X)
|
|
def_shell_mode/\fBcurs_kernel\fR(3X)
|
|
define_key/\fBdefine_key\fR(3X)*
|
|
del_curterm/\fBcurs_terminfo\fR(3X)
|
|
delay_output/\fBcurs_util\fR(3X)
|
|
delch/\fBcurs_delch\fR(3X)
|
|
deleteln/\fBcurs_deleteln\fR(3X)
|
|
delscreen/\fBcurs_initscr\fR(3X)
|
|
delwin/\fBcurs_window\fR(3X)
|
|
derwin/\fBcurs_window\fR(3X)
|
|
doupdate/\fBcurs_refresh\fR(3X)
|
|
dupwin/\fBcurs_window\fR(3X)
|
|
echo/\fBcurs_inopts\fR(3X)
|
|
echo_wchar/\fBcurs_add_wch\fR(3X)
|
|
echochar/\fBcurs_addch\fR(3X)
|
|
endwin/\fBcurs_initscr\fR(3X)
|
|
erase/\fBcurs_clear\fR(3X)
|
|
erasechar/\fBcurs_termattrs\fR(3X)
|
|
erasewchar/\fBcurs_termattrs\fR(3X)
|
|
exit_curses/\fBcurs_memleaks\fR(3X)*
|
|
exit_terminfo/\fBcurs_memleaks\fR(3X)*
|
|
extended_color_content/\fBcurs_color\fR(3X)*
|
|
extended_pair_content/\fBcurs_color\fR(3X)*
|
|
extended_slk_color/\fBcurs_slk\fR(3X)*
|
|
filter/\fBcurs_util\fR(3X)
|
|
find_pair/\fBnew_pair\fR(3X)*
|
|
flash/\fBcurs_beep\fR(3X)
|
|
flushinp/\fBcurs_util\fR(3X)
|
|
free_pair/\fBnew_pair\fR(3X)*
|
|
get_wch/\fBcurs_get_wch\fR(3X)
|
|
get_wstr/\fBcurs_get_wstr\fR(3X)
|
|
getattrs/\fBcurs_attr\fR(3X)
|
|
getbegx/\fBcurs_legacy\fR(3X)*
|
|
getbegy/\fBcurs_legacy\fR(3X)*
|
|
getbegyx/\fBcurs_getyx\fR(3X)
|
|
getbkgd/\fBcurs_bkgd\fR(3X)
|
|
getbkgrnd/\fBcurs_bkgrnd\fR(3X)
|
|
getcchar/\fBcurs_getcchar\fR(3X)
|
|
getch/\fBcurs_getch\fR(3X)
|
|
getcurx/\fBcurs_legacy\fR(3X)*
|
|
getcury/\fBcurs_legacy\fR(3X)*
|
|
getmaxx/\fBcurs_legacy\fR(3X)*
|
|
getmaxy/\fBcurs_legacy\fR(3X)*
|
|
getmaxyx/\fBcurs_getyx\fR(3X)
|
|
getmouse/\fBcurs_mouse\fR(3X)*
|
|
getn_wstr/\fBcurs_get_wstr\fR(3X)
|
|
getnstr/\fBcurs_getstr\fR(3X)
|
|
getparx/\fBcurs_legacy\fR(3X)*
|
|
getpary/\fBcurs_legacy\fR(3X)*
|
|
getparyx/\fBcurs_getyx\fR(3X)
|
|
getstr/\fBcurs_getstr\fR(3X)
|
|
getsyx/\fBcurs_kernel\fR(3X)
|
|
getwin/\fBcurs_util\fR(3X)
|
|
getyx/\fBcurs_getyx\fR(3X)
|
|
halfdelay/\fBcurs_inopts\fR(3X)
|
|
has_colors/\fBcurs_color\fR(3X)
|
|
has_ic/\fBcurs_termattrs\fR(3X)
|
|
has_il/\fBcurs_termattrs\fR(3X)
|
|
has_key/\fBcurs_getch\fR(3X)*
|
|
has_mouse/\fBcurs_mouse\fR(3X)*
|
|
hline/\fBcurs_border\fR(3X)
|
|
hline_set/\fBcurs_border_set\fR(3X)
|
|
idcok/\fBcurs_outopts\fR(3X)
|
|
idlok/\fBcurs_outopts\fR(3X)
|
|
immedok/\fBcurs_outopts\fR(3X)
|
|
in_wch/\fBcurs_in_wch\fR(3X)
|
|
in_wchnstr/\fBcurs_in_wchstr\fR(3X)
|
|
in_wchstr/\fBcurs_in_wchstr\fR(3X)
|
|
inch/\fBcurs_inch\fR(3X)
|
|
inchnstr/\fBcurs_inchstr\fR(3X)
|
|
inchstr/\fBcurs_inchstr\fR(3X)
|
|
init_color/\fBcurs_color\fR(3X)
|
|
init_extended_color/\fBcurs_color\fR(3X)*
|
|
init_extended_pair/\fBcurs_color\fR(3X)*
|
|
init_pair/\fBcurs_color\fR(3X)
|
|
initscr/\fBcurs_initscr\fR(3X)
|
|
innstr/\fBcurs_instr\fR(3X)
|
|
innwstr/\fBcurs_inwstr\fR(3X)
|
|
ins_nwstr/\fBcurs_ins_wstr\fR(3X)
|
|
ins_wch/\fBcurs_ins_wch\fR(3X)
|
|
ins_wstr/\fBcurs_ins_wstr\fR(3X)
|
|
insch/\fBcurs_insch\fR(3X)
|
|
insdelln/\fBcurs_deleteln\fR(3X)
|
|
insertln/\fBcurs_deleteln\fR(3X)
|
|
insnstr/\fBcurs_insstr\fR(3X)
|
|
insstr/\fBcurs_insstr\fR(3X)
|
|
instr/\fBcurs_instr\fR(3X)
|
|
intrflush/\fBcurs_inopts\fR(3X)
|
|
inwstr/\fBcurs_inwstr\fR(3X)
|
|
is_cleared/\fBcurs_opaque\fR(3X)*
|
|
is_idcok/\fBcurs_opaque\fR(3X)*
|
|
is_idlok/\fBcurs_opaque\fR(3X)*
|
|
is_immedok/\fBcurs_opaque\fR(3X)*
|
|
is_keypad/\fBcurs_opaque\fR(3X)*
|
|
is_leaveok/\fBcurs_opaque\fR(3X)*
|
|
is_linetouched/\fBcurs_touch\fR(3X)
|
|
is_nodelay/\fBcurs_opaque\fR(3X)*
|
|
is_notimeout/\fBcurs_opaque\fR(3X)*
|
|
is_pad/\fBcurs_opaque\fR(3X)*
|
|
is_scrollok/\fBcurs_opaque\fR(3X)*
|
|
is_subwin/\fBcurs_opaque\fR(3X)*
|
|
is_syncok/\fBcurs_opaque\fR(3X)*
|
|
is_term_resized/\fBresizeterm\fR(3X)*
|
|
is_wintouched/\fBcurs_touch\fR(3X)
|
|
isendwin/\fBcurs_initscr\fR(3X)
|
|
key_defined/\fBkey_defined\fR(3X)*
|
|
key_name/\fBcurs_util\fR(3X)
|
|
keybound/\fBkeybound\fR(3X)*
|
|
keyname/\fBcurs_util\fR(3X)
|
|
keyok/\fBkeyok\fR(3X)*
|
|
keypad/\fBcurs_inopts\fR(3X)
|
|
killchar/\fBcurs_termattrs\fR(3X)
|
|
killwchar/\fBcurs_termattrs\fR(3X)
|
|
leaveok/\fBcurs_outopts\fR(3X)
|
|
longname/\fBcurs_termattrs\fR(3X)
|
|
mcprint/\fBcurs_print\fR(3X)*
|
|
meta/\fBcurs_inopts\fR(3X)
|
|
mouse_trafo/\fBcurs_mouse\fR(3X)*
|
|
mouseinterval/\fBcurs_mouse\fR(3X)*
|
|
mousemask/\fBcurs_mouse\fR(3X)*
|
|
move/\fBcurs_move\fR(3X)
|
|
mvadd_wch/\fBcurs_add_wch\fR(3X)
|
|
mvadd_wchnstr/\fBcurs_add_wchstr\fR(3X)
|
|
mvadd_wchstr/\fBcurs_add_wchstr\fR(3X)
|
|
mvaddch/\fBcurs_addch\fR(3X)
|
|
mvaddchnstr/\fBcurs_addchstr\fR(3X)
|
|
mvaddchstr/\fBcurs_addchstr\fR(3X)
|
|
mvaddnstr/\fBcurs_addstr\fR(3X)
|
|
mvaddnwstr/\fBcurs_addwstr\fR(3X)
|
|
mvaddstr/\fBcurs_addstr\fR(3X)
|
|
mvaddwstr/\fBcurs_addwstr\fR(3X)
|
|
mvchgat/\fBcurs_attr\fR(3X)
|
|
mvcur/\fBcurs_terminfo\fR(3X)
|
|
mvdelch/\fBcurs_delch\fR(3X)
|
|
mvderwin/\fBcurs_window\fR(3X)
|
|
mvget_wch/\fBcurs_get_wch\fR(3X)
|
|
mvget_wstr/\fBcurs_get_wstr\fR(3X)
|
|
mvgetch/\fBcurs_getch\fR(3X)
|
|
mvgetn_wstr/\fBcurs_get_wstr\fR(3X)
|
|
mvgetnstr/\fBcurs_getstr\fR(3X)
|
|
mvgetstr/\fBcurs_getstr\fR(3X)
|
|
mvhline/\fBcurs_border\fR(3X)
|
|
mvhline_set/\fBcurs_border_set\fR(3X)
|
|
mvin_wch/\fBcurs_in_wch\fR(3X)
|
|
mvin_wchnstr/\fBcurs_in_wchstr\fR(3X)
|
|
mvin_wchstr/\fBcurs_in_wchstr\fR(3X)
|
|
mvinch/\fBcurs_inch\fR(3X)
|
|
mvinchnstr/\fBcurs_inchstr\fR(3X)
|
|
mvinchstr/\fBcurs_inchstr\fR(3X)
|
|
mvinnstr/\fBcurs_instr\fR(3X)
|
|
mvinnwstr/\fBcurs_inwstr\fR(3X)
|
|
mvins_nwstr/\fBcurs_ins_wstr\fR(3X)
|
|
mvins_wch/\fBcurs_ins_wch\fR(3X)
|
|
mvins_wstr/\fBcurs_ins_wstr\fR(3X)
|
|
mvinsch/\fBcurs_insch\fR(3X)
|
|
mvinsnstr/\fBcurs_insstr\fR(3X)
|
|
mvinsstr/\fBcurs_insstr\fR(3X)
|
|
mvinstr/\fBcurs_instr\fR(3X)
|
|
mvinwstr/\fBcurs_inwstr\fR(3X)
|
|
mvprintw/\fBcurs_printw\fR(3X)
|
|
mvscanw/\fBcurs_scanw\fR(3X)
|
|
mvvline/\fBcurs_border\fR(3X)
|
|
mvvline_set/\fBcurs_border_set\fR(3X)
|
|
mvwadd_wch/\fBcurs_add_wch\fR(3X)
|
|
mvwadd_wchnstr/\fBcurs_add_wchstr\fR(3X)
|
|
mvwadd_wchstr/\fBcurs_add_wchstr\fR(3X)
|
|
mvwaddch/\fBcurs_addch\fR(3X)
|
|
mvwaddchnstr/\fBcurs_addchstr\fR(3X)
|
|
mvwaddchstr/\fBcurs_addchstr\fR(3X)
|
|
mvwaddnstr/\fBcurs_addstr\fR(3X)
|
|
mvwaddnwstr/\fBcurs_addwstr\fR(3X)
|
|
mvwaddstr/\fBcurs_addstr\fR(3X)
|
|
mvwaddwstr/\fBcurs_addwstr\fR(3X)
|
|
mvwchgat/\fBcurs_attr\fR(3X)
|
|
mvwdelch/\fBcurs_delch\fR(3X)
|
|
mvwget_wch/\fBcurs_get_wch\fR(3X)
|
|
mvwget_wstr/\fBcurs_get_wstr\fR(3X)
|
|
mvwgetch/\fBcurs_getch\fR(3X)
|
|
mvwgetn_wstr/\fBcurs_get_wstr\fR(3X)
|
|
mvwgetnstr/\fBcurs_getstr\fR(3X)
|
|
mvwgetstr/\fBcurs_getstr\fR(3X)
|
|
mvwhline/\fBcurs_border\fR(3X)
|
|
mvwhline_set/\fBcurs_border_set\fR(3X)
|
|
mvwin/\fBcurs_window\fR(3X)
|
|
mvwin_wch/\fBcurs_in_wch\fR(3X)
|
|
mvwin_wchnstr/\fBcurs_in_wchstr\fR(3X)
|
|
mvwin_wchstr/\fBcurs_in_wchstr\fR(3X)
|
|
mvwinch/\fBcurs_inch\fR(3X)
|
|
mvwinchnstr/\fBcurs_inchstr\fR(3X)
|
|
mvwinchstr/\fBcurs_inchstr\fR(3X)
|
|
mvwinnstr/\fBcurs_instr\fR(3X)
|
|
mvwinnwstr/\fBcurs_inwstr\fR(3X)
|
|
mvwins_nwstr/\fBcurs_ins_wstr\fR(3X)
|
|
mvwins_wch/\fBcurs_ins_wch\fR(3X)
|
|
mvwins_wstr/\fBcurs_ins_wstr\fR(3X)
|
|
mvwinsch/\fBcurs_insch\fR(3X)
|
|
mvwinsnstr/\fBcurs_insstr\fR(3X)
|
|
mvwinsstr/\fBcurs_insstr\fR(3X)
|
|
mvwinstr/\fBcurs_instr\fR(3X)
|
|
mvwinwstr/\fBcurs_inwstr\fR(3X)
|
|
mvwprintw/\fBcurs_printw\fR(3X)
|
|
mvwscanw/\fBcurs_scanw\fR(3X)
|
|
mvwvline/\fBcurs_border\fR(3X)
|
|
mvwvline_set/\fBcurs_border_set\fR(3X)
|
|
napms/\fBcurs_kernel\fR(3X)
|
|
newpad/\fBcurs_pad\fR(3X)
|
|
newterm/\fBcurs_initscr\fR(3X)
|
|
newwin/\fBcurs_window\fR(3X)
|
|
nl/\fBcurs_inopts\fR(3X)
|
|
nocbreak/\fBcurs_inopts\fR(3X)
|
|
nodelay/\fBcurs_inopts\fR(3X)
|
|
noecho/\fBcurs_inopts\fR(3X)
|
|
nofilter/\fBcurs_util\fR(3X)*
|
|
nonl/\fBcurs_inopts\fR(3X)
|
|
noqiflush/\fBcurs_inopts\fR(3X)
|
|
noraw/\fBcurs_inopts\fR(3X)
|
|
notimeout/\fBcurs_inopts\fR(3X)
|
|
overlay/\fBcurs_overlay\fR(3X)
|
|
overwrite/\fBcurs_overlay\fR(3X)
|
|
pair_content/\fBcurs_color\fR(3X)
|
|
pecho_wchar/\fBcurs_pad\fR(3X)*
|
|
pechochar/\fBcurs_pad\fR(3X)
|
|
pnoutrefresh/\fBcurs_pad\fR(3X)
|
|
prefresh/\fBcurs_pad\fR(3X)
|
|
printw/\fBcurs_printw\fR(3X)
|
|
putp/\fBcurs_terminfo\fR(3X)
|
|
putwin/\fBcurs_util\fR(3X)
|
|
qiflush/\fBcurs_inopts\fR(3X)
|
|
raw/\fBcurs_inopts\fR(3X)
|
|
redrawwin/\fBcurs_refresh\fR(3X)
|
|
refresh/\fBcurs_refresh\fR(3X)
|
|
reset_color_pairs/\fBcurs_color\fR(3X)*
|
|
reset_prog_mode/\fBcurs_kernel\fR(3X)
|
|
reset_shell_mode/\fBcurs_kernel\fR(3X)
|
|
resetty/\fBcurs_kernel\fR(3X)
|
|
resize_term/\fBresizeterm\fR(3X)*
|
|
resizeterm/\fBresizeterm\fR(3X)*
|
|
restartterm/\fBcurs_terminfo\fR(3X)
|
|
ripoffline/\fBcurs_kernel\fR(3X)
|
|
savetty/\fBcurs_kernel\fR(3X)
|
|
scanw/\fBcurs_scanw\fR(3X)
|
|
scr_dump/\fBcurs_scr_dump\fR(3X)
|
|
scr_init/\fBcurs_scr_dump\fR(3X)
|
|
scr_restore/\fBcurs_scr_dump\fR(3X)
|
|
scr_set/\fBcurs_scr_dump\fR(3X)
|
|
scrl/\fBcurs_scroll\fR(3X)
|
|
scroll/\fBcurs_scroll\fR(3X)
|
|
scrollok/\fBcurs_outopts\fR(3X)
|
|
set_curterm/\fBcurs_terminfo\fR(3X)
|
|
set_term/\fBcurs_initscr\fR(3X)
|
|
setcchar/\fBcurs_getcchar\fR(3X)
|
|
setscrreg/\fBcurs_outopts\fR(3X)
|
|
setsyx/\fBcurs_kernel\fR(3X)
|
|
setupterm/\fBcurs_terminfo\fR(3X)
|
|
slk_attr/\fBcurs_slk\fR(3X)*
|
|
slk_attr_off/\fBcurs_slk\fR(3X)
|
|
slk_attr_on/\fBcurs_slk\fR(3X)
|
|
slk_attr_set/\fBcurs_slk\fR(3X)
|
|
slk_attroff/\fBcurs_slk\fR(3X)
|
|
slk_attron/\fBcurs_slk\fR(3X)
|
|
slk_attrset/\fBcurs_slk\fR(3X)
|
|
slk_clear/\fBcurs_slk\fR(3X)
|
|
slk_color/\fBcurs_slk\fR(3X)
|
|
slk_init/\fBcurs_slk\fR(3X)
|
|
slk_label/\fBcurs_slk\fR(3X)
|
|
slk_noutrefresh/\fBcurs_slk\fR(3X)
|
|
slk_refresh/\fBcurs_slk\fR(3X)
|
|
slk_restore/\fBcurs_slk\fR(3X)
|
|
slk_set/\fBcurs_slk\fR(3X)
|
|
slk_touch/\fBcurs_slk\fR(3X)
|
|
slk_wset/\fBcurs_slk\fR(3X)*
|
|
standend/\fBcurs_attr\fR(3X)
|
|
standout/\fBcurs_attr\fR(3X)
|
|
start_color/\fBcurs_color\fR(3X)
|
|
subpad/\fBcurs_pad\fR(3X)
|
|
subwin/\fBcurs_window\fR(3X)
|
|
syncok/\fBcurs_window\fR(3X)
|
|
term_attrs/\fBcurs_termattrs\fR(3X)
|
|
termattrs/\fBcurs_termattrs\fR(3X)
|
|
termname/\fBcurs_termattrs\fR(3X)
|
|
tgetent/\fBcurs_termcap\fR(3X)
|
|
tgetflag/\fBcurs_termcap\fR(3X)
|
|
tgetnum/\fBcurs_termcap\fR(3X)
|
|
tgetstr/\fBcurs_termcap\fR(3X)
|
|
tgoto/\fBcurs_termcap\fR(3X)
|
|
tigetflag/\fBcurs_terminfo\fR(3X)
|
|
tigetnum/\fBcurs_terminfo\fR(3X)
|
|
tigetstr/\fBcurs_terminfo\fR(3X)
|
|
timeout/\fBcurs_inopts\fR(3X)
|
|
tiparm/\fBcurs_terminfo\fR(3X)*
|
|
touchline/\fBcurs_touch\fR(3X)
|
|
touchwin/\fBcurs_touch\fR(3X)
|
|
tparm/\fBcurs_terminfo\fR(3X)
|
|
tputs/\fBcurs_termcap\fR(3X)
|
|
tputs/\fBcurs_terminfo\fR(3X)
|
|
trace/\fBcurs_trace\fR(3X)*
|
|
typeahead/\fBcurs_inopts\fR(3X)
|
|
unctrl/\fBcurs_util\fR(3X)
|
|
unget_wch/\fBcurs_get_wch\fR(3X)
|
|
ungetch/\fBcurs_getch\fR(3X)
|
|
ungetmouse/\fBcurs_mouse\fR(3X)*
|
|
untouchwin/\fBcurs_touch\fR(3X)
|
|
use_default_colors/\fBdefault_colors\fR(3X)*
|
|
use_env/\fBcurs_util\fR(3X)
|
|
use_extended_names/\fBcurs_extend\fR(3X)*
|
|
use_legacy_coding/\fBlegacy_coding\fR(3X)*
|
|
use_tioctl/\fBcurs_util\fR(3X)*
|
|
vid_attr/\fBcurs_terminfo\fR(3X)
|
|
vid_puts/\fBcurs_terminfo\fR(3X)
|
|
vidattr/\fBcurs_terminfo\fR(3X)
|
|
vidputs/\fBcurs_terminfo\fR(3X)
|
|
vline/\fBcurs_border\fR(3X)
|
|
vline_set/\fBcurs_border_set\fR(3X)
|
|
vw_printw/\fBcurs_printw\fR(3X)
|
|
vw_scanw/\fBcurs_scanw\fR(3X)
|
|
vwprintw/\fBcurs_printw\fR(3X)
|
|
vwscanw/\fBcurs_scanw\fR(3X)
|
|
wadd_wch/\fBcurs_add_wch\fR(3X)
|
|
wadd_wchnstr/\fBcurs_add_wchstr\fR(3X)
|
|
wadd_wchstr/\fBcurs_add_wchstr\fR(3X)
|
|
waddch/\fBcurs_addch\fR(3X)
|
|
waddchnstr/\fBcurs_addchstr\fR(3X)
|
|
waddchstr/\fBcurs_addchstr\fR(3X)
|
|
waddnstr/\fBcurs_addstr\fR(3X)
|
|
waddnwstr/\fBcurs_addwstr\fR(3X)
|
|
waddstr/\fBcurs_addstr\fR(3X)
|
|
waddwstr/\fBcurs_addwstr\fR(3X)
|
|
wattr_get/\fBcurs_attr\fR(3X)
|
|
wattr_off/\fBcurs_attr\fR(3X)
|
|
wattr_on/\fBcurs_attr\fR(3X)
|
|
wattr_set/\fBcurs_attr\fR(3X)
|
|
wattroff/\fBcurs_attr\fR(3X)
|
|
wattron/\fBcurs_attr\fR(3X)
|
|
wattrset/\fBcurs_attr\fR(3X)
|
|
wbkgd/\fBcurs_bkgd\fR(3X)
|
|
wbkgdset/\fBcurs_bkgd\fR(3X)
|
|
wbkgrnd/\fBcurs_bkgrnd\fR(3X)
|
|
wbkgrndset/\fBcurs_bkgrnd\fR(3X)
|
|
wborder/\fBcurs_border\fR(3X)
|
|
wborder_set/\fBcurs_border_set\fR(3X)
|
|
wchgat/\fBcurs_attr\fR(3X)
|
|
wclear/\fBcurs_clear\fR(3X)
|
|
wclrtobot/\fBcurs_clear\fR(3X)
|
|
wclrtoeol/\fBcurs_clear\fR(3X)
|
|
wcolor_set/\fBcurs_attr\fR(3X)
|
|
wcursyncup/\fBcurs_window\fR(3X)
|
|
wdelch/\fBcurs_delch\fR(3X)
|
|
wdeleteln/\fBcurs_deleteln\fR(3X)
|
|
wecho_wchar/\fBcurs_add_wch\fR(3X)
|
|
wechochar/\fBcurs_addch\fR(3X)
|
|
wenclose/\fBcurs_mouse\fR(3X)*
|
|
werase/\fBcurs_clear\fR(3X)
|
|
wget_wch/\fBcurs_get_wch\fR(3X)
|
|
wget_wstr/\fBcurs_get_wstr\fR(3X)
|
|
wgetbkgrnd/\fBcurs_bkgrnd\fR(3X)
|
|
wgetch/\fBcurs_getch\fR(3X)
|
|
wgetdelay/\fBcurs_opaque\fR(3X)*
|
|
wgetn_wstr/\fBcurs_get_wstr\fR(3X)
|
|
wgetnstr/\fBcurs_getstr\fR(3X)
|
|
wgetparent/\fBcurs_opaque\fR(3X)*
|
|
wgetscrreg/\fBcurs_opaque\fR(3X)*
|
|
wgetstr/\fBcurs_getstr\fR(3X)
|
|
whline/\fBcurs_border\fR(3X)
|
|
whline_set/\fBcurs_border_set\fR(3X)
|
|
win_wch/\fBcurs_in_wch\fR(3X)
|
|
win_wchnstr/\fBcurs_in_wchstr\fR(3X)
|
|
win_wchstr/\fBcurs_in_wchstr\fR(3X)
|
|
winch/\fBcurs_inch\fR(3X)
|
|
winchnstr/\fBcurs_inchstr\fR(3X)
|
|
winchstr/\fBcurs_inchstr\fR(3X)
|
|
winnstr/\fBcurs_instr\fR(3X)
|
|
winnwstr/\fBcurs_inwstr\fR(3X)
|
|
wins_nwstr/\fBcurs_ins_wstr\fR(3X)
|
|
wins_wch/\fBcurs_ins_wch\fR(3X)
|
|
wins_wstr/\fBcurs_ins_wstr\fR(3X)
|
|
winsch/\fBcurs_insch\fR(3X)
|
|
winsdelln/\fBcurs_deleteln\fR(3X)
|
|
winsertln/\fBcurs_deleteln\fR(3X)
|
|
winsnstr/\fBcurs_insstr\fR(3X)
|
|
winsstr/\fBcurs_insstr\fR(3X)
|
|
winstr/\fBcurs_instr\fR(3X)
|
|
winwstr/\fBcurs_inwstr\fR(3X)
|
|
wmouse_trafo/\fBcurs_mouse\fR(3X)*
|
|
wmove/\fBcurs_move\fR(3X)
|
|
wnoutrefresh/\fBcurs_refresh\fR(3X)
|
|
wprintw/\fBcurs_printw\fR(3X)
|
|
wredrawln/\fBcurs_refresh\fR(3X)
|
|
wrefresh/\fBcurs_refresh\fR(3X)
|
|
wresize/\fBwresize\fR(3X)*
|
|
wscanw/\fBcurs_scanw\fR(3X)
|
|
wscrl/\fBcurs_scroll\fR(3X)
|
|
wsetscrreg/\fBcurs_outopts\fR(3X)
|
|
wstandend/\fBcurs_attr\fR(3X)
|
|
wstandout/\fBcurs_attr\fR(3X)
|
|
wsyncdown/\fBcurs_window\fR(3X)
|
|
wsyncup/\fBcurs_window\fR(3X)
|
|
wtimeout/\fBcurs_inopts\fR(3X)
|
|
wtouchln/\fBcurs_touch\fR(3X)
|
|
wunctrl/\fBcurs_util\fR(3X)
|
|
wvline/\fBcurs_border\fR(3X)
|
|
wvline_set/\fBcurs_border_set\fR(3X)
|
|
.TE
|
|
.PP
|
|
Depending on the configuration,
|
|
additional sets of functions may be available:
|
|
.RS 3
|
|
.TP 5
|
|
\fBcurs_memleaks\fP(3X) - curses memory-leak checking
|
|
.TP 5
|
|
\fBcurs_sp_funcs\fP(3X) - curses screen-pointer extension
|
|
.TP 5
|
|
\fBcurs_threads\fP(3X) - curses thread support
|
|
.TP 5
|
|
\fBcurs_trace\fP(3X) - curses debugging routines
|
|
.RE
|
|
.SH RETURN VALUE
|
|
Routines that return an integer return \fBERR\fR upon failure and an
|
|
integer value other than \fBERR\fR upon successful completion, unless
|
|
otherwise noted in the routine descriptions.
|
|
.PP
|
|
As a general rule, routines check for null pointers passed as parameters,
|
|
and handle this as an error.
|
|
.PP
|
|
All macros return the value of the \fBw\fR version, except \fBsetscrreg\fR,
|
|
\fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and \fBgetmaxyx\fR.
|
|
The return values of
|
|
\fBsetscrreg\fR,
|
|
\fBwsetscrreg\fR,
|
|
\fBgetyx\fR,
|
|
\fBgetbegyx\fR, and
|
|
\fBgetmaxyx\fR are undefined (i.e., these should not be used as the
|
|
right-hand side of assignment statements).
|
|
.PP
|
|
Functions with a \*(``mv\*('' prefix first perform a cursor movement using
|
|
\fBwmove\fP, 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 \fBmvprintw\fP)
|
|
are provided both as macros and functions.
|
|
.PP
|
|
Routines that return pointers return \fBNULL\fR on error.
|
|
.SH ENVIRONMENT
|
|
.PP
|
|
The following environment symbols are useful for customizing the
|
|
runtime behavior of the \fBncurses\fR library.
|
|
The most important ones have been already discussed in detail.
|
|
.SS CC command-character
|
|
.PP
|
|
When set, change occurrences of the command_character
|
|
(i.e., the \fBcmdch\fP capability)
|
|
of the loaded terminfo entries to the value of this variable.
|
|
Very few terminfo entries provide this feature.
|
|
.PP
|
|
Because this name is also used in development environments to represent
|
|
the C compiler's name, \fBncurses\fR ignores it if it does not happen to
|
|
be a single character.
|
|
.SS BAUDRATE
|
|
.PP
|
|
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, \fBncurses\fR uses 9600.
|
|
This allows testers to construct repeatable test-cases
|
|
that take into account costs that depend on baudrate.
|
|
.SS COLUMNS
|
|
.PP
|
|
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 \fBCOLUMNS\fP value nor the terminal's screen size is available,
|
|
\fBncurses\fR uses the size which may be specified in the terminfo database
|
|
(i.e., the \fBcols\fR capability).
|
|
.PP
|
|
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 \fBCOLUMNS\fP and/or \fBLINES\fP overrides the library's
|
|
use of the screen size obtained from the operating system.
|
|
.PP
|
|
Either \fBCOLUMNS\fP or \fBLINES\fP 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, \fBlines\fR and \fBcols\fR should not be specified in
|
|
a terminal description for terminals which are run as emulations.
|
|
.PP
|
|
Use the \fBuse_env\fR function to disable all use of external environment
|
|
(but not including system calls) to determine the screen size.
|
|
Use the \fBuse_tioctl\fR function to update \fBCOLUMNS\fP or \fBLINES\fP
|
|
to match the screen size obtained from system calls or the terminal database.
|
|
.SS ESCDELAY
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.SS HOME
|
|
Tells \fBncurses\fR where your home directory is.
|
|
That is where it may read and write auxiliary terminal descriptions:
|
|
.NS
|
|
$HOME/.termcap
|
|
$HOME/.terminfo
|
|
.NE
|
|
.SS LINES
|
|
.PP
|
|
Like COLUMNS, specify the height of the screen in characters.
|
|
See COLUMNS for a detailed description.
|
|
.SS MOUSE_BUTTONS_123
|
|
.PP
|
|
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:
|
|
.NS
|
|
1 = left
|
|
.br
|
|
2 = right
|
|
.br
|
|
3 = middle.
|
|
.NE
|
|
.PP
|
|
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, \fBncurses\fR uses 132.
|
|
.SS NCURSES_ASSUMED_COLORS
|
|
.PP
|
|
Override the compiled-in assumption that the
|
|
terminal's default colors are white-on-black
|
|
(see \fBdefault_colors\fR(3X)).
|
|
You may set the foreground and background color values with this environment
|
|
variable by proving a 2-element list: foreground,background.
|
|
For example, to tell ncurses to not assume anything
|
|
about the colors, set this to "\-1,\-1".
|
|
To make it green-on-black, set it to "2,0".
|
|
Any positive value from zero to the terminfo \fBmax_colors\fR value is allowed.
|
|
.SS NCURSES_CONSOLE2
|
|
This applies only to the MinGW port of ncurses.
|
|
.PP
|
|
The \fBConsole2\fP program's handling of the Microsoft Console API call
|
|
\fBCreateConsoleScreenBuffer\fP 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 \fBNCGDB\fP has the same effect.
|
|
.SS NCURSES_GPM_TERMS
|
|
.PP
|
|
This applies only to ncurses configured to use the GPM interface.
|
|
.PP
|
|
If present,
|
|
the environment variable is a list of one or more terminal names
|
|
against which the \fBTERM\fP environment variable is matched.
|
|
Setting it to an empty value disables the GPM interface;
|
|
using the built-in support for xterm, etc.
|
|
.PP
|
|
If the environment variable is absent,
|
|
ncurses will attempt to open GPM if \fBTERM\fP contains \*(``linux\*(''.
|
|
.SS NCURSES_NO_HARD_TABS
|
|
.PP
|
|
\fBNcurses\fP 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 \fBstty\fP settings to avoid the problem.
|
|
.SS NCURSES_NO_MAGIC_COOKIE
|
|
.PP
|
|
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.
|
|
.SS NCURSES_NO_PADDING
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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 \fIflash\fR.
|
|
.SS NCURSES_NO_SETBUF
|
|
This setting is obsolete.
|
|
Before changes
|
|
.RS 3
|
|
.bP
|
|
started with 5.9 patch 20120825
|
|
and
|
|
.bP
|
|
continued
|
|
though 5.9 patch 20130126
|
|
.RE
|
|
.PP
|
|
\fBncurses\fR enabled buffered output during terminal initialization.
|
|
This was done (as in SVr4 curses) for performance reasons.
|
|
For testing purposes, both of \fBncurses\fR 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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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 \fBputp\fP still use the
|
|
standard output.
|
|
But high-level curses calls do not.
|
|
.SS NCURSES_NO_UTF8_ACS
|
|
.PP
|
|
During initialization, the \fBncurses\fR 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 \fBTERM\fP 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.
|
|
.PP
|
|
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\*(''.
|
|
.PP
|
|
As an alternative to the environment variable,
|
|
ncurses checks for an extended terminfo capability \fBU8\fP.
|
|
This is a numeric capability which can be compiled using \fB@TIC@\ \-x\fP.
|
|
For example
|
|
.RS 3
|
|
.ft CW
|
|
.sp
|
|
.nf
|
|
# linux console, if patched to provide working
|
|
# VT100 shift-in/shift-out, with corresponding font.
|
|
linux-vt100|linux console with VT100 line-graphics,
|
|
U8#0, use=linux,
|
|
.sp
|
|
# uxterm with vt100Graphics resource set to false
|
|
xterm-utf8|xterm relying on UTF-8 line-graphics,
|
|
U8#1, use=xterm,
|
|
.fi
|
|
.ft
|
|
.RE
|
|
.PP
|
|
The name \*(``U8\*('' is chosen to be two characters,
|
|
to permit it to be used by applications that use ncurses'
|
|
termcap interface.
|
|
.SS NCURSES_TRACE
|
|
.PP
|
|
During initialization, the \fBncurses\fR debugging library
|
|
checks the NCURSES_TRACE environment variable.
|
|
If it is defined, to a numeric value, \fBncurses\fR calls the \fBtrace\fR
|
|
function, using that value as the argument.
|
|
.PP
|
|
The argument values, which are defined in \fBcurses.h\fR, provide several
|
|
types of information.
|
|
When running with traces enabled, your application will write the
|
|
file \fBtrace\fR to the current directory.
|
|
.PP
|
|
See \fBcurs_trace\fP(3X) for more information.
|
|
.SS TERM
|
|
.PP
|
|
Denotes your terminal type.
|
|
Each terminal type is distinct, though many are similar.
|
|
.PP
|
|
\fBTERM\fP 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.
|
|
.PP
|
|
If you set \fBTERM\fP 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 (\fBxterm\fP being a rare exception),
|
|
terminal emulators which allow you to
|
|
specify \fBTERM\fP as a parameter or configuration value do
|
|
not change their behavior to match that setting.
|
|
.SS TERMCAP
|
|
If the \fBncurses\fR library has been configured with \fItermcap\fR
|
|
support, \fBncurses\fR will check for a terminal's description in
|
|
termcap form if it is not available in the terminfo database.
|
|
.PP
|
|
The \fBTERMCAP\fP environment variable contains
|
|
either a terminal description (with newlines stripped out),
|
|
or a file name telling where the information denoted by
|
|
the \fBTERM\fP environment variable exists.
|
|
In either case, setting it directs \fBncurses\fR to ignore
|
|
the usual place for this information, e.g., /etc/termcap.
|
|
.SS TERMINFO
|
|
.PP
|
|
\fBncurses\fP can be configured to read from multiple terminal databases.
|
|
The \fBTERMINFO\fP variable overrides the location for
|
|
the default terminal database.
|
|
Terminal descriptions (in terminal format) are stored in terminal databases:
|
|
.bP
|
|
Normally these are stored in a directory tree,
|
|
using subdirectories named by the first letter of the terminal names therein.
|
|
.IP
|
|
This is the scheme used in System V, which legacy Unix systems use,
|
|
and the \fBTERMINFO\fP variable is used by \fIcurses\fP applications on those
|
|
systems to override the default location of the terminal database.
|
|
.bP
|
|
If \fBncurses\fP is built to use hashed databases,
|
|
then each entry in this list may be the path of a hashed database file, e.g.,
|
|
.NS
|
|
/usr/share/terminfo.db
|
|
.NE
|
|
.IP
|
|
rather than
|
|
.NS
|
|
/usr/share/terminfo/
|
|
.NE
|
|
.IP
|
|
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.
|
|
.bP
|
|
If \fBncurses\fP is built with a support for reading termcap files
|
|
directly, then an entry in this list may be the path of a termcap file.
|
|
.bP
|
|
If the \fBTERMINFO\fP variable begins with
|
|
\*(``hex:\*('' or \*(``b64:\*('',
|
|
\fBncurses\fP uses the remainder of that variable as a compiled terminal
|
|
description.
|
|
You might produce the base64 format using \fBinfocmp\fP(1M):
|
|
.NS
|
|
TERMINFO="$(infocmp -0 -Q2 -q)"
|
|
export TERMINFO
|
|
.NE
|
|
.IP
|
|
The compiled description is used if it corresponds to the terminal identified
|
|
by the \fBTERM\fP variable.
|
|
.PP
|
|
Setting \fBTERMINFO\fP 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:
|
|
.RS 3
|
|
.bP
|
|
the last terminal database to which \fBncurses\fR wrote,
|
|
if any, is searched first
|
|
.bP
|
|
the location specified by the TERMINFO environment variable
|
|
.bP
|
|
$HOME/.terminfo
|
|
.bP
|
|
locations listed in the TERMINFO_DIRS environment variable
|
|
.bP
|
|
one or more locations whose names are configured and compiled into the
|
|
ncurses library, i.e.,
|
|
.RS 3
|
|
.bP
|
|
@TERMINFO_DIRS@ (corresponding to the TERMINFO_DIRS variable)
|
|
.bP
|
|
@TERMINFO@ (corresponding to the TERMINFO variable)
|
|
.RE
|
|
.RE
|
|
.PP
|
|
.SS TERMINFO_DIRS
|
|
.PP
|
|
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 \fBTERMINFO\fP variable.
|
|
The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
|
|
.PP
|
|
There is no corresponding feature in System V terminfo;
|
|
it is an extension developed for \fBncurses\fP.
|
|
.SS TERMPATH
|
|
.PP
|
|
If \fBTERMCAP\fP does not hold a file name then \fBncurses\fR checks
|
|
the \fBTERMPATH\fP environment variable.
|
|
This is a list of filenames separated by spaces or colons (i.e., ":") on Unix,
|
|
semicolons on OS/2 EMX.
|
|
.PP
|
|
If the \fBTERMPATH\fP environment variable is not set,
|
|
\fBncurses\fR looks in the files
|
|
.NS
|
|
/etc/termcap, /usr/share/misc/termcap and $HOME/.termcap,
|
|
.NE
|
|
.PP
|
|
in that order.
|
|
.PP
|
|
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:
|
|
.NS
|
|
$TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
|
|
.NE
|
|
.SH ALTERNATE CONFIGURATIONS
|
|
.PP
|
|
Several different configurations are possible,
|
|
depending on the configure script options used when building \fBncurses\fP.
|
|
There are a few main options whose effects are visible to the applications
|
|
developer using \fBncurses\fP:
|
|
.TP 5
|
|
\-\-disable\-overwrite
|
|
The standard include for \fBncurses\fP is as noted in \fBSYNOPSIS\fP:
|
|
.NS
|
|
\fB#include <curses.h>\fR
|
|
.NE
|
|
.IP
|
|
This option is used to avoid filename conflicts when \fBncurses\fP
|
|
is not the main implementation of curses of the computer.
|
|
If \fBncurses\fP is installed disabling overwrite, it puts its headers in
|
|
a subdirectory, e.g.,
|
|
.NS
|
|
\fB#include <ncurses/curses.h>\fR
|
|
.NE
|
|
.IP
|
|
It also omits a symbolic link which would allow you to use \fB\-lcurses\fP
|
|
to build executables.
|
|
.TP 5
|
|
\-\-enable\-widec
|
|
The configure script renames the library and
|
|
(if the \fB\-\-disable\-overwrite\fP 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
|
|
.NS
|
|
\fB\-lncurses\fR
|
|
.NE
|
|
.IP
|
|
you link with
|
|
.NS
|
|
\fB\-lncursesw\fR
|
|
.NE
|
|
.IP
|
|
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:
|
|
.RS
|
|
.bP
|
|
Originally, the wide-character feature required the symbol
|
|
\fB_XOPEN_SOURCE_EXTENDED\fP
|
|
but that was only valid for XPG4 (1996).
|
|
.bP
|
|
Later, that was deemed conflicting with \fB_XOPEN_SOURCE\fP defined to 500.
|
|
.bP
|
|
As of mid-2018,
|
|
none of the features in this implementation require a \fB_XOPEN_SOURCE\fP
|
|
feature greater than 600.
|
|
However, X/Open Curses, Issue 7 (2009) recommends defining it to 700.
|
|
.bP
|
|
Alternatively, you can enable the feature by defining \fBNCURSES_WIDECHAR\fP
|
|
with the caveat that some other header file than \fBcurses.h\fP
|
|
may require a specific value for \fB_XOPEN_SOURCE\fP
|
|
(or a system-specific symbol).
|
|
.RE
|
|
.IP
|
|
The \fBcurses.h\fP 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 \fBWINDOW\fP structure differs, and very few
|
|
applications require more than a pointer to \fBWINDOW\fPs.
|
|
.IP
|
|
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.
|
|
.TP 5
|
|
\-\-with\-pthread
|
|
The configure script renames the library.
|
|
All of the library names have a \*(``t\*('' appended to them
|
|
(before any \*(``w\*('' added by \fB\-\-enable\-widec\fP).
|
|
.IP
|
|
The global variables such as \fBLINES\fP 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 changes to work with this convention.
|
|
.TP 5
|
|
\-\-with\-shared
|
|
.TP
|
|
\-\-with\-normal
|
|
.TP
|
|
\-\-with\-debug
|
|
.TP
|
|
\-\-with\-profile
|
|
The shared and normal (static) library names differ by their suffixes,
|
|
e.g., \fBlibncurses.so\fP and \fBlibncurses.a\fP.
|
|
The debug and profiling libraries add a \*(``_g\*(''
|
|
and a \*(``_p\*('' to the root names respectively,
|
|
e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP.
|
|
.TP 5
|
|
\-\-with\-termlib
|
|
Low-level functions which do not depend upon whether the library
|
|
supports wide-characters, are provided in the tinfo library.
|
|
.IP
|
|
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.
|
|
.IP
|
|
Those functions are described in these pages:
|
|
.RS
|
|
.bP
|
|
\fBcurs_extend\fP(3X) \- miscellaneous curses extensions
|
|
.bP
|
|
\fBcurs_inopts\fR(3X) \- \fBcurses\fR input options
|
|
.bP
|
|
\fBcurs_kernel\fR(3X) \- low-level \fBcurses\fR routines
|
|
.bP
|
|
\fBcurs_termattrs\fR(3X) \- \fBcurses\fR environment query routines
|
|
.bP
|
|
\fBcurs_termcap\fR(3X) \- \fBcurses\fR emulation of termcap
|
|
.bP
|
|
\fBcurs_terminfo\fR(3X) \- \fBcurses\fR interfaces to terminfo database
|
|
.bP
|
|
\fBcurs_util\fR(3X) \- miscellaneous \fBcurses\fR utility routines
|
|
.RE
|
|
.TP 5
|
|
\-\-with\-trace
|
|
The \fBtrace\fP 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.
|
|
.SH FILES
|
|
.TP 5
|
|
@DATADIR@/tabset
|
|
directory containing initialization files for the terminal capability database
|
|
@TERMINFO@
|
|
terminal capability database
|
|
.SH SEE ALSO
|
|
\fBterminfo\fR(\*n) and related pages whose names begin
|
|
\*(``curs_\*('' for detailed routine descriptions.
|
|
.br
|
|
\fBcurs_variables\fR(3X)
|
|
.br
|
|
\fBuser_caps\fP(5) for user-defined capabilities
|
|
.SH EXTENSIONS
|
|
The \fBncurses\fR library can be compiled with an option (\fB\-DUSE_GETCAP\fR)
|
|
that falls back to the old-style /etc/termcap file if the terminal setup code
|
|
cannot find a terminfo entry corresponding to \fBTERM\fR.
|
|
Use of this feature
|
|
is not recommended, as it essentially includes an entire termcap compiler in
|
|
the \fBncurses\fR startup code, at significant cost in core and startup cycles.
|
|
.PP
|
|
The \fBncurses\fR library includes facilities for capturing mouse events on
|
|
certain terminals (including xterm).
|
|
See the \fBcurs_mouse\fR(3X)
|
|
manual page for details.
|
|
.PP
|
|
The \fBncurses\fR library includes facilities for responding to window
|
|
resizing events, e.g., when running in an xterm.
|
|
See the \fBresizeterm\fR(3X)
|
|
and \fBwresize\fR(3X) manual pages for details.
|
|
In addition, the library may be configured with a \fBSIGWINCH\fP handler.
|
|
.PP
|
|
The \fBncurses\fR 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 \fBdefine_key\fR(3X)
|
|
\fBkey_defined\fR(3X),
|
|
and \fBkeyok\fR(3X) manual pages for details.
|
|
.PP
|
|
The \fBncurses\fR 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 \fBdefault_colors\fR(3X) manual page for details.
|
|
.PP
|
|
The \fBncurses\fR library includes a function for directing application output
|
|
to a printer attached to the terminal device.
|
|
See the \fBcurs_print\fR(3X) manual page for details.
|
|
.SH PORTABILITY
|
|
The \fBncurses\fR library is intended to be BASE-level conformant with XSI
|
|
Curses.
|
|
The EXTENDED XSI Curses functionality
|
|
(including color support) is supported.
|
|
.PP
|
|
A small number of local differences (that is, individual differences between
|
|
the XSI Curses and \fBncurses\fR calls) are described in \fBPORTABILITY\fR
|
|
sections of the library man pages.
|
|
.SS Error checking
|
|
.PP
|
|
In many cases, X/Open Curses is vague about error conditions,
|
|
omitting some of the SVr4 documentation.
|
|
.PP
|
|
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.
|
|
.SS Extensions versus portability
|
|
.PP
|
|
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:
|
|
.bP
|
|
The routine \fBhas_key\fR is not part of XPG4, nor is it present in SVr4.
|
|
See the \fBcurs_getch\fR(3X) manual page for details.
|
|
.bP
|
|
The routine \fBslk_attr\fR is not part of XPG4, nor is it present in SVr4.
|
|
See the \fBcurs_slk\fR(3X) manual page for details.
|
|
.bP
|
|
The routines \fBgetmouse\fR, \fBmousemask\fR, \fBungetmouse\fR,
|
|
\fBmouseinterval\fR, and \fBwenclose\fR relating to mouse interfacing are not
|
|
part of XPG4, nor are they present in SVr4.
|
|
See the \fBcurs_mouse\fR(3X) manual page for details.
|
|
.bP
|
|
The routine \fBmcprint\fR was not present in any previous curses implementation.
|
|
See the \fBcurs_print\fR(3X) manual page for details.
|
|
.bP
|
|
The routine \fBwresize\fR is not part of XPG4, nor is it present in SVr4.
|
|
See the \fBwresize\fR(3X) manual page for details.
|
|
.bP
|
|
The WINDOW structure's internal details can be hidden from application
|
|
programs.
|
|
See \fBcurs_opaque\fR(3X) for the discussion of \fBis_scrollok\fR, etc.
|
|
.bP
|
|
This implementation can be configured to provide rudimentary support
|
|
for multi-threaded applications.
|
|
See \fBcurs_threads\fR(3X) for details.
|
|
.bP
|
|
This implementation can also be configured to provide a set of functions which
|
|
improve the ability to manage multiple screens.
|
|
See \fBcurs_sp_funcs\fR(3X) for details.
|
|
.SS Padding differences
|
|
.PP
|
|
In historic curses versions, delays embedded in the capabilities \fBcr\fR,
|
|
\fBind\fR, \fBcub1\fR, \fBff\fR and \fBtab\fR 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.
|
|
.SS Header files
|
|
The header file \fB<curses.h>\fR automatically includes the header files
|
|
\fB<stdio.h>\fR and \fB<unctrl.h>\fR.
|
|
.PP
|
|
X/Open Curses has more to say,
|
|
but does not finish the story:
|
|
.RS 4
|
|
.PP
|
|
The inclusion of <curses.h> may make visible all symbols
|
|
from the headers <stdio.h>, <term.h>, <termios.h>, and <wchar.h>.
|
|
.RE
|
|
.PP
|
|
Here is a more complete story:
|
|
.bP
|
|
Starting with BSD curses, all implementations have included <stdio.h>.
|
|
.IP
|
|
BSD curses included <curses.h> and <unctrl.h> from an internal header
|
|
"curses.ext" ("ext" was a short name for \fIexterns\fP).
|
|
.IP
|
|
BSD curses used <stdio.h> internally (for \fBprintw\fP and \fBscanw\fP),
|
|
but nothing in <curses.h> itself relied upon <stdio.h>.
|
|
.bP
|
|
SVr2 curses added \fBnewterm\fP(3X), which relies upon <stdio.h>.
|
|
That is, the function prototype uses \fBFILE\fP.
|
|
.IP
|
|
SVr4 curses added \fBputwin\fP and \fBgetwin\fP, which also use <stdio.h>.
|
|
.IP
|
|
X/Open Curses documents all three of these functions.
|
|
.IP
|
|
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.
|
|
.IP
|
|
As a result, standard <curses.h> will always include <stdio.h>.
|
|
.bP
|
|
X/Open Curses is inconsistent with respect to SVr4 regarding <unctrl.h>.
|
|
.IP
|
|
As noted in \fBcurs_util\fP(3X), ncurses includes <unctrl.h> from
|
|
<curses.h> (like SVr4).
|
|
.bP
|
|
X/Open's comments about <term.h> and <termios.h> may refer to HP-UX and AIX:
|
|
.IP
|
|
HP-UX curses includes <term.h> from <curses.h>
|
|
to declare \fBsetupterm\fP in curses.h,
|
|
but ncurses (and Solaris curses) do not.
|
|
.IP
|
|
AIX curses includes <term.h> and <termios.h>.
|
|
Again, ncurses (and Solaris curses) do not.
|
|
.bP
|
|
X/Open says that <curses.h> \fImay\fP include <term.h>,
|
|
but there is no requirement that it do that.
|
|
.IP
|
|
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>.
|
|
.IP
|
|
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>.
|
|
.bP
|
|
X/Open Curses says \fI"may make visible"\fP
|
|
because including a header file does not necessarily make all symbols
|
|
in it visible (there are ifdef's to consider).
|
|
.IP
|
|
For instance, in ncurses <wchar.h> \fImay\fP 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 \fB_XOPEN_SOURCE\fP
|
|
feature test macro.
|
|
.bP
|
|
X/Open Curses documents one required header,
|
|
in a special case: <stdarg.h> before <curses.h> to prototype
|
|
the \fBvw_printw\fP and \fBvw_scanw\fP functions
|
|
(as well as the obsolete
|
|
the \fBvwprintw\fP and \fBvwscanw\fP functions).
|
|
Each of those uses a \fBva_list\fP parameter.
|
|
.IP
|
|
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 \fBvoid*\fP for the \fBva_list\fP
|
|
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>.
|
|
.IP
|
|
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.
|
|
.SH NOTES
|
|
.PP
|
|
If standard output from a \fBncurses\fR 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.
|
|
.SH AUTHORS
|
|
Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
|
|
Based on pcurses by Pavel Curtis.
|