CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
NAME
curses - terminal screen handling and optimization package
SYNOPSIS
The curses manual page is organized as follows:
In SYNOPSIS
- compiling information
- summary of parameters used by curses routines
- alphabetical list of curses routines, showing their parameters
In DESCRIPTION:
- An overview of how curses routines should be used
In ROUTINES, each curses routine is described under the
appropriate heading:
- Overall Screen Manipulation
- Window and Pad Manipulation
- Output
- Input
- Output Options Setting
- Input Options Setting
- Environment Queries
- Color Manipulation
- Soft Labels
- Low-level Curses Access
- Terminfo-Level Manipulations
- Termcap Emulation
- Miscellaneous
- Use of curscr
Then come sections on:
- ATTRIBUTES
- COLORS
- FUNCTION KEYS
- LINE GRAPHICS
cc [flag ...] file ... -lcurses [library ...]
#include <curses.h> (automatically includes <stdio.h>,
<termio.h>, and <unctrl.h>).
The parameters in the following list are not global vari-
ables, but rather this is a summary of the parameters used
by the curses library routines. All routines return the int
values ERR or OK unless otherwise noted. Routines that
return pointers always return NULL on error. (ERR, OK, and
NULL are all defined in <curses.h>.)
bool bf
char **area,*boolnames[], *boolcodes[], *boolfnames[], *bp
char *cap, *capname, codename[2], erasechar, *filename, *fmt
char *keyname, killchar, *label, *longname
char *name, *numnames[], *numcodes[], *numfnames[]
char *slk_label, *str, *strnames[], *strcodes[], *strfnames[]
char *term, *tgetstr, *tigetstr, *tgoto, *tparm, *type
Rev. Extended Terminal Interface Page 1
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
chtype attrs, ch, horch, vertch
FILE *infd, *outfd
int begin_x, begin_y, begline, bot, c, col, count
int dmaxcol, dmaxrow, dmincol, dminrow, *errret, fildes
int (*init( )), labfmt, labnum, line
int ms, ncols, new, newcol, newrow, nlines, numlines
int oldcol, oldrow, overlay
int p1, p2, p9, pmincol, pminrow, (*putc( )), row
int smaxcol, smaxrow, smincol, sminrow, start
int tenths, top, visibility, x, y
short pair, f, b, color, r, g, b
SCREEN *new, *newterm, *set_term
TERMINAL *cur_term, *nterm, *oterm
va_list varglist
WINDOW *curscr, *dstwin, *initscr, *newpad, *newwin, *orig
WINDOW *pad, *srcwin, *stdscr, *subpad, *subwin, *win
addch(ch)
addstr(str)
attroff(attrs)
attron(attrs)
attrset(attrs)
baudrate()
beep()
box(win, vertch, horch)
can_change_color()
cbreak()
clear()
clearok(win, bf)
clrtobot()
clrtoeol()
color_content(color, &r, &g, &b)
copywin(srcwin, dstwin, sminrow, smincol, dminrow, dmincol,
dmaxrow, dmaxcol, overlay)
curs_set(visibility)
def_prog_mode()
def_shell_mode()
del_curterm(oterm)
delay_output(ms)
delch()
deleteln()
delwin(win)
doupdate()
draino(ms)
echo()
echochar(ch)
endwin()
erase()
erasechar()
filter()
flash()
flushinp()
garbagedlines(win, begline, numlines)
Rev. Extended Terminal Interface Page 2
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
getbegyx(win, y, x)
getch()
getmaxyx(win, y, x)
getstr(str)
getsyx(y, x)
getyx(win, y, x)
halfdelay(tenths)
has_colors()
has_ic()
has_il()
idlok(win, bf)
inch()
init_color(color, r, g, b)
init_pair(pair, f, b)
initscr()
insch(ch)
insertln()
intrflush(win, bf)
isendwin()
keyname(c)
keypad(win, bf)
killchar()
leaveok(win, bf)
longname()
meta(win, bf)
move(y, x)
mvaddch(y, x, ch)
mvaddstr(y, x, str)
mvcur(oldrow, oldcol, newrow, newcol)
mvdelch(y, x)
mvgetch(y, x)
mvgetstr(y, x, str)
mvinch(y, x)
mvinsch(y, x, ch)
mvprintw(y, x, fmt [, arg...])
mvscanw(y, x, fmt [, arg...])
mvwaddch(win, y, x, ch)
mvwaddstr(win, y, x, str)
mvwdelch(win, y, x)
mvwgetch(win, y, x)
mvwgetstr(win, y, x, str)
mvwin(win, y, x)
mvwinch(win, y, x)
mvwinsch(win, y, x, ch)
mvwprintw(win, y, x, fmt [, arg...])
mvwscanw(win, y, x, fmt [, arg...])
napms(ms)
newpad(nlines, ncols)
newterm(type, outfd, infd)
newwin(nlines, ncols, begin_y, begin_x)
nl()
nocbreak()
nodelay(win, bf)
Rev. Extended Terminal Interface Page 3
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
noecho()
nonl()
noraw()
notimeout(win, bf)
overlay(srcwin, dstwin)
overwrite(srcwin, dstwin)
pair_content(pair, &f, &b)
pechochar(pad, ch)
pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow,
smaxcol)
prefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol)
printw(fmt [, arg...])
putp(str)
raw()
refresh()
reset_prog_mode()
reset_shell_mode()
resetty()
restartterm(term, fildes, errret)
ripoffline(line, init)
savetty()
scanw(fmt [, arg...])
scr_dump(filename)
scr_init(filename)
scr_restore(filename)
scroll(win)
scrollok(win, bf)
set_curterm(nterm)
set_term(new)
setscrreg(top, bot)
setsyx(y, x)
setupterm(term, fildes, errret)
slk_clear()
slk_init(fmt)
slk_label(labnum)
slk_noutrefresh()
slk_refresh()
slk_restore()
slk_set(labnum, label, fmt)
slk_touch()
standend()
standout()
start_color()
subpad(orig, nlines, ncols, begin_y, begin_x)
subwin(orig, nlines, ncols, begin_y, begin_x)
tgetent(bp, name)
tgetflag(codename)
tgetnum(codename)
tgetstr(codename, area)
tgoto(cap, col, row)
tigetflag(capname)
tigetnum(capname)
tigetstr(capname)
Rev. Extended Terminal Interface Page 4
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
touchline(win, start, count)
touchwin(win)
tparm(str, p1, p2, ..., p9)
tputs(str, count, putc)
traceoff()
traceon()
typeahead(fildes)
unctrl(c)
ungetch(c)
vidattr(attrs)
vidputs(attrs, putc)
vwprintw(win, fmt, varglist)
vwscanw(win, fmt, varglist)
waddch(win, ch)
waddstr(win, str)
wattroff(win, attrs)
wattron(win, attrs)
wattrset(win, attrs)
wclear(win)
wclrtobot(win)
wclrtoeol(win)
wdelch(win)
wdeleteln(win)
wechochar(win, ch)
werase(win)
wgetch(win)
wgetstr(win, str)
winch(win)
winsch(win, ch)
winsertln(win)
wmove(win, y, x)
wnoutrefresh(win)
wprintw(win, fmt [, arg...])
wrefresh(win)
wscanw(win, fmt [, arg...])
wsetscrreg(win, top, bot)
wstandend(win)
wstandout(win)
DESCRIPTION
The curses routines give the user a terminal-independent
method of updating screens with reasonable optimization.
The file <curses.h> must be included at the beginning of
programs that use any curses routines. In addition, the
routine initscr() or newterm() must be called before any of
the other routines that deal with windows and screens are
used. (Three exceptions are noted where they apply.) The
routine endwin() must be called before exiting. To get
character-at-a-time input without echoing (most interactive,
screen-oriented programs want this), after calling initscr()
you should call ``cbreak(); noecho();'' Most programs would
additionally call ``nonl(); intrflush (stdscr, FALSE);
Rev. Extended Terminal Interface Page 5
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
keypad(stdscr, TRUE);''.
Before a curses program is run, a terminal's tab stops
should be set and its initialization strings, if defined,
must be output. To do this, execute tput init command after
the shell environment variable TERM has been exported. For
further details, see profile(4), tput(1), and the "Tabs and
Initialization" subsection of terminfo(4).
The curses library contains routines that manipulate data
structures called windows that can be thought of as two-
dimensional arrays of characters representing all or part of
a terminal screen. A default window called stdscr is sup-
plied, which is the size of the terminal screen. Others may
be created with newwin(). Windows are referred to by vari-
ables declared as WINDOW *; the type WINDOW is defined in
<curses.h> to be a structure. These data structures are
manipulated with routines described below, among which the
most basic are move() and addch(). (More general versions
of these routines are included with names beginning with w,
allowing you to specify a window. The routines not begin-
ning with w usually affect stdscr.) Then refresh() is
called, telling the routines to make the user's terminal
screen look like stdscr. The characters in a window are
actually of type chtype, 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 displayed completely.
See the description of newpad( ) under "Window and Pad Mani-
pulation" for more information.
In addition to drawing characters on the screen, video
attributes may be included which cause the characters to be
underlined or shown in reverse video on terminals that sup-
port 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
<curses.h>, such as A_REVERSE, ACS_HLINE, and KEY_LEFT.
Routines that manipulate color on color alphanumeric termi-
nals are new in this release of curses. To use these rou-
tines start_color() must be called, usually right after
initscr(). Colors are always used in pairs (referred to as
color-pairs). A color-pair consists of a foregound color
(for characters) and a background color (for the field the
characters are displayed on). A programmer initializes a
color-pair with the routine init_pair(). After it has been
initialized, COLOR_PAIR(n), a macro defined in <curses.h>,
can be used in the same ways other video attributes can be
Rev. Extended Terminal Interface Page 6
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
used. If a terminal is capable of redefining colors the
programmer can use the routine init_color() to change the
definition of a color. The routines has_color() and
can_change_color() return TRUE or FALSE, depending on
whether the terminal has color capabilities and whether the
user can change the colors. The routine color_content()
allows a user to identify the amounts of red, green, and
blue components in an initialized color. The routine
pair_content() allows a user to find out how a given color-
pair is currently defined.
curses also defines the WINDOW * variable, curscr, which is
used only for certain low-level operations like clearing and
redrawing a garbaged screen. curscr can be used in only a
few routines. If the window argument to clearok() is
curscr, the next call to wrefresh() with any window will
cause the screen to be cleared and repainted from scratch.
If the window argument to wrefresh() is curscr, the screen
is immediately cleared and repainted from scratch. This is
how most programs would implement a ``repaint-screen'' func-
tion. More information on using curscr is provided where
its use is appropriate.
The environment variables LINES and COLUMNS may be set to
override terminfo's idea of how large a screen is. These
may be used in an AT&T TELETYPE 5620 layer, for example,
where the size of a screen is changeable.
If the environment variable TERMINFO is defined, any program
using curses will check for a local terminal definition
before checking in the standard place. For example, if the
environment variable TERM is set to att4425, then the com-
piled terminal definition is found in
/usr/lib/terminfo/a/att4425. (The a is copied from the
first letter of att4425 to avoid creation of huge direc-
tories.) However, if TERMINFO is set to $HOME/myterms,
curses will first check $HOME/myterms/a/att4425, and, if
that fails, will then check /usr/lib/terminfo/a/att4425.
This is useful for developing experimental definitions or
when write permission on /usr/lib/terminfo is not available.
The integer variables LINES and COLS are defined in
<curses.h>, and will be filled in by initscr() with the size
of the screen. (For more information, see the subsection
"Terminfo-Level Manipulations".) The integer variables
COLORS and COLOR_PAIRS are also defined in <curses.h> and
contain, respectively, the maximum number of colors and
color-pairs the terminal can support. They are initialized
by start_color(). The constants TRUE and FALSE have the
values 1 and 0, respectively. The constants ERR and OK are
returned by routines to indicate whether the routine suc-
cessfully completed. These constants are also defined in
<curses.h>.
Rev. Extended Terminal Interface Page 7
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
ROUTINES
Many of the following 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 y and x coordinates to
move to before performing the appropriate action. The mv()
routines imply a call to move() before the call to the other
routine. The window argument is always specified before the
coordinates. y always refers to the row (of the window),
and x always refers to the column. The upper left corner is
always (0,0), not (1,1). The routines prefixed with mvw
take both a window argument and y and x coordinates.
In each case, win is the window affected and pad is the pad
affected. (win and pad are always of type WINDOW *.)
Option-setting routines require a boolean flag bf with the
value TRUE or FALSE. (bf is always of type bool.) The types
WINDOW, bool, and chtype are defined in <curses.h>. See the
SYNOPSIS for a summary of what types all variables are.
All routines return either the integer ERR or the integer
OK, unless otherwise noted. Routines that return pointers
always return NULL on error.
Sometimes the description of a routine refers to a second
routine. If the routine referred to is prefixed with a w,
then you should assume that other versions of the second
routine behave similarly. For example, the description of
initscr() refers to wrefresh(). This implies that the same
result will occur if refresh() is called.
Overall Screen Manipulation
WINDOW *initscr() The first routine called should almost
always be initscr(). (The exceptions
are slk_init(), filter(), and ripoff-
line().) This will determine the termi-
nal type and initialize all curses data
structures. initscr() also arranges
that the first call to wrefresh() will
clear the screen. If errors occur,
initscr() will write an appropriate
error message to standard error and
exit; otherwise, a pointer to stdscr is
returned. If the program wants an indi-
cation of error conditions, newterm()
should be used instead of initscr().
initscr() should only be called once per
application.
endwin() A program should always call endwin()
before exiting or escaping from curses
Rev. Extended Terminal Interface Page 8
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
mode temporarily, to do a shell escape
or system(3S) call, for example. This
routine will restore tty(7) modes, move
the cursor to the lower left corner of
the screen and reset the terminal into
the proper non-visual mode. To resume
after a temporary escape, call
wrefresh() or doupdate().
isendwin() Returns TRUE if endwin() has been called
without any subsequent calls to
wrefresh().
SCREEN *newterm(type, outfd, infd)
A program that outputs to more than one
terminal must use newterm() for each
terminal instead of initscr(). A pro-
gram that wants an indication of error
conditions, so that it may continue to
run in a line-oriented mode if the ter-
minal cannot support a screen-oriented
program, must also use this routine.
newterm() should be called once for each
terminal. It returns a variable of type
SCREEN* that should be saved as a refer-
ence to that terminal. The arguments
are the type of the terminal to be used
in place of the environment variable
TERM; outfd, a stdio(3S) file pointer
for output to the terminal; and infd,
another file pointer for input from the
terminal. When it is done running, the
program must also call endwin() for each
terminal being used. If newterm() is
called more than once for the same ter-
minal, the first terminal referred to
must be the last one for which endwin()
is called.
SCREEN *set_term(new)
This routine is used to switch between
different terminals. The screen refer-
ence new becomes the new current termi-
nal. A pointer to the screen of the
previous terminal is returned by the
routine. This is the only routine which
manipulates SCREEN pointers; all other
routines affect only the current termi-
nal.
Window and Pad Manipulation
refresh()
wrefresh (win) These routines [or prefresh(),
Rev. Extended Terminal Interface Page 9
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
pnoutrefresh(), wnoutrefresh(), or doup-
date()] must be called to write output
to the terminal, as most other routines
merely manipulate data structures.
wrefresh() copies the named window to
the physical terminal screen, taking
into account what is already there in
order to minimize the amount of informa-
tion that's sent to the terminal (called
optimization). refresh() does the same
thing, except it uses stdscr as a
default window. Unless leaveok() has
been enabled, the physical cursor of the
terminal is left at the location of the
window's cursor. The number of charac-
ters output to the terminal is returned.
Note that refresh() is a macro.
wnoutrefresh(win)
doupdate() These two routines allow multiple
updates to the physical terminal screen
with more efficiency than wrefresh()
alone. How this is accomplished is
described in the next paragraph.
curses keeps two data structures
representing the terminal screen: a phy-
sical terminal screen, describing what
is actually on the screen, and a virtual
terminal screen, describing what the
programmer wants to have on the screen.
wrefresh() works by first calling
wnoutrefresh(), which copys the named
window to the virtual screen, and then
by calling doupdate(), which compares
the virtual screen to the physical
screen and does the actual update. If
the programmer wishes to output several
windows at once, a series of calls to
wrefresh() will result in alternating
calls to wnoutrefresh() and doupdate(),
causing several bursts of output to the
screen. By first calling wnoutrefresh()
for each window, it is then possible to
call doupdate() once, resulting in only
one burst of output, with probably fewer
total characters transmitted and cer-
tainly less processor time used.
WINDOW *newwin(nlines, ncols, begin_y, begin_x)
Create and return a pointer to a new
window with the given number of lines
(or rows), nlines, and columns, ncols.
The upper left corner of the window is
at line begin_y, column begin_x. If
Rev. Extended Terminal Interface Page 10
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
either nlines or ncols is 0, they will
be set to the value of lines-begin_y and
cols-begin_x. A new full-screen window
is created by calling newwin(0,0,0,0).
mvwin(win, y, x) Move the window so that the upper left
corner will be at position (y, x). If
the move would cause any portion of the
window to be moved off the screen, it is
an error and the window is not moved.
WINDOW *subwin(orig, nlines, ncols, begin_y, begin_x)
Create and return a pointer to a new
window with the given number of lines
(or rows), nlines, and columns, ncols.
The window is at position (begin_y,
begin_x) on the screen. (This position
is relative to the screen, and not to
the window orig.) The window is made in
the middle of the window orig, so that
changes made to one window will affect
the character image of both windows.
When changing the image of a subwindow,
it will be necessary to call touchwin()
or touchline() on orig before calling
wrefresh() on orig.
delwin(win) Delete the named window, freeing up all
memory associated with it. If you try
to delete a main window before all of
its subwindows have been deleted, ERR
will be returned.
WINDOW *newpad(nlines, ncols)
Create and return a pointer to a new pad
data structure with the given number of
lines (or rows), nlines, and columns,
ncols. A pad is a window that is not
restricted by the screen size and is not
necessarily associated with a particular
part of the screen. Pads can be used
when a large window is needed, and only
a part of the window will be on the
screen at one time. Automatic refreshes
of pads (e.g. from scrolling or echoing
of input) do not occur. It is not legal
to call wrefresh() with a pad as an
argument; the routines prefresh() or
pnoutrefresh() should be called instead.
Note that these routines require addi-
tional parameters to specify the part of
the pad to be displayed and the location
on the screen to be used for display.
Rev. Extended Terminal Interface Page 11
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
WINDOW *subpad(orig, nlines, ncols, begin_y, begin_x)
Create and return a pointer to a subwin-
dow within a pad with the given number
of lines (or rows), nlines, and columns,
ncols. Unlike subwin(), which uses
screen coordinates, the window is at
position (begin_y, begin_x) on the pad.
The window is made in the middle of the
window orig, so that changes made to one
window will affect the character image
of both windows. When changing the
image of a subwindow, it will be neces-
sary to call touchwin() or touchline()
on orig before calling prefresh() on
orig.
col)
prefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smax-
pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow,
smaxcol)
These routines are analogous to wrefresh() and
wnoutrefresh() except that pads, instead of windows, are
involved. The additional parameters are needed to indicate
what part of the pad and screen are involved. pminrow and
pmincol specify the upper left corner, in the pad, of the
rectangle to be displayed. sminrow, smincol, smaxrow, and
smaxcol specify the edges, on the screen, of the rectangle
to be displayed in. The lower right corner in the pad of
the rectangle to be displayed is calculated from the screen
coordinates, since the rectangles must be the same size.
Both rectangles must be entirely contained within their
respective structures. Negative values of pminrow, pmincol,
sminrow, or smincol are treated as if they were zero.
Output
These routines are used to manipulate text in windows.
addch(ch)
waddch(win, ch)
mvaddch(y, x, ch)
mvwaddch(win, y, x, ch)
The character ch is put into the window
at the current cursor position of the
window and the position of the window
cursor is advanced. Its function is
similar to that of putchar [see
putc(3S)]. At the right margin, an
automatic newline is performed. At the
bottom of the scrolling region, if
scrollok() is enabled, the scrolling
region will be scrolled up one line.
If ch is a tab, newline, or backspace,
the cursor will be moved appropriately
within the window. A newline also does
a wclrtoeol() before moving. Tabs are
Rev. Extended Terminal Interface Page 12
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
considered to be at every eighth column.
If ch is another control character, it
will be drawn in the ^X notation. (Cal-
ling winch() on a position in the window
containing a control character will not
return the control character, but
instead will return one character of the
representation of the control charac-
ter.)
Video attributes can be combined with a
character by or-ing them into the param-
eter. This will result in these attri-
butes also being set. (The intent here
is that text, including attributes, can
be copied from one place to another
using winch() and waddch().) See
wstandout(), below.
Note that ch is actually of type chtype,
not a character.
Note that addch(), mvaddch(), and
mvwaddch(), are macros.
echochar(ch)
wechochar(win, ch)
pechochar(pad, ch) These routines are functionally
equivalent to a call to addch(ch) fol-
lowed by a call to refresh(), a call to
waddch(win, ch) followed by a call to
wrefresh(win), or a call to waddch(pad,
ch) followed by a call to prefresh(pad).
The knowledge that only a single charac-
ter is being output is taken into con-
sideration and, for non-control charac-
ters, a considerable performance gain
can be seen by using these routines
instead of their equivalents. In the
case of pechochar(), the last location
of the pad on the screen is reused for
the arguments to prefresh().
Note that ch is actually of type chtype,
not a character.
Note that echochar() is a macro.
addstr(str)
waddstr(win, str)
mvwaddstr(win, y, x, str)
mvaddstr(y, x, str) These routines write all the characters
of the null-terminated character string
str on the given window. This is
equivalent to calling waddch() once for
each character in the string.
Note that addstr(), mvaddstr(), and
mvwaddstr() are macros.
Rev. Extended Terminal Interface Page 13
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
attroff(attrs)
wattroff(win, attrs)
attron(attrs)
wattron(win, attrs)
attrset(attrs)
wattrset(win, attrs)
standend()
wstandend(win)
standout()
wstandout(win) These routines manipulate the current
attributes of the named window. These
attributes can be any combination of the
constants A_STANDOUT, A_REVERSE, A_BOLD,
A_DIM, A_BLINK, A_UNDERLINE, and
A_ALTCHARSET, as well as the macro
COLOR_PAIR(n). These attributes are
defined in <curses.h> and can be com-
bined with the C logical OR (| ) opera-
tor.
The current attributes of a window are
applied to all characters that are writ-
ten into the window with waddch().
Attributes are a property of the charac-
ter, and move with the character through
any scrolling and insert/delete
line/character operations. To the
extent possible on the particular termi-
nal, they will be displayed as the
graphic rendition of the characters put
on the screen.
wattrset(win, attrs) sets the current
attributes of the given window to attrs.
wattroff(win, attrs) turns off the named
attributes without turning on or off any
other attributes. wattron(win, attrs)
turns on the named attributes without
affecting any others. wstandout(win,
attrs) is the same as wattron(win,
A_STANDOUT). wstandend(win, attrs) is
the same as wattrset(win, 0), that is,
it turns off all attributes.
Note that wattroff(), wattron(), wat-
trset(), wstandend(), and wstandout()
return 1 at all times.
Note that attrs is actually of type
chtype, not a character.
Note that attroff(), attron(),
attrset(), standend(), and standout()
are macros.
beep()
flash() These routines are used to signal the
terminal user. beep() will sound the
audible alarm on the terminal, if
Rev. Extended Terminal Interface Page 14
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
possible, and if not, will flash the
screen (visible bell), if that is possi-
ble. flash() will flash the screen, and
if that is not possible, will sound the
audible signal. If neither signal is
possible, nothing will happen. Nearly
all terminals have an audible signal
(bell or beep) but only some can flash
the screen.
box(win, vertch, horch)
A box is drawn around the edge of the
window, win. vertch and horch are the
characters the box is to be drawn with.
If vertch and horch are 0, then
appropriate default characters,
ACS_VLINE and ACS_HLINE, will be used.
Note that vertch and horch are actually
of type chtype, not characters.
erase()
werase(win) These routines copy blanks to every
position in the window.
Note that erase() is a macro.
clear()
wclear(win) These routines are like erase() and
werase(), but they also call clearok(),
arranging that the screen will be
cleared completely on the next call to
wrefresh() for that window, and
repainted from scratch.
Note that clear() is a macro.
clrtobot()
wclrtobot(win) All lines below the cursor in this win-
dow are erased. Also, the current line
to the right of the cursor, inclusive,
is erased.
Note that clrtobot() is a macro.
clrtoeol()
wclrtoeol(win) The current line to the right of the
cursor, inclusive, is erased.
Note that clrtoeol() is a macro.
delay_output(ms) Insert a ms millisecond pause in the
output. It is not recommended that this
routine be used extensively, because
padding characters are used rather than
a processor pause.
delch()
wdelch(win)
mvdelch(y, x)
mvwdelch(win, y, x) The character under the cursor in the
window is deleted. All characters to
the right on the same line are moved to
Rev. Extended Terminal Interface Page 15
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
the left one position and the last char-
acter on the line is filled with a
blank. The cursor position does not
change (after moving to (y, x), if
specified). (This does
not imply use of the hardware ``delete-
character'' feature.)
Note that delch(), mvdelch(), and
mvwdelch() are macros.
deleteln()
wdeleteln(win) The line under the cursor in the window
is deleted. All lines below the current
line are moved up one line. The bottom
line of the window is cleared. The cur-
sor position does not change. (This
does not imply use of the hardware
``delete-line'' feature.)
Note that deleteln() is a macro.
getyx(win, y, x) The cursor position of the window is
placed in the two integer variables y
and x.
Note that getyx() is a macro, so no
``&'' is necessary before the variables
y and x.
getbegyx(win, y, x)
getmaxyx(win, y, x) The current beginning coordinates [get-
begyx()] or size [getmaxyx()] of the
specified window are placed in the two
integer variables y and x.
Note that getbegyx() and getmaxyx() are
macros, so no ``&'' is necessary before
the variables y and x.
insch(ch)
winsch(win, ch)
mvwinsch(win, y, x, ch)
mvinsch(y, x, ch) The character ch is inserted before the
character under the cursor. All charac-
ters to the right are moved one space to
the right, losing the rightmost charac-
ter of the line. The cursor position
does not change (after moving to (y, x),
if specified). (This does not imply use
of the hardware ``insert-character''
feature.)
Note that ch is actually of type chtype,
not a character.
Note that insch(), mvinsch(), and
mvwinsch() are macros.
Rev. Extended Terminal Interface Page 16
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
insertln()
winsertln(win) A blank line is inserted above the
current line and the bottom line is
lost. (This does not imply use of the
hardware ``insert-line'' feature.)
Note that insertln() is a macro.
move(y, x)
wmove(win, y, x) The cursor associated with the window is
moved to line (row) y, column x. This
does not move the physical cursor of the
terminal until wrefresh() is called.
The position specified is relative to
the upper left corner of the window,
which is (0, 0).
Note that move() is a macro.
overlay(srcwin, dstwin)
overwrite(srcwin, dstwin)
These routines overlay text from srcwin
on top of text from dstwin wherever the
two windows overlap. The difference is
that overlay() is non-destructive
(blanks are not copied), while
overwrite() is destructive.
row,
copywin(srcwin, dstwin, sminrow, smincol, dminrow, dmincol, dmax-
dmaxcol, overlay)
This routine provides finer control over
the overlay() and overwrite() routines.
As in the prefresh() routine, a rectan-
gle is specified in the destination win-
dow, (dminrow, dmincol) and (dmaxrow,
dmaxcol), and the upper-left-corner
coordinates of the source window, (smin-
row, smincol). If the argument overlay
is true, then copying is non-
destructive, as in overlay().
printw(fmt [, arg...])
wprintw(win, fmt [, arg...])
mvprintw(y, x, fmt [, arg...])
mvwprintw(win, y, x, fmt [, arg...])
These routines are analogous to
printf(3). The string which would be
output by printf(3) is instead output
using waddstr() on the given window.
vwprintw(win, fmt, varglist)
This routine corresponds to
vfprintf(3S). It performs a wprintw()
using a variable argument list. The
third argument is a va_list, a pointer
to a list of arguments, as defined in
<varargs.h>. See the vprintf(3S) and
varargs(5) manual pages for a detailed
Rev. Extended Terminal Interface Page 17
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
description on how to use variable argu-
ment lists.
scroll(win) The window is scrolled up one line.
This involves moving the lines in the
window data structure.
touchwin(win)
touchline(win, start, count)
Throw away all optimization information
about which parts of the window have
been touched, by pretending that the
entire window has been drawn on. This
is sometimes necessary when using over-
lapping windows, since a change to one
window will affect the other window, but
the records of which lines have been
changed in the other window will not
reflect the change. touchline() only
pretends that count lines have been
changed, beginning with line start .
Input
getch()
wgetch(win)
mvgetch(y, x)
mvwgetch(win, y, x) A character is read from the terminal
associated with the window. In NODELAY
mode, if there is no input waiting, the
value ERR is returned. In DELAY mode,
the program will hang until the system
passes text through to the program.
Depending on the setting of cbreak(),
this will be after one character (CBREAK
mode), or after the first newline (NOC-
BREAK mode). In HALF-DELAY mode, the
program will hang until a character is
typed or the specified timeout has been
reached. Unless noecho() has been set,
the character will also be echoed into
the designated window.
When wgetch() is called, before getting
a character, it will call wrefresh() if
anything in the window has changed (for
example, the cursor has moved or text
changed).
When using getch(), wgetch(), mvgetch(),
or mvwgetch(), do not set both NOCBREAK
mode [nocbreak()] and ECHO mode [echo()]
at the same time. Depending on the
state of the tty(7) driver when each
character is typed, the program may pro-
duce undesirable results.
If wgetch() encounters a ^D, it is
Rev. Extended Terminal Interface Page 18
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
returned (unlike stdio routines, which
would return a null string and have a
return code of -1).
If keypad(win, TRUE) has been called,
and a function key is pressed, the token
for that function key will be returned
instead of the raw characters. (See
keypad() under "Input Options Setting.")
Possible function keys are defined in
<curses.h> with integers beginning with
0401, whose names begin with KEY_. If a
character is received that could be the
beginning of a function key (such as
escape), curses will set a timer. If
the remainder of the sequence is not
received within the designated time, the
character will be passed through, other-
wise the function key value will be
returned. For this reason, on many ter-
minals, there will be a delay after a
user presses the escape key before the
escape is returned to the program. (Use
by a programmer of the escape key for a
single character routine is discouraged.
Also see notimeout() below.)
Note that getch(), mvgetch(), and
mvwgetch() are macros.
getstr(str)
wgetstr(win, str)
mvgetstr(y, x, str)
mvwgetstr(win, y, x, str)
A series of calls to wgetch() is made,
until a newline, carriage return, or
enter key is received. The resulting
value (except for this terminating char-
acter) is placed in the area pointed at
by the character pointer str. The
user's erase and kill characters are
interpreted. See wgetch() for how it
handles characters differently from
stdio routines (especially ^D).
Note that getstr(), mvgetstr(), and
mvwgetstr() are macros.
ungetch(c) Place c onto the input queue, to be
returned by the next call to wgetch().
flushinp() Throws away any typeahead that has been
typed by the user and has not yet been
read by the program. Note that
flushinp() will not throw away any char-
acters supplied by ungetch().
inch()
Rev. Extended Terminal Interface Page 19
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
winch(win)
mvinch(y, x)
mvwinch(win, y, x) The character, of type chtype, at the
current position in the named window is
returned. If any attributes are set for
that position, their values will be
OR'ed into the value returned. The
predefined constants A_CHARTEXT and
A_ATTRIBUTES, defined in <curses.h>, can
be used with the C logical AND (&)
operator to extract the character or
attributes alone.
Note that inch(), winch(), mvinch(), and
mvwinch() are macros.
scanw(fmt [, arg...])
wscanw(win, fmt [, arg...])
mvscanw(y, x, fmt [, arg...])
mvwscanw(win, y, x, fmt [, arg...])
These routines correspond to scanf(3S),
as do their arguments and return values.
wgetstr() is called on the window, and
the resulting line is used as input for
the scan. The return value for these
routines is the number of arg values
that are converted by fmt. arg values
that are not converted are lost. See
wgetstr() for how it handles strings
differently from the stdio routines
(especially ^D).
vwscanw(win, fmt, ap)
This routine is similar to vwprintw() in
that it performs a wscanw() using a
variable argument list. The third argu-
ment is a va_list, a pointer to a list
of arguments, as defined in <varargs.h>.
See the vprintf(3S) and varargs(5)
manual pages for a detailed description
on how to use variable argument lists.
Output Options Setting
These routines set options within curses that deal with out-
put. All options are initially FALSE, unless otherwise
stated. It is not necessary to turn these options off
before calling endwin().
clearok(win, bf) If enabled (bf is TRUE), the next call
to wrefresh() with this window will
clear the screen completely and redraw
the entire screen from scratch. This is
useful when the contents of the screen
are uncertain, or in some cases for a
more pleasing visual effect.
Rev. Extended Terminal Interface Page 20
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
idlok(win, bf) If enabled (bf is TRUE), curses will
consider using the hardware
``insert/delete-line'' feature of termi-
nals so equipped. If disabled (bf is
FALSE), curses will very seldom use this
feature. (The ``insert/delete-
character'' feature is always con-
sidered.) This option should be enabled
only if your application needs
``insert/delete-line'', for example, for
a screen editor. It is disabled by
default because ``insert/delete-line''
tends to be visually annoying when used
in applications where it isn't really
needed. If ``insert/delete-line'' can-
not be used, curses will redraw the
changed portions of all lines. Not cal-
ling idlok() saves approximately 5000
bytes of memory.
leaveok(win, bf) Normally, the hardware cursor is left at
the location of the window cursor being
refreshed. This option allows the cur-
sor to be left wherever the update hap-
pens to leave it. It is useful for
applications where the cursor is not
used, since it reduces the need for cur-
sor motions. If possible, the cursor is
made invisible when this option is
enabled.
setscrreg(top, bot)
wsetscrreg(win, top, bot)
These routines allow the user to set a
software scrolling region in a window.
top and bot are the line numbers of the
top and bottom margin of the scrolling
region. (Line 0 is the top line of the
window.) If this option and scrollok()
are enabled, an attempt to move off the
bottom margin line will cause all lines
in the scrolling region to scroll up one
line. (Note that this has nothing to do
with use of a physical scrolling region
capability in the terminal, like that in
the DEC VT100. Only the text of the
window is scrolled; if idlok() is
enabled and the terminal has either a
scrolling region or ``insert/delete-
line'' capability, they will probably be
used by the output routines.)
Note that setscrreg() is a macro.
scrollok(win, bf) This option controls what happens when
Rev. Extended Terminal Interface Page 21
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
the cursor of a window is moved off the
edge of the window or scrolling region,
either from a newline on the bottom
line, or typing the last character of
the last line. If disabled (bf is
FALSE), the cursor is left on the bottom
line at the location where the offending
character was entered. If enabled (bf
is TRUE), wrefresh() is called on the
window, and then the physical terminal
and window are scrolled up one line.
(Note that in order to get the physical
scrolling effect on the terminal, it is
also necessary to call idlok().)
Note that scrollok() will always return
OK.
Input Options Setting
These routines set options within curses that deal with
input. The options involve using ioctl(2) and therefore
interact with curses routines. It is not necessary to turn
these options off before calling endwin().
For more information on these options, see the chapter of
the Programmer's Guide that describes how to write curses
programs.
cbreak()
nocbreak() These two routines put the terminal into
and out of CBREAK mode, respectively.
In CBREAK mode, characters typed by the
user are immediately available to the
program and erase/kill character pro-
cessing is not performed. When in NOC-
BREAK mode, the tty driver will buffer
characters typed until a newline or car-
riage return is typed. Interrupt and
flow-control characters are unaffected
by this mode [see termio(7)]. Initially
the terminal may or may not be in CBREAK
mode, as it is inherited, therefore, a
program should call cbreak() or noc-
break() explicitly. Most interactive
programs using curses will set CBREAK
mode.
Note that cbreak() performs a subset of
the functionality of raw(). See
wgetch() under "Input" for a discussion
of how these routines interact with
echo() and noecho().
echo()
noecho() These routines control whether charac-
ters typed by the user are echoed by
wgetch() as they are typed. Echoing by
the tty driver is always disabled, but
Rev. Extended Terminal Interface Page 22
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
initially wgetch() is in ECHO mode, so
characters typed are echoed. Authors of
most interactive programs prefer to do
their own echoing in a controlled area
of the screen, or not to echo at all, so
they disable echoing by calling noe-
cho(). See wgetch() under "Input" for a
discussion of how these routines
interact with cbreak() and nocbreak().
nl()
nonl() These routines control whether carriage
return is translated into newline on
input by wgetch(). Initially, this
translation is done; nonl() turns the
translation off. Note that translation
by the tty(7) driver is disabled in
CBREAK mode.
halfdelay(tenths) Half-delay mode is similar to CBREAK
mode in that characters typed by the
user are immediately available to the
program. However, after blocking for
tenths tenths of seconds, ERR will be
returned if nothing has been typed.
tenths must be a number between 1 and
255. Use nocbreak() to leave half-delay
mode.
intrflush(win, bf) If this option is enabled, when an
interrupt key is pressed on the keyboard
(interrupt, break, quit) all output in
the tty driver queue will be flushed,
giving the effect of faster response to
the interrupt, but causing curses to
have the wrong idea of what is on the
screen. Disabling the option prevents
the flush. The default for the option
is inherited from the tty driver set-
tings. The window argument is ignored.
keypad(win, bf) This option enables curses to obtain
information from the keypad of the
user's terminal. If enabled, the user
can press a function key (such as an
arrow key) and wgetch() will return a
single value representing the function
key, as in KEY_LEFT. If disabled,
curses will not treat function keys spe-
cially and the program would have to
interpret the escape sequences itself.
If the keypad in the terminal can be
turned on (made to transmit), calling
keypad (win, TRUE) will turn it on.
Rev. Extended Terminal Interface Page 23
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
meta(win, bf) Initially, whether the terminal returns
7 or 8 significant bits on input depends
on the control mode of the tty driver
[see termio(7)]. To force 8 bits to be
returned, invoke meta (win, TRUE). To
force 7 bits to be returned, invoke meta
(win, FALSE). The window argument, win,
is always ignored. If the terminfo(4)
capabilities smm (meta_on) and rmm
(meta_off) are defined for the termi-
nal, smm will be sent to the terminal
when meta (win, TRUE) is called and rmm
will be sent when meta (win, FALSE) is
called.
nodelay(win, bf) This option causes wgetch() to be a
non-blocking call. If no input is
ready, wgetch() will return ERR. If
disabled, wgetch() will hang until a key
is pressed.
notimeout(win, bf) While interpreting an input escape
sequence, wgetch() will set a timer
while waiting for the next character.
If notimeout(win, TRUE) is called, then
wgetch() will not set a timer. The pur-
pose of the timeout is to differentiate
between sequences received from a func-
tion key and those typed by a user.
raw()
noraw() The terminal is placed into or out of
RAW mode. RAW mode is similar to CBREAK
mode, in that characters typed are
immediately passed through to the user
program; however, in RAW mode, the
interrupt, quit, suspend, and flow con-
trol characters are passed through unin-
terpreted, instead of generating a sig-
nal as they do in CBREAK mode. The
behavior of the BREAK key depends on
other bits in the tty(7) driver that are
not set by curses.
typeahead(fildes) curses does ``line-breakout optimiza-
tion'' by looking for typeahead periodi-
cally while updating the screen. If
input is found, and it is coming from a
tty, the current update will be post-
poned until wrefresh() or doupdate() is
called again. This allows faster
response to commands typed in advance.
Normally, the file descriptor for the
input FILE pointer passed to newterm(),
Rev. Extended Terminal Interface Page 24
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
or stdin in the case that initscr() was
used, will be used to do this typeahead
checking. The typeahead() routine
specifies that the file descriptor
fildes is to be used to check for typea-
head instead. If fildes is -1, then no
typeahead checking will be done.
Note that fildes is a file descriptor,
not a <stdio.h> FILE pointer.
Environment Queries
baudrate() Returns the output speed of the termi-
nal. The number returned is in bits per
second, for example, 9600, and is an
integer.
char erasechar() The user's current erase character is
returned.
has_ic() True if the terminal has insert- and
delete-character capabilities.
has_il() True if the terminal has insert- and
delete-line capabilities, or can simu-
late them using scrolling regions. This
might be used to check to see if it
would be appropriate to turn on physical
scrolling using scrollok() or idlok().
char killchar() The user's current line-kill character
is returned.
char *longname() This routine returns a pointer to a
static area containing a verbose
description of the current terminal.
The maximum length of a verbose descrip-
tion is 128 characters. It is defined
only after the call to initscr() or
newterm(). The area is overwritten by
each call to newterm() and is not
restored by set_term(), so the value
should be saved between calls to
newterm() if longname() is going to be
used with multiple terminals.
Color Manipulation
This section describes the color manipulation routines
introduced in this release of curses.
can_change_color() This routine requires no arguments. It
returns TRUE if the terminal supports
colors and can change their definitions,
FALSE otherwise. This routine
Rev. Extended Terminal Interface Page 25
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
facilitates writing terminal-independent
programs.
color_content(color, &r, &g, &b)
This routine gives users a way to find
the intensity of the red, green, and
blue (RGB) components in a color. It
requires four arguments: the color
number, and three addresses of shorts
for storing the information about the
amounts of red, green, and blue com-
ponents in the given color. The value
of the first argument must be between 0
and COLORS-1. The values that will be
stored at the addresses pointed to by
the last three arguments will be between
0 (no component) and 1000 (maximum
amount of component). This routine
returns ERR if the color does not exist
(the first argument is outside the valid
range), or if the terminal cannot change
color definitions, OK otherwise.
has_colors() This routine requires no arguments. It
returns TRUE if the terminal can manipu-
late colors, FALSE otherwise. This rou-
tine facilitates writing terminal-
independent programs. For example, a
programmer can use it to decide whether
to use color or some other video attri-
bute.
init_color(color, r, g, b)
This routine changes the definition of a
color. It takes four arguments: the
number of the color to be changed fol-
lowed by three RGB values (for the
amounts of red, green, and blue com-
ponents). (See the section COLOR for
the default color index.) The value of
the first argument must be between 0 and
COLORS-1. The last three arguments must
each be a value between 0 and 1000.
When init_color() is used, all
occurrences of that color on the screen
immediately change to the new defini-
tion. It returns OK if it was able to
change the definition of the color, ERR
otherwise.
init_pair(pair, f, b)
This routine changes the definition of a
color-pair. It takes three arguments:
Rev. Extended Terminal Interface Page 26
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
the number of the color-pair to be
changed, the foreground color number,
and the background color number. The
value of the first argument must be
between 1 and COLOR_PAIRS-1. The value
of the second and third arguments must
be between 0 and COLORS-1. If the
color-pair was previously initialized,
the screen will be refreshed and all
occurrences of that color-pair will be
changed to the new definition. The rou-
tine returns OK if it was able to change
the definition of the color-pair, ERR
otherwise.
pair_content(pair, &f, &b)
This routine allows users to find out
what colors a given color-pair consists
of. It requires three arguments: the
color-pair number, and two addresses of
shorts for storing the foreground and
the background color numbers. The value
of the first argument must be between 1
and COLOR_PAIRS-1. The values that will
be stored at the addresses pointed to by
the second and third arguments will be
between 0 and COLORS-1. The routine
returns ERR if the color_pair has not
been initialized, OK otherwise.
start_color() This routine requires no arguments. It
must be called if the user wants to use
colors, and before any other color mani-
pulation routine is called. It is good
practice to call this routine right
after initscr(). start_color() initial-
izes eight basic colors (black, blue,
green, cyan, red, magenta, yellow, and
white), and two global variables, COLORS
and COLOR_PAIRS (respectively defining
the maximum number of colors and color-
pairs the terminal can support). It
also restores the terminal's colors to
the values they had when the terminal
was just turned on. It returns ERR if
the terminal does not support colors, OK
otherwise.
Soft Labels
If desired, curses will manipulate the set of soft
function-key labels that exist on many terminals. For those
terminals that do not have soft labels, if you want to simu-
late them, curses will take over the bottom line of stdscr,
Rev. Extended Terminal Interface Page 27
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
reducing the size of stdscr and the variable LINES. curses
standardizes on 8 labels of 8 characters each. If a curses
program changes the values of the soft labels, it can
restore them only to the default settings for that terminal.
Therefore, if before calling a curses program a user changes
the values of the soft labels, those values cannot be reset
when the curses program terminates.
slk_init(labfmt) In order to use soft labels, this rou-
tine must be called before initscr() or
newterm() is called. If initscr() winds
up using a line from stdscr to emulate
the soft labels, then labfmt determines
how the labels are arranged on the
screen. Setting labfmt to 0 indicates
that the labels are to be arranged in a
3-2-3 arrangement; 1 asks for a 4-4
arrangement.
slk_set(labnum, label, labfmt)
labnum is the label number, from 1 to 8.
label is the string to be put on the
label, up to 8 characters in length. A
NULL string or a NULL pointer will put
up a blank label. labfmt is one of 0, 1
or 2, to indicate whether the label is
to be left-justified, centered, or
right-justified within the label.
slk_refresh()
slk_noutrefresh() These routines correspond to the rou-
tines wrefresh() and wnoutrefresh().
Most applications would use
slk_noutrefresh() because a wrefresh()
will most likely soon follow.
char *slk_label(labnum)
The current label for label number lab-
num is returned, in the same format as
it was in when it was passed to
slk_set(); that is, how it looked prior
to being justified according to the
labfmt argument of slk_set().
slk_clear() The soft labels are cleared from the
screen.
slk_restore() The soft labels are restored to the
screen after a slk_clear().
slk_touch() All of the soft labels are forced to be
output the next time a slk_noutrefresh()
is performed.
Rev. Extended Terminal Interface Page 28
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
Low-Level curses Access
The following routines give low-level access to various
curses functionality. These routines typically would be
used inside of library routines.
def_prog_mode()
def_shell_mode() Save the current terminal modes as the
``program'' (in curses) or ``shell''
(not in curses) state for use by the
reset_prog_mode() and reset_shell_mode()
routines. This is done automatically by
initscr().
reset_prog_mode()
reset_shell_mode() Restore the terminal to ``program'' (in
curses) or ``shell'' (out of curses)
state. These are done automatically by
endwin() and doupdate() after an
endwin(), so they normally would not be
called.
resetty()
savetty() These routines save and restore the
state of the terminal modes. savetty()
saves the current state of the terminal
in a buffer and resetty() restores the
state to what it was at the last call to
savetty().
getsyx(y, x) The current coordinates of the virtual
screen cursor are returned in y and x.
If leaveok() is currently TRUE, then
-1,-1 will be returned. If lines have
been removed from the top of the screen
using ripoffline(), y and x include
these lines; therefore, y and x should
be used only as arguments for setsyx().
Note that getsyx() is a macro, so no
``&'' is necessary before the variables
y and x.
setsyx(y, x) The virtual screen cursor is set to y,
x. If y and x are both -1, then
leaveok() will be set. The two routines
getsyx() and setsyx() are designed to be
used by a library routine which manipu-
lates curses windows but does not want
to change the current position of the
program's cursor. The library routine
would call getsyx() at the beginning, do
its manipulation of its own windows, do
a wnoutrefresh() on its windows, call
setsyx(), and then call doupdate().
ripoffline(line, init)
This routine provides access to the same
Rev. Extended Terminal Interface Page 29
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
facility that slk_init() uses to reduce
the size of the screen. ripoffline()
must be called before initscr() or
newterm() is called. If line is posi-
tive, a line will be removed from the
top of stdscr; if negative, a line will
be removed from the bottom. When this
is done inside initscr(), the routine
init() is called with two arguments: a
window pointer to the 1-line window that
has been allocated and an integer with
the number of columns in the window.
Inside this initialization routine, the
integer variables LINES and COLS
(defined in <curses.h>) are not
guaranteed to be accurate and wrefresh()
or doupdate() must not be called. It is
allowable to call wnoutrefresh() during
the initialization routine.
ripoffline() can be called up to five
times before calling initscr() or
newterm().
scr_dump(filename) The current contents of the virtual
screen are written to the file filename.
scr_restore(filename)
The virtual screen is set to the con-
tents of filename, which must have been
written using scr_dump(). ERR is
returned if the contents of filename are
not compatible with the current release
of curses software. The next call to
doupdate() will restore the screen to
what it looked like in the dump file.
scr_init(filename) The contents of filename are read in and
used to initialize the curses data
structures about what the terminal
currently has on its screen. If the
data is determined to be valid, curses
will base its next update of the screen
on this information rather than clearing
the screen and starting from scratch.
scr_init() would be used after initscr()
or a system(3S) call to share the screen
with another process which has done a
scr_dump() after its endwin() call. The
data will be declared invalid if the
terminfo(4) capability nrrmc is true or
the time-stamp of the tty is old. Note
that keypad(), meta(), slk_clear(),
curs_set(), flash(), and beep() do not
Rev. Extended Terminal Interface Page 30
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
affect the contents of the screen, but
will make the tty's time-stamp old.
curs_set(visibility)
The cursor state is set to invisible,
normal, or very visible for visibility
equal to 0, 1 or 2. If the terminal
supports the visibility requested, the
previous cursor state is returned; oth-
erwise, ERR is returned.
draino(ms) Wait until the output has drained enough
that it will only take ms more mil-
liseconds to drain completely.
garbagedlines(win, begline, numlines)
This routine indicates to curses that a
screen line is garbaged and should be
thrown away before having anything writ-
ten over the top of it. It could be
used for programs such as editors which
want a command to redraw just a single
line. Such a command could be used in
cases where there is a noisy communica-
tions line and redrawing the entire
screen would be subject to even more
communication noise. Just redrawing the
single line gives some semblance of hope
that it would show up unblemished. The
current location of the window is used
to determine which lines are to be
redrawn.
napms(ms) Sleep for ms milliseconds.
mvcur(oldrow, oldcol, newrow, newcol)
Low-level cursor motion.
Terminfo-Level Manipulations
These low-level routines must be called by programs that
need to deal directly with the terminfo(4) database to han-
dle certain terminal capabilities, such as programming func-
tion keys. For all other functionality, curses routines are
more suitable and their use is recommended.
Initially, setupterm() should be called. (Note that setup-
term() is automatically called by initscr() and newterm().)
This will define the set of terminal-dependent variables
defined in the terminfo(4) database. The terminfo(4) vari-
ables lines and columns [see terminfo(4)] are initialized by
setupterm() as follows: if the environment variables LINES
and COLUMNS exist, their values are used. If the above
environment variables do not exist and the program is
Rev. Extended Terminal Interface Page 31
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
running in a layer [see layers(1)], the size of the current
layer is used. Otherwise, the values for lines and columns
specified in the terminfo(4) database are used.
The header files <curses.h> and <term.h> should be included,
in this order, to get the definitions for these strings,
numbers, and flags. Parameterized strings should be passed
through tparm() to instantiate them. All terminfo(4)
strings [including the output of tparm()] should be printed
with tputs() or putp(). Before exiting, reset_shell_mode()
should be called to restore the tty modes. Programs which
use cursor addressing should output enter_ca_mode upon
startup and should output exit_ca_mode before exiting [see
terminfo(4)]. (Programs desiring shell escapes should call
reset_shell_mode() and output exit_ca_mode before the shell
is called and should output enter_ca_mode and call
reset_prog_mode() after returning from the shell. Note that
this is different from the curses routines [see endwin()].
setupterm(term, fildes, errret)
Reads in the terminfo(4) database, ini-
tializing the terminfo(4) structures,
but does not set up the output virtuali-
zation structures used by curses. The
terminal type is in the character string
term; if term is NULL, the environment
variable TERM will be used. All output
is to the file descriptor fildes. If
errret is not NULL, then setupterm()
will return OK or ERR and store a status
value in the integer pointed to by
errret. A status of 1 in errret is nor-
mal, 0 means that the terminal could not
be found, and -1 means that the ter-
minfo(4) database could not be found.
If errret is NULL, setupterm() will
print an error message upon finding an
error and exit. Thus, the simplest call
is setupterm ((char *)0, 1, (int *)0),
which uses all the defaults.
The terminfo(4) boolean, numeric and
string variables are stored in a struc-
ture of type TERMINAL. After setup-
term() returns successfully, the vari-
able cur_term (of type TERMINAL *) is
initialized with all of the information
that the terminfo(4) boolean, numeric
and string variables refer to. The
pointer may be saved before calling
setupterm() again. Further calls to
setupterm() will allocate new space
rather than reuse the space pointed to
by cur_term.
Rev. Extended Terminal Interface Page 32
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
set_curterm(nterm) nterm is of type TERMINAL *.
set_curterm() sets the variable cur_term
to nterm, and makes all of the ter-
minfo(4) boolean, numeric and string
variables use the values from nterm.
del_curterm(oterm) oterm is of type TERMINAL *.
del_curterm() frees the space pointed to
by oterm and makes it available for
further use. If oterm is the same as
cur_term, then references to any of the
terminfo(4) boolean, numeric and string
variables thereafter may refer to
invalid memory locations until another
setupterm() has been called.
restartterm(term, fildes, errret)
Similar to setupterm(), except that it
is called after restoring memory to a
previous state; for example, after a
call to scr_restore(). It assumes that
the windows and the input and output
options are the same as when memory was
saved, but the terminal type and baud
rate may be different.
char *tparm(str, p1, p2, ..., p9)
Instantiate the string str with parms
pi. A pointer is returned to the result
of str with the parameters applied.
tputs(str, count, putc)
Apply padding to the string str and out-
put it. str must be a terminfo(4)
string variable or the return value from
tparm(), tgetstr(), tigetstr() or
tgoto(). count is the number of lines
affected, or 1 if not applicable. putc
is a putchar(3S)-like routine to which
the characters are passed, one at a
time.
putp(str) A routine that calls tputs (str, 1,
putchar).
vidputs(attrs, putc)
Output a string that puts the terminal
in the video attribute mode attrs, which
is any combination of the attributes
listed below. The characters are passed
to the putchar(3S)-like routine putc().
vidattr(attrs) Similar to vidputs(), except that it
Rev. Extended Terminal Interface Page 33
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
outputs through putchar(3S).
The following routines return the value of the capability
corresponding to the character string containing the ter-
minfo(4) capname passed to them. For example, rc =
tigetstr("acsc") causes the value of acsc to be returned in
rc.
tigetflag(capname) The value -1 is returned if capname is
not a boolean capability. The value 0
is returned if capname is not defined
for this terminal.
tigetnum(capname) The value -2 is returned if capname is
not a numeric capability. The value -1
is returned if capname is not defined
for this terminal.
tigetstr(capname) The value (char *) -1 is returned if
capname is not a string capability. A
null value is returned if capname is not
defined for this terminal.
char *boolnames[], *boolcodes[], *boolfnames[]
char *numnames[], *numcodes[], *numfnames[]
char *strnames[], *strcodes[], *strfnames[]
These null-terminated arrays contain the
capnames, the termcap codes, and the
full C names, for each of the ter-
minfo(4) variables.
Termcap Emulation
These routines are included as a conversion aid for programs
that use the termcap library. Their parameters are the same
and the routines are emulated using the terminfo(4) data-
base.
tgetent(bp, name) Look up termcap entry for name. The
emulation ignores the buffer pointer bp.
tgetflag(codename) Get the boolean entry for codename.
tgetnum(codename) Get numeric entry for codename.
char *tgetstr(codename, area)
Return the string entry for codename.
If area is not NULL, then also store it
in the buffer pointed to by area and
advance area. tputs() should be used to
output the returned string.
Rev. Extended Terminal Interface Page 34
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
char *tgoto(cap, col, row)
Instantiate the parameters into the
given capability. The output from this
routine is to be passed to tputs().
tputs(str, affcnt, putc)
See tputs() above, under "Terminfo-Level
Manipulations".
Miscellaneous
traceoff()
traceon() Turn off and on debugging trace output
when using the debug version of the
curses library, /usr/lib/libdcurses.a.
This facility is available only to cus-
tomers with a source license.
unctrl(c) This macro expands to a character string
which is a printable representation of
the character c. Control characters are
displayed in the ^X notation. Printing
characters are displayed as is.
unctrl() is a macro, defined in
<unctrl.h>, which is automatically
included by <curses.h>.
char *keyname(c) A character string corresponding to the
key c is returned.
filter() This routine is one of the few that is
to be called before initscr() or
newterm() is called. It arranges things
so that curses thinks that there is a
1-line screen. curses will not use any
terminal capabilities that assume that
they know what line on the screen the
cursor is on.
Use of curscr
The special window curscr can be used in only a few rou-
tines. If the window argument to clearok() is curscr, the
next call to wrefresh() with any window will cause the
screen to be cleared and repainted from scratch. If the
window argument to wrefresh() is curscr, the screen is
immediately cleared and repainted from scratch. (This is
how most programs would implement a ``repaint-screen'' rou-
tine.) The source window argument to overlay(),
overwrite(), and copywin() may be curscr, in which case the
current contents of the virtual terminal screen will be
accessed.
Obsolete Calls
Rev. Extended Terminal Interface Page 35
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
Various routines are provided to maintain compatibility in
programs written for older versions of the curses library.
These routines are all emulated as indicated below.
crmode() Replaced by cbreak().
fixterm() Replaced by reset_prog_mode().
gettmode() A no-op.
nocrmode() Replaced by nocbreak().
resetterm() Replaced by reset_shell_mode().
saveterm() Replaced by def_prog_mode().
setterm() Replaced by setupterm().
ATTRIBUTES
The following video attributes, defined in <curses.h>, can
be passed to the routines wattron(), wattroff(), and wat-
trset(), or OR'ed with the characters passed to waddch().
A_STANDOUT Terminal's best highlighting mode
A_UNDERLINE Underlining
A_REVERSE Reverse video
A_BLINK Blinking
A_DIM Half bright
A_BOLD Extra bright or bold
A_ALTCHARSET Alternate character set
COLOR_PAIR(n) Color_pair defined in n (Note that this is a macro.)
A_CHARTEXT Bit-mask to extract character [refer to winch()]
A_ATTRIBUTES Bit-mask to extract attributes [refer to winch()]
A_NORMAL Bit mask to reset all attributes off
(for example: wattrset (win, A_NORMAL)
A_COLOR Bit-mask to extract color_pair field information
PAIR_NUMBER(attrs) Returns the pair number associated with the
COLOR_PAIR(n) attribute.
(Note that this is a macro.)
COLORS
In <curses.h> the following macros are defined to have the
numeric value shown. These are the default colors. curses
also assumes that color 0 (zero) is the default background
color for all terminals.
COLOR_BLACK 0
COLOR_BLUE 1
COLOR_GREEN 2
COLOR_CYAN 3
COLOR_RED 4
Rev. Extended Terminal Interface Page 36
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
COLOR_MAGENTA 5
COLOR_YELLOW 6
COLOR_WHITE 7
FUNCTION KEYS
The following function keys, defined in <curses.h>, might be
returned by wgetch() if keypad() has been enabled. Note
that not all of these may be supported on a particular ter-
minal if the terminal does not transmit a unique code when
the key is pressed or the definition for the key is not
present in the terminfo(4) database.
Name Value Key name
KEY_BREAK 0401 break key (unreliable)
KEY_DOWN 0402 The four arrow keys ...
KEY_UP 0403
KEY_LEFT 0404
KEY_RIGHT 0405 ...
KEY_HOME 0406 Home key (upward+left arrow)
KEY_BACKSPACE 0407 backspace (unreliable)
KEY_F0 0410 Function keys. Space for 64 keys is reserved.
KEY_F(n) (KEY_F0+(n)) Formula for fn.
KEY_DL 0510 Delete line
KEY_IL 0511 Insert line
KEY_DC 0512 Delete character
KEY_IC 0513 Insert char or enter insert mode
KEY_EIC 0514 Exit insert char mode
KEY_CLEAR 0515 Clear screen
KEY_EOS 0516 Clear to end of screen
KEY_EOL 0517 Clear to end of line
KEY_SF 0520 Scroll 1 line forward
KEY_SR 0521 Scroll 1 line backwards (reverse)
KEY_NPAGE 0522 Next page
KEY_PPAGE 0523 Previous page
KEY_STAB 0524 Set tab
KEY_CTAB 0525 Clear tab
KEY_CATAB 0526 Clear all tabs
KEY_ENTER 0527 Enter or send
KEY_SRESET 0530 soft (partial) reset
KEY_RESET 0531 reset or hard reset
KEY_PRINT 0532 print or copy
KEY_LL 0533 home down or bottom (lower left)
keypad is arranged like this:
A1 up A3
left B2 right
C1 down C3
KEY_A1 0534 Upper left of keypad
KEY_A3 0535 Upper right of keypad
KEY_B2 0536 Center of keypad
KEY_C1 0537 Lower left of keypad
Rev. Extended Terminal Interface Page 37
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
KEY_C3 0540 Lower right of keypad
KEY_BTAB 0541 Back tab key
KEY_BEG 0542 beg(inning) key
KEY_CANCEL 0543 cancel key
KEY_CLOSE 0544 close key
KEY_COMMAND 0545 cmd (command) key
KEY_COPY 0546 copy key
KEY_CREATE 0547 create key
KEY_END 0550 end key
KEY_EXIT 0551 exit key
KEY_FIND 0552 find key
KEY_HELP 0553 help key
KEY_MARK 0554 mark key
KEY_MESSAGE 0555 message key
KEY_MOVE 0556 move key
KEY_NEXT 0557 next object key
KEY_OPEN 0560 open key
KEY_OPTIONS 0561 options key
KEY_PREVIOUS 0562 previous object key
KEY_REDO 0563 redo key
KEY_REFERENCE 0564 ref(erence) key
KEY_REFRESH 0565 refresh key
KEY_REPLACE 0566 replace key
KEY_RESTART 0567 restart key
KEY_RESUME 0570 resume key
KEY_SAVE 0571 save key
KEY_SBEG 0572 shifted beginning key
KEY_SCANCEL 0573 shifted cancel key
KEY_SCOMMAND 0574 shifted command key
KEY_SCOPY 0575 shifted copy key
KEY_SCREATE 0576 shifted create key
KEY_SDC 0577 shifted delete char key
KEY_SDL 0600 shifted delete line key
KEY_SELECT 0601 select key
KEY_SEND 0602 shifted end key
KEY_SEOL 0603 shifted clear line key
KEY_SEXIT 0604 shifted exit key
KEY_SFIND 0605 shifted find key
KEY_SHELP 0606 shifted help key
KEY_SHOME 0607 shifted home key
KEY_SIC 0610 shifted input key
KEY_SLEFT 0611 shifted left arrow key
KEY_SMESSAGE 0612 shifted message key
KEY_SMOVE 0613 shifted move key
KEY_SNEXT 0614 shifted next key
KEY_SOPTIONS 0615 shifted options key
KEY_SPREVIOUS 0616 shifted prev key
KEY_SPRINT 0617 shifted print key
KEY_SREDO 0620 shifted redo key
KEY_SREPLACE 0621 shifted replace key
KEY_SRIGHT 0622 shifted right arrow
Rev. Extended Terminal Interface Page 38
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
KEY_SRSUME 0623 shifted resume key
KEY_SSAVE 0624 shifted save key
KEY_SSUSPEND 0625 shifted suspend key
KEY_SUNDO 0626 shifted undo key
KEY_SUSPEND 0627 suspend key
KEY_UNDO 0630 undo key
LINE GRAPHICS
The following variables may be used to add line-drawing
characters to the screen with waddch(). When defined for
the terminal, the variable will have the A_ALTCHARSET bit
turned on. Otherwise, the default character listed below
will be stored in the variable. The names were chosen to be
consistent with the DEC VT100 nomenclature.
Name Default Glyph Description
ACS_ULCORNER + upper left corner
ACS_LLCORNER + lower left corner
ACS_URCORNER + upper right corner
ACS_LRCORNER + lower right corner
ACS_RTEE + right tee (-|)
ACS_LTEE + left tee (†)
ACS_BTEE + bottom tee (|)
|) ACS_TTEE + top tee (
ACS_HLINE - horizontal line
ACS_VLINE | vertical line
ACS_PLUS + plus
ACS_S1 - scan line 1
ACS_S9 _ scan line 9
ACS_DIAMOND + diamond
ACS_CKBOARD : checker board (stipple)
ACS_DEGREE ' degree symbol
ACS_PLMINUS # plus/minus
ACS_BULLET o bullet
ACS_LARROW < arrow pointing left
ACS_RARROW > arrow pointing right
ACS_DARROW v arrow pointing down
ACS_UARROW ^ arrow pointing up
ACS_BOARD # board of squares
ACS_LANTERN # lantern symbol
ACS_BLOCK # solid square block
SEE ALSO
cc(1), ld(1), ioctl(2), plot(3X), putc(3S), scanf(3S),
stdio(3S), system(3S), vprintf(3S), profile(4), term(4),
terminfo(4), varargs(5).
termio(7), tty(7) in the INTERACTIVE UNIX System
User's/System Administrator's Reference Manual.
Chapter 10 of the Programmer's Guide.
DIAGNOSTICS
All routines return the integer OK upon successful
Rev. Extended Terminal Interface Page 39
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
completion and the integer ERR upon failure, unless other-
wise noted in the preceding routine descriptions.
All macros return the value of their w version, except get-
syx(), getyx(), getbegyx(), getmaxyx(). For these macros,
no useful value is returned.
Routines that return pointers always return (type *) NULL on
error.
WARNINGS
To use the new curses features, use the Release 3.1 version
of curses on UNIX System V Release 3.1. All programs that
ran with Release 2 or Release 3.0 curses will also run on
UNIX System V Release 3.1. You can link applications with
object files based on Release 2 or Release 3.0
curses/terminfo with the Release 3.1 libcurses.a library;
however, you cannot link applications with object files
based on Release 3.1 curses/terminfo with the Release 2 or
Release 3.0 libcurses.a library.
The plotting library plot(3X) and the curses library
curses(3X) both use the names erase() and move(). The
curses versions are macros. If you need both libraries, put
the plot(3X) code in a different source file from the
curses(3X) code, and/or #undef move() and erase() in the
plot(3X) code.
Between the time a call to initscr() and endwin() has been
issued, use only the routines in the curses library to gen-
erate output. Using system calls or the "standard I/O pack-
age" [see stdio(3S)] for output during that time can cause
unpredictable results.
If a pointer passed to a routine as a window argument is
null or out of range, the results are undefined (core may be
dumped).
BUGS
Currently typeahead checking is done using a nodelay read
followed by an ungetch() of any character that may have been
read. Typeahead checking is done only if wgetch() has been
called at least once. This may change when proper kernel
support is available. Programs which use a mixture of their
own input routines with curses input routines may wish to
call typeahead(-1) to turn off typeahead checking.
The argument to napms() is currently rounded up to the
nearest second.
draino (ms) only works for ms equal to 0.
Rev. Extended Terminal Interface Page 40
CURSES(3X) INTERACTIVE UNIX System CURSES(3X)
Rev. Extended Terminal Interface Page 41