Index of Section 3 Manual Pages
| Interix / SUA | curses.3 | Interix / SUA |
curses(3) curses(3)
curses()
NAME
ncurses - CRT screen handling and optimization package
SYNOPSIS
#include
DESCRIPTION
The curses 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 is being discontinued.
The ncurses routines emulate the curses(3) library of System V Release 4,
and the XPG4 curses standard (XSI curses) but the ncurses library is
freely redistributable in source form. Differences from the SVr4 curses
are summarized under the EXTENSIONS and BUGS sections below and described
in detail in the EXTENSIONS and BUGS sections of individual man pages.
A program using these routines must be linked with the -lncurses option,
or (if it has been generated) with the debugging library -lncurses_g. The
ncurses_g library generates trace logs (in a file called 'trace' in the
current directory) that describe curses actions.
The ncurses package supports: overall screen, window and pad manipulation;
output to windows and pads; reading terminal input; control over terminal
and curses input and output options; environment query routines; color
manipulation; use of soft label keys; terminfo capabilities; and access to
low-level terminal-manipulation routines.
To initialize the routines, the routine initscr or newterm must be called
before any of the other routines that deal with windows and screens are
used. The routine endwin must be called before exiting. To get character-
at-a-time input without echoing (most interactive, screen oriented
programs want this), the following sequence should be used:
initscr();
cbreak();
noecho();
Most programs would additionally use the sequence:
nonl();
intrflush(stdscr, FALSE);
keypad(stdscr, TRUE);
Before a curses program is run, the tab stops of the terminal should be
set and its initialization strings, if defined, must be output. This can
be done by executing the
$ tput init
command after the shell environment variable TERM has been exported.
tset(1) is usually responsible for doing this. (See terminfo(5) for
further details.)
The curses library permits manipulation of data structures, called
windows, which can be thought of as two-dimensional arrays of characters
representing all or part of a CRT screen. A default window called stdscr
which is the size of the terminal screen, is supplied. Others may be
created with newwin(3).
Note that curses does not handle overlapping windows, that's done by the
panels(3x) library. This means that you can either use stdscr or divide
the screen into tiled windows and not using stdscr at all. Mixing the two
will result in unpredictable, and undesired, effects.
Windows are referred to by variables declared as WINDOW *. These data
structures are manipulated with routines described here and elsewhere in
the ncurses manual pages. Among which the most basic routines are move(3)
and addch(3). More general versions of these routines are included with
names beginning with w, allowing the user to specify a window. The
routines not beginning with w affect stdscr
After using routines to manipulate a window, refresh(3) is called, telling
curses to make the user's CRT screen look like stdscr The characters in a
window are actually of type chtype (character and attribute data), so that
other information about the character may also be stored with each
character.
Special windows called pads 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 curs_pad(3) for more information.
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, curses 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
, such as A_REVERSE, ACS_HLINE, and KEY_LEFT.
If the environment variables LINES and COLUMNS are set, or if the program
is executing in a window environment, line and column information in the
environment will override information read by terminfo This would effect a
program running in an AT&T 630 layer, for example, where the size of a
screen is changeable.
If the environment variable TERMINFO is defined, any program using curses
checks for a local terminal definition before checking in the standard
place. For example, if TERM is set to att4424, then the compiled terminal
definition is found in
$TERMINFO/a/att4424.
(The a is copied from the first letter of att4424 to avoid creation of
huge directories.) However, if TERMINFO is set to $HOME/myterms, curses
first checks
$HOME/myterms/a/att4424
and if that fails, it then checks
/a/att4424
This is useful for developing experimental definitions or when write
permission in is not available.
The integer variables LINES and COLS are defined in and will be
filled in by initscr(3) with the size of the screen. The constants TRUE
and FALSE have the values 1 and 0, respectively.
The curses routines also define the WINDOW * variable curscr which is used
for certain low-level operations like clearing and redrawing a screen
containing garbage. The curscr can be used in only a few routines.
Routine and Argument Names
Many curses routines have two or more versions. The routines prefixed with
w require a window argument. The routines prefixed with p require a pad
argument. Those without a prefix generally use stdscr
The routines prefixed with mv require a y and x coordinate to move to
before performing the appropriate action. The mv routines imply a call to
move(3) before the call to the other routine. The coordinate y always
refers to the row (of the window), and x always refers to the column. The
upper left-hand corner is always (0,0), not (1,1).
The routines prefixed with mvw take both a window argument and x and y
coordinates. The window argument is always specified before the
coordinates.
In each case, win is the window affected, and pad is the pad affected; win
and pad are always pointers to type WINDOW.
Option setting routines require a Boolean flag bf with the value TRUE or
FALSE; bf is always of type bool. The variables ch and attrs below are
always of type chtype. The types WINDOW, SCREEN, bool, and chtype are
defined in . The type TERMINAL is defined in . All other
arguments are integers.
Routine Name Index
The following table lists each curses routine and the name of the manual
page on which it is described. Routines flagged with `*' are ncurses not
described by XPG4 or present in SVr4.
curses Routine Name Manual Page Name
addch() curs_addch
addchnstr() curs_addchstr
addchstr() curs_addchstr
addnstr() curs_addstr
addstr() curs_addstr
attroff() curs_attr
attron() curs_attr
attrset() curs_attr
baudrate() curs_termattrs
beep() curs_beep
bkgd() curs_bkgd
bkgdset() curs_bkgd
border() curs_border
box() curs_border
can_change_color() curs_color
cbreak() curs_inopts
clear() curs_clear
clearok() curs_outopts
clrtobot() curs_clear
clrtoeol() curs_clear
color_content() curs_color
copywin() curs_overlay
curs_set() curs_kernel
def_prog_mode() curs_kernel
def_shell_mode() curs_kernel
del_curterm() curs_terminfo
delay_output() curs_util
delch() curs_delch
deleteln() curs_deleteln
delscreen() curs_initscr
delwin() curs_window
derwin() curs_window
doupdate() curs_refresh
dupwin() curs_window
echo() curs_inopts
echochar() curs_addch
endwin() curs_initscr
erase() curs_clear
erasechar() curs_termattrs
filter() curs_util
flash() curs_beep
flushinp() curs_util
getbegyx() curs_getyx
getch() curs_getch
getmaxyx() curs_getyx
getmouse() curs_mouse*
getparyx() curs_getyx
getstr() curs_getstr
getsyx() curs_kernel
getwin() curs_util
getyx() curs_getyx
halfdelay() curs_inopts
has_colors() curs_color
has_ic() curs_termattrs
has_il() curs_termattrs
hline() curs_border
idcok() curs_outopts
idlok() curs_outopts
immedok() curs_outopts
inch() curs_inch
inchnstr() curs_inchstr
inchstr() curs_inchstr
init_color() curs_color
init_pair() curs_color
initscr() curs_initscr
innstr() curs_instr
insch() curs_insch
insdelln() curs_deleteln
insertln() curs_deleteln
insnstr() curs_insstr
insstr() curs_insstr
instr() curs_instr
intrflush() curs_inopts
is_linetouched() curs_touch
is_wintouched() curs_touch
isendwin() curs_initscr
keyname() curs_util
keypad() curs_inopts
killchar() curs_termattrs
leaveok() curs_outopts
longname() curs_termattrs
meta() curs_inopts
mouseinterval() curs_mouse*
mousemask() curs_mouse*
move() curs_move
mvaddch() curs_addch
mvaddchnstr() curs_addchstr
mvaddchstr() curs_addchstr
mvaddnstr() curs_addstr
mvaddstr() curs_addstr
mvcur() curs_terminfo
mvdelch() curs_delch
mvderwin() curs_window
mvgetch() curs_getch
mvgetstr() curs_getstr
mvinch() curs_inch
mvinchnstr() curs_inchstr
mvinchstr() curs_inchstr
mvinnstr() curs_instr
mvinsch() curs_insch
mvinsnstr() curs_insstr
mvinsstr() curs_insstr
mvinstr() curs_instr
mvprintw() curs_printw
mvscanw() curs_scanw
mvwaddch() curs_addch
mvwaddchnstr() curs_addchstr
mvwaddchstr() curs_addchstr
mvwaddnstr() curs_addstr
mvwaddstr() curs_addstr
mvwdelch() curs_delch
mvwgetch() curs_getch
mvwgetstr() curs_getstr
mvwin() curs_window
mvwinch() curs_inch
mvwinchnstr() curs_inchstr
mvwinchstr() curs_inchstr
mvwinnstr() curs_instr
mvwinsch() curs_insch
mvwinsnstr() curs_insstr
mvwinsstr() curs_insstr
mvwinstr() curs_instr
mvwprintw() curs_printw
mvwscanw() curs_scanw
napms() curs_kernel
newpad() curs_pad
newterm() curs_initscr
newwin() curs_window
nl() curs_outopts
nocbreak() curs_inopts
nodelay() curs_inopts
noecho() curs_inopts
nonl() curs_outopts
noqiflush() curs_inopts
noraw() curs_inopts
notimeout() curs_inopts
overlay() curs_overlay
overwrite() curs_overlay
pair_content() curs_color
pechochar() curs_pad
pnoutrefresh() curs_pad
prefresh() curs_pad
printw() curs_printw
putp() curs_terminfo
putwin() curs_util
qiflush() curs_inopts
raw() curs_inopts
redrawwin() curs_refresh
refresh() curs_refresh
reset_prog_mode() curs_kernel
reset_shell_mode() curs_kernel
resetty() curs_kernel
restartterm() curs_terminfo
ripoffline() curs_kernel
savetty() curs_kernel
scanw() curs_scanw
scr_dump() curs_scr_dump
scr_init() curs_scr_dump
scr_restore() curs_scr_dump
scr_set() curs_scr_dump
scrl() curs_scroll
scroll() curs_scroll
scrollok() curs_outopts
set_curterm() curs_terminfo
set_term() curs_initscr
setscrreg() curs_outopts
setsyx() curs_kernel
setterm() curs_terminfo
setupterm() curs_terminfo
slk_attroff() curs_slk
slk_attron() curs_slk
slk_attrset() curs_slk
slk_clear() curs_slk
slk_init() curs_slk
slk_label() curs_slk
slk_noutrefresh() curs_slk
slk_refresh() curs_slk
slk_restore() curs_slk
slk_set() curs_slk
slk_touch() curs_slk
standend() curs_attr
standout() curs_attr
start_color() curs_color
subpad() curs_pad
subwin() curs_window
syncok() curs_window
termattrs() curs_termattrs
termname() curs_termattrs
tigetflag() curs_terminfo
tigetnum() curs_terminfo
tigetstr() curs_terminfo
timeout() curs_inopts
touchline() curs_touch
touchwin() curs_touch
tparm() curs_terminfo
tputs() curs_terminfo
typeahead() curs_inopts
unctrl() curs_util
ungetch() curs_getch
ungetmouse() curs_mouse*
untouchwin() curs_touch
use_env() curs_util
vidattr() curs_terminfo
vidputs() curs_terminfo
vline() curs_border
vwprintw() curs_printw
vwscanw() curs_scanw
waddch() curs_addch
waddchnstr() curs_addchstr
waddchstr() curs_addchstr
waddnstr() curs_addstr
waddstr() curs_addstr
wattroff() curs_attr
wattron() curs_attr
wattrset() curs_attr
wbkgd() curs_bkgd
wbkgdset() curs_bkgd
wborder() curs_border
wclear() curs_clear
wclrtobot() curs_clear
wclrtoeol() curs_clear
wcursyncup() curs_window
wdelch() curs_delch
wdeleteln() curs_deleteln
wechochar() curs_addch
wenclose() curs_mouse*
werase() curs_clear
wgetch() curs_getch
wgetnstr() curs_getstr
wgetstr() curs_getstr
whline() curs_border
winch() curs_inch
winchnstr() curs_inchstr
winchstr() curs_inchstr
winnstr() curs_instr
winsch() curs_insch
winsdelln() curs_deleteln
winsertln() curs_deleteln
winsnstr() curs_insstr
winsstr() curs_insstr
winstr() curs_instr
wmove() curs_move
wnoutrefresh() curs_refresh
wprintw() curs_printw
wredrawln() curs_refresh
wrefresh() curs_refresh
wresize() curs_resize*
wscanw() curs_scanw
wscrl() curs_scroll
wsetscrreg() curs_outopts
wstandend() curs_attr
wstandout() curs_attr
wsyncdown() curs_window
wsyncup() curs_window
wtimeout() curs_inopts
wtouchln() curs_touch
wvline() curs_border
RETURN VALUE
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(3),
wsetscrreg(3), getyx(3), getbegyx(3), getmaxyx(3). The return values of
setscrreg(3), wsetscrreg(3), getyx(3), getbegyx(3), and getmaxyx(3) 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.
PORTABILITY
The curses 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
(in alphabetical order):
add_wch(3), add_wchnstr(3), add_wchstr(3), addnwstr(3), addwstr(3),
bkgrnd(3), bkgrndset(3), border_set(3), box_set(3), echo_wchar(3),
erasewchar(3), get_wch(3), get_wstr(3), getbkgrnd(3), getn_wstr(3),
getwchtype(3), hline_set(3), in_wch(3), innwstr(3), ins_nwstr(3),
ins_wch(3), ins_wstr(3), inwchnstr(3), inwchstr(3), inwstr(3),
killwchar(3), mvadd_wch(3), mvadd_wchnstr(3), mvadd_wchstr(3),
mvaddnwstr(3), mvaddwstr(3), mvget_wch(3), mvget_wstr(3), mvgetn_wstr(3),
mvhline_set(3), mvin_wch(3), mvinnwstr(3), mvins_nwstr(3), mvins_wch(3),
mvins_wstr(3), mvinwchnstr(3), mvinwchstr(3), mvinwchstr(3), mvinwstr(3),
mvvline_set(3), mvwadd_wch(3), mvwadd_wchnstr(3), mvwadd_wchstr(3),
mvwaddnwstr(3), mvwget_ch(3), mvwget_wstr(3), mvwgetn_wstr(3),
mvwhline_set(3), mvwin_wch(3), mvwinnwstr(3), mvwins_nwstr(3),
mvwins_wch(3), mvwins_wstr(3), mvwinwchnstr(3), mvwinwstr(3),
mvwvline_set(3), vhline_set(3), wadd_wch(3), wadd_wchnstr(3),
wadd_wchstr(3), waddnwstr(3), waddwstr(3), wbkgrnd(3), wbkgrndset(3),
wborder_set(3), wecho_wchar(3), wget_wch(3), wget_wstr(3), wgetbkgrnd(3),
wgetn_wstr(3), whline_set(3), win_wch(3), winnwstr(3), wins_nwstr(3),
wins_wch(3), wins_wstr(3), winwchnstr(3), winwchstr(3), winwstr(3),
wvline_set(3).
A small number of local differences (that is, individual differences
between the XSI Curses and curses calls) are described in PORTABILITY
sections of the library man pages.
The terminfo format supported by curses is binary-compatible with SVr4,
but not conformant with XSI curses. This is because the XSI Curses
drafters, in a remarkable fit of braindamage, changed the undocumented
SVr4 capability getm from a string to a boolean, changing the binary
offsets of all capabilities after it in the SVr4 order and making it
impossible for any SVr4-compatible implementation to be fully conformant.
The routines getmouse(3), mousemask(3), ungetmouse(3), mouseinterval(3),
and wenclose(3) relating to mouse interfacing are not part of XPG4, nor
are they present in SVr4. They are also not supported under the Interix
subsystem. See the curs_mouse(3) manual page for details.
The routine wresize(3) is not part of XPG4, nor is it present in SVr4. See
the curs_resize(3) 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 tty driver. In
this implementation, all padding is done by NUL sends. This method is
slightly more expensive, but narrows the interface to the 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 form 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 const char *x
is a modifiable pointer to unmodifiable data, but char *const x' is an
unmodifiable pointer to modifiable data. Given that C passes arguments by
value, *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 * globally.
NOTES
The header file automatically includes the header files
and .
If standard output from a curses 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.
SEE ALSO
terminfo(5) and pages whose names begin curs_ for detailed routine
descriptions.