CURSES(3V) CURSES(3V)
NAME
curses - System V terminal screen handling and optimization package
SYNOPSIS
The curses manual page is organized as follows:
In SYNOPSIS
o compiling information
o summary of parameters used by curses routines
In SYSTEM V SYNOPSIS:
o compiling information
In DESCRIPTION and SYSTEM V DESCRIPTION:
o An overview of how curses routines should be used
In ROUTINES, descriptions of curses routines are grouped under the
appropriate topics:
o Overall Screen Manipulation
o Window and Pad Manipulation
o Output
o Input
o Output Options Setting
o Input Options Setting
o Environment Queries
o Low-level Curses Access
o Miscellaneous
o Use of curscr
In SYSTEM V ROUTINES, descriptions of curses routines are grouped under
the appropriate topics:
o Overall Screen Manipulation
o Window and Pad Manipulation
o Output
o Input
o Output Options Setting
o Input Options Setting
o Environment Queries
o Soft Labels
o Low-level Curses Access
o Terminfo-Level Manipulations
o Termcap Emulation
o Miscellaneous
o Use of curscr
Then come sections on:
o SYSTEM V ATTRIBUTES
o SYSTEM V FUNCTION KEYS
o LINE GRAPHICS
cc [ flags ] files -lcurses -ltermcap [ libraries ]
#include <<curses.h>> (automatically includes <<stdio.h>> and
<<unctl.h>>.)
The parameters in the following list are not global variables. 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. Rou-
tines that return pointers always return NULL on error. ERR, OK , and
NULL are all defined in <<curses.h>>.) Routines that return integers are
not listed in the parameter list below.
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
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
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
SYSTEM V SYNOPSIS
/usr/5bin/cc [ flag ...] file ... -lcurses [ library ...]
#include <<curses.h>> (automatically includes <<stdio.h>>, <<termio.h>>,
and <<unctrl.h>>).
DESCRIPTION
These routines give the user a method of updating screens with reason-
able optimization. They keep an image of the current screen, and the
user sets up an image of a new one. Then the refresh() tells the rou-
tines to make the current screen look like the new one. In order to
initialize the routines, the routine initscr() must be called before
any of the other routines that deal with windows and screens are used.
The routine endwin() should be called before exiting.
SYSTEM V DESCRIPTION
The curses routines give the user a terminal-independent method of
updating screens with reasonable optimization.
In order 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. 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 (); intr-
flush(stdscr, FALSE); 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. This can
be done by executing the tset command in your .profile or .login file.
For further details, see tset(1) and the Tabs and Initialization sub-
section of terminfo(5V).
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 supplied, which is the size of the terminal
screen. Others may be created with newwin(). Windows are referred to
by variables declared as WINDOW *; the type WINDOW is defined in
<curses.h> to be a C 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 beginning with w usually affect stdscr. Then refresh() is called,
telling the routines to make the user's terminal screen look like std-
scr. 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
that 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 Manipulation for more information.
In addition to drawing characters on the screen, video attributes may
be included that cause the characters to show up in modes such as
underlined or in reverse video.
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 clear and repaint the screen from scratch. If the window
argument to wrefresh() is curscr, the screen in immediately cleared and
repainted from scratch. This is how most programs would implement a
"repaint-screen" function. More information on using curscr is pro-
vided where its use is appropriate.
The environment variables LINES and COLUMNS may be set to override
curses's idea of how large a screen is.
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 sun, then the compiled terminal definition is found in
/usr/share/lib/terminfo/s/sun. The s is copied from the first letter
of sun to avoid creation of huge directories.) However, if TERMINFO is
set to $HOME/myterms, curses will first check $HOME/myterms/s/sun, and,
if that fails, will then check /usr/share/lib/terminfo/s/sun. This is
useful for developing experimental definitions or when write permission
on /usr/share/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 con-
stants TRUE and FALSE have the values 1 and 0, respectively. The con-
stants ERR and OK are returned by routines to indicate whether the rou-
tine successfully completed. These constants are also defined in
<<curses.h>>.
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 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.
Overall Screen Manipulation
WINDOW *initscr() The first routine called should almost always be
initscr(). The exceptions are slk_init(), fil-
ter(), and ripoffline(). This will determine the
terminal type and initialize all curses data struc-
tures. initscr() also arranges that the first call
to refresh() 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 indication 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 exit-
ing or escaping from curses mode temporarily, to do
a shell escape or system(3) call, for example.
This routine will restore termio(4) 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().
Window and Pad Manipulation
refresh()
wrefresh (win) These routines (or prefresh(), pnoutrefresh(),
wnoutrefresh(), or doupdate()) must be called to
write output to the terminal, as most other rou-
tines merely manipulate data structures. wre-
fresh() copies the named window to the physical
terminal screen, taking into account what is
already there in order to minimize the amount of
information 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 win-
dow's cursor. The number of characters output to
the terminal is returned.
Note: refresh() is a macro.
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 win-
dow is at line begin_y, column begin_x. If 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 the
window to be 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),. When using this routine,
often it will be necessary to call touchwin() or
touchline() on orig before calling wrefresh.
delwin (win) Delete the named window, freeing up all memory
associated with it. In the case of overlapping
windows, subwindows should be deleted before the
main window.
Output
These routines are used to "draw" text on 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 cur-
rent 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 per-
formed. 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 clrtoeol() before moving. TAB
characters are considered to be at every eighth
column. If ch is another control character, it
will be drawn in the CTRL-X notation. (Calling
winch() after adding a control character will not
return the control character, but instead will
return the representation of the control charac-
ter.)
Video attributes can be combined with a character
by or-ing them into the parameter. This will
result in these attributes also being set. The
intent here is that text, including attributes, can
be copied from one place to another using inch()
and addch(). See standout(), below.
Note: ch is actually of type chtype, not a charac-
ter.
Note: addch(), mvaddch(), and mvwaddch() are
macros.
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: addstr(), mvaddstr(), and mvwaddstr() are
macros.
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: vertch and horch are actually of type chtype,
not characters.
erase()
werase (win) These routines copy blanks to every position in the
window.
Note: 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 wre-
fresh() for that window, and repainted from
scratch.
Note: clear() is a macro.
clrtobot()
wclrtobot (win) All lines below the cursor in this window are
erased. Also, the current line to the right of the
cursor, inclusive, is erased.
Note: clrtobot() is a macro.
clrtoeol()
wclrtoeol (win) The current line to the right of the cursor, inclu-
sive, is erased.
Note: clrtoeol() is a macro.
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 the left one position and the
last character 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: 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 cursor position does not change. This does not
imply use of the hardware "delete-line" feature.
Note: deleteln() is a macro.
getyx (win, y, x) The cursor position of the window is placed in the
two integer variables y and x. This is implemented
as a macro, so no `&&' is necessary before the vari-
ables.
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 characters to the right are
moved one SPACE to the right, possibly losing the
rightmost character of the line. The cursor posi-
tion does not change (after moving to (y, x), if
specified). This does not imply use of the hard-
ware "insert-character" feature.
Note: ch is actually of type chtype, not a charac-
ter.
Note: insch(), mvinsch(), and mvwinsch() are
macros.
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: 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 refresh() is
called. The position specified is relative to the
upper left corner of the window, which is (0, 0).
Note: move() is a macro.
overlay (srcwin, dstwin)
overwrite (srcwin, dstwin)
These routines overlay srcwin on top of dstwin;
that is, all text in srcwin is copied into dstwin.
scrwin and dstwin need not be the same size; only
text where the two windows overlap is copied. The
difference is that overlay() is non-destructive
(blanks are not copied), while overwrite() is
destructive.
printw (fmt [, arg...])
wprintw (win, fmt [, arg...])
mvprintw (y, x, fmt [, arg...])
mvwprintw (win, y, x, fmt [, arg...])
These routines are analogous to printf(3V). The
string that would be output by printf(3V) is
instead output using waddstr() on the given window.
scroll (win) The window is scrolled up one line. This involves
moving the lines in the window data structure. As
an optimization, if the window is stdscr and the
scrolling region is the entire window, the physical
screen will be scrolled at the same time.
touchwin (win)
touchline (win, start, count)
Throw away all optimization information about which
parts of the window have been touched, by pretend-
ing that the entire window has been drawn on. This
is sometimes necessary when using overlapping win-
dows, 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 set-
ting of cbreak(), this will be after one character
(CBREAK mode), or after the first newline (NOCBREAK
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 desig-
nated window. No refresh() will occur between the
move() and the getch() done within the routines
mvgetch() and mvwgetch().
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 terminal
driver when each character is typed, the program
may produce undesirable results.
If keypad (win, TRUE) has been called, and a func-
tion 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 inte-
gers 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 terminals, 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: 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 getch() is made, until a new-
line, carriage return, or enter key is received.
The resulting value is placed in the area pointed
at by the character pointer str. The user's erase
and kill characters are interpreted. As in
mvgetch(), no refresh() is done between the move()
and getstr() within the routines mvgetstr() and
mvwgetstr().
Note: getstr(), mvgetstr(), and mvwgetstr() are
macros.
inch()
winch (win)
mvinch (y, x)
mvwinch (win, y, x) The character, of type chtype, at the current posi-
tion 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 prede-
fined constants A_CHARTEXT and A_ATTRIBUTES,
defined in <curses.h>, can be used with the C logi-
cal AND (&) operator to extract the character or
attributes alone.
Note: 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(3V), as do their
arguments and return values. wgetstr() is called
on the window, and the resulting line is used as
input for the scan.
Output Options Setting
These routines set options within curses that deal with output. All
options are initially FALSE, unless otherwise stated. It is not neces-
sary to turn these options off before calling endwin().
clearok (win, bf) If enabled (bf is TRUE), the next call to wre-
fresh() with this window will clear the screen com-
pletely 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.
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 consid-
ered. This option should be enabled only if your
application needs "insert/delete-line", for exam-
ple, for a screen editor. It is disabled by
default because "insert/delete-line" tends to be
visually annoying when used in applications where
it is not really needed. If "insert/delete-line"
cannot be used, curses will redraw the changed por-
tions of all lines.
leaveok (win, bf) Normally, the hardware cursor is left at the loca-
tion of the window cursor being refreshed. This
option allows the cursor to be left wherever the
update happens to leave it. It is useful for
applications where the cursor is not used, since it
reduces the need for cursor motions. If possible,
the cursor is made invisible when this option is
enabled.
scrollok (win, bf) This option controls what happens when the cursor
of a window is moved off the edge of the window or
scrolling region, either from a newline on the bot-
tom 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: in order to get the physical
scrolling effect on the terminal, it is also neces-
sary to call idlok().
nl()
nonl() These routines control whether NEWLINE is trans-
lated into RETURN and LINEFEED on output, and
whether RETURN is translated into NEWLINE on input.
Initially, the translations do occur. By disabling
these translations using nonl(), curses is able to
make better use of the linefeed capability, result-
ing in faster cursor motion.
Input Options Setting
These routines set options within curses that deal with input. The
options involve using ioctl(2) and therefore interact with curses rou-
tines. It is not necessary to turn these options off before calling
endwin().
For more information on these options, refer to
cbreak()
nocbreak() These two routines put the terminal into and out of
CBREAK mode, respectively. In CBREAK mode, charac-
ters typed by the user are immediately available to
the program and erase/kill character processing is
not performed. When in NOCBREAK mode, the tty
driver will buffer characters typed until a NEWLINE
or RETURN is typed. Interrupt and flow-control
characters are unaffected by this mode (see
termio(4)). Initially the terminal may or may not
be in CBREAK mode, as it is inherited, therefore, a
program should call cbreak() or nocbreak() explic-
itly. Most interactive programs using curses will
set CBREAK mode.
Note: cbreak() overrides raw(). See getch() under
Input for a discussion of how these routines inter-
act with echo() and noecho().
echo()
noecho() These routines control whether characters typed by
the user are echoed by getch() as they are typed.
Echoing by the tty driver is always disabled, but
initially getch() is in ECHO mode, so characters
typed are echoed. Authors of most interactive pro-
grams prefer to do their own echoing in a con-
trolled area of the screen, or not to echo at all,
so they disable echoing by calling noecho(). See
getch() under Input for a discussion of how these
routines interact with cbreak() and nocbreak().
raw()
noraw() The terminal is placed into or out of RAW mode.
RAW mode is similar to CBREAK mode, in that charac-
ters typed are immediately passed through to the
user program. The differences are that in RAW
mode, the interrupt, quit, suspend, and flow con-
trol characters are passed through uninterpreted,
instead of generating a signal. RAW mode also
causes 8-bit input and output. The behavior of the
BREAK key depends on other bits in the terminal
driver that are not set by curses.
Environment Queries
baudrate() Returns the output speed of the terminal. The num-
ber returned is in bits per second, for example,
9600, and is an integer.
char erasechar() The user's current erase character is returned.
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.
Low-Level curses Access
The following routines give low-level access to various curses func-
tionality. These routines typically would be used inside of library
routines.
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().
Miscellaneous
unctrl (c) This macro expands to a character string which is a
printable representation of the character c. Con-
trol 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>.
flusok(win,boolf) set flush-on-refresh flag for win
getcap(name) get terminal capability name
touchoverlap(win1,win2)
mark overlap of win1 on win2 as changed().
gettmode() A no-op.
nocrmode() Replaced by nocbreak().
SYSTEM V ROUTINES
The above routines are available as described except for flusok(), get-
cap() and touchoverlap() which are not available.
In addition, the following routines are available:
Overall Screen Manipulation
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 program that wants an indication of
error conditions, so that it may continue to run in
a line-oriented mode if the terminal cannot support
a screen-oriented program, must also use this rou-
tine. newterm() should be called once for each
terminal. It returns a variable of type SCREEN*
that should be saved as a reference to that termi-
nal. The arguments are the type of the terminal to
be used in place of the environment variable TERM;
outfd, a stdio(3V) 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 terminal, 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 reference new becomes the
new current terminal. A pointer to the screen of
the previous terminal is returned by the routine.
This is the only routine that manipulates SCREEN
pointers; all other routines affect only the cur-
rent terminal.
Window and Pad Manipulation
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 physical terminal screen,
describing what is actually on the screen, and a
virtual terminal screen, describing what the pro-
grammer wants to have on the screen. wrefresh()
works by first calling wnoutrefresh(), which copies
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
probably fewer total characters transmitted and
certainly less processor time used.
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 wre-
fresh() with a pad as an argument; the routines
prefresh() or pnoutrefresh() should be called
instead. Note: these routines require additional
parameters to specify the part of the pad to be
displayed and the location on the screen to be used
for display.
WINDOW *subpad (orig, nlines, ncols, begin_y, begin_x)
Create and return a pointer to a subwindow 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 both windows. When
using this routine, often it will be necessary to
call touchwin() or touchline() on orig before call-
ing prefresh().
prefresh (pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol)
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 coordi-
nates, 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 "draw" text on windows.
echochar (ch)
wechochar (win, ch)
pechochar (pad, ch) These routines are functionally equivalent to a
call to addch (ch) followed 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) fol-
lowed by a call to prefresh (pad). The knowledge
that only a single character is being output is
taken into consideration and, for non-control char-
acters, a considerable performance gain can be seen
by using these routines instead of their equiva-
lents. In the case of pechochar(), the last loca-
tion of the pad on the screen is reused for the
arguments to prefresh().
Note: ch is actually of type chtype, not a charac-
ter.
Note: echochar() is a macro.
attroff (attrs)
wattroff (win, attrs)
attron (attrs)
wattron (win, attrs)
attrset (attrs)
wattrset (win, attrs)
beep()
flash() These routines are used to signal the terminal
user. beep() will sound the audible alarm on the
terminal, if possible, and if not, will flash the
screen (visible bell), if that is possible.
flash() will flash the screen, and if that is not
possible, will sound the audible signal. If nei-
ther signal is possible, nothing will happen.
Nearly all terminals have an audible signal (bell
or beep) but only some can flash the screen.
delay_output (ms) Insert a ms millisecond pause in the output. It is
not recommended that this routine be used exten-
sively, because padding characters are used rather
than a processor pause.
getbegyx (win, y, x)
getmaxyx (win, y, x)
Like getyx(), these routines store the current
beginning coordinates and size of the specified
window.
Note: getbegyx() and getmaxyx() are macros.
copywin (srcwin, dstwin, sminrow, smincol, dminrow, dmincol, dmaxrow,
dmaxcol, overlay)
This routine provides a finer grain of control over
the overlay() and overwrite() routines. Like in
the prefresh() routine, a rectangle is specified in
the destination window, (dminrow, dmincol) and
(dmaxrow, dmaxcol), and the upper-left-corner coor-
dinates of the source window, (sminrow, smincol).
If the argument overlay is true, then copying is
non-destructive, as in overlay().
vwprintw (win, fmt, varglist)
This routine corresponds to vprintf(3V). It per-
forms a wprint.
Input
flushinp() Throws away any typeahead that has been typed by
the user and has not yet been read by the program.
ungetch (c) Place c back onto the input queue to be returned by
the next call to wgetch().
vwscanw (win, fmt, ap)
This routine is similar to vwprintw() above in that
performs a wscan.
Output Options Setting
These routines set options within curses that deal with output. All
options are initially FALSE, unless otherwise stated. It is not neces-
sary to turn these options off before calling endwin().
setscrreg (top, bot)
wsetscrreg (win, top, bot)
These routines allow the user will
cause all lines in the scrolling region to scroll
up one line. Note: 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: setscrreg() and wsetscrreg() are macros.
Input Options Setting
These routines set options within curses that deal with input. The
options involve using ioctl(2) and therefore interact with curses rou-
tines. It is not necessary to turn these options off before calling
endwin().
For more information on these options, refer to
halfdelay (tenths) Half-delay mode is similar to CBREAK mode in that
characters typed by the user are immediately avail-
able 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 inter-
rupt, but causing curses to have the wrong idea of
what is on the screen. Disabling the option pre-
vents the flush. The default for the option is
inherited from the tty driver settings. The window
argument is ignored.
keypad (win, bf) This option enables the keypad of the user's termi-
nal. 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 func-
tion keys specially and the program would have to
interpret the escape sequences itself. If the key-
pad in the terminal can be turned on (made to
transmit) and off (made to work locally), turning
on this option will cause the terminal keypad to be
turned on when wgetch() is called.
meta (win, bf) If enabled, characters returned by wgetch() are
transmitted with all 8 bits, instead of with the
highest bit stripped. In order for meta() to work
correctly, the km (has_meta_key) capability has to
be specified in the terminal's terminfo(5V) entry.
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
purpose of the timeout is to differentiate between
sequences received from a function key and those
typed by a user.
typeahead (fildes) curses does "line-breakout optimization" by looking
for typeahead periodically while updating the
screen. If input is found, and it is coming from a
tty, the current update will be postponed until
refresh() 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(), or stdin in
the case that initscr() was used, will be used to
do this typeahead checking. The typeahead() rou-
tine specifies that the file descriptor fildes is
to be used to check for typeahead instead. If
fildes is -1, then no typeahead checking will be
done.
Note: fildes is a file descriptor, not a <<stdio.h>>
FILE pointer.
Environment Queries
has_ic() True if the terminal has insert- and delete-charac-
ter capabilities.
has_il() True if the terminal has insert- and delete-line
capabilities, or can simulate them using scrolling
regions. This might be used to check to see if it
would be appropriate to turn on physical scrolling
using scrollok().
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 simulate them, curses will take over the
bottom line of stdscr, reducing the size of stdscr and the variable
LINES. curses standardizes on 8 labels of 8 characters each.
slk_init (labfmt) In order to use soft labels, this routine must be
called before initscr() or newterm() is called. If
initscr() winds up using a line from stdscr to emu-
late 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 charac-
ters 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 routines wre-
fresh() 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 labnum, with
leading and trailing blanks stripped, is returned.
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.
Low-Level curses Access
The following routines give low-level access to various curses func-
tionality. 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.
getsyx (y, x) The current coordinates of the virtual screen cur-
sor are returned in y and x. Like getyx(), the
variables y and x do not take an && before them. If
leaveok() is currently TRUE, then -1, -1 will be
returned. If lines may have been removed from the
top of the screen using ripoffline() and the values
are to be used beyond just passing them on to set-
syx(), the value y+stdscr->>_yoffset should be used
for those other uses.
Note: getsyx() is a macro.
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 that manipulates curses
windows but does not want to mess up the current
position of the program's cursor. The library rou-
tine would call getsyx() at the beginning, do its
manipulation of its own windows, do a wnoutre-
fresh() on its windows, call setsyx(), and then
call doupdate().
ripoffline (line, init)
This routine provides access to the same 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 std-
scr; 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 ini-
tialization 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 contents of file-
name, which must have been written using
scr_dump(). 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(3) call to share the screen with
another process that has done a scr_dump() after
its endwin() call. The data will be declared
invalid if the time-stamp of the tty is old or the
terminfo(5V) capability nrrmc is true.
curs_set (visibility)
The cursor is set to invisible, normal, or very
visible for visibility equal to 0, 1 or 2.
draino (ms) Wait until the output has drained enough that it
will only take ms more milliseconds to drain com-
pletely.
garbagedlines (win, begline, numlines)
This routine indicates to curses that a screen line
is garbaged and should be thrown away before having
anything written over the top of it. It could be
used for programs such as editors that want a com-
mand to redraw just a single line. Such a command
could be used in cases where there is a noisy com-
munications 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.
Terminfo-Level Manipulations
These low-level routines must be called by programs that need to deal
directly with the terminfo(5V) database to handle certain terminal
capabilities, such as programming function keys. For all other func-
tionality, curses routines are more suitable and their use is recom-
mended.
Initially, setupterm() should be called. Note: setupterm() is automat-
ically called by initscr() and newterm(). This will define the set of
terminal-dependent variables defined in the terminfo(5V) database. The
terminfo(5V) variables lines and columns (see terminfo(5V)) are ini-
tialized 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 window sizes in rows and columns as
returned by the TIOCGWINSZ ioctl are non-zero, those sizes are used.
Otherwise, the values for lines and columns specified in the ter-
minfo(5V) 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(5V) 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 that use cursor
addressing should output enter_ca_mode upon startup and should output
exit_ca_mode before exiting (see terminfo(5V)). 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: this is dif-
ferent from the curses routines (see endwin()).
setupterm (term, fildes, errret)
Reads in the terminfo(5V) database, initializing
the terminfo(5V) structures, but does not set up
the output virtualization structures used by
curses. The terminal type is in the character
string term; if term is NULL, the environment vari-
able 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 sta-
tus value in the integer pointed to by errret. A
status of 1 in errret is normal, 0 means that the
terminal could not be found, and -1 means that the
terminfo(5V) 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(5V) boolean, numeric and string vari-
ables are stored in a structure of type TERMINAL.
After setupterm() returns successfully, the vari-
able cur_term (of type TERMINAL *) is initialized
with all of the information that the terminfo(5V)
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.
set_curterm (nterm) nterm is of type TERMINAL * . set_curterm() sets
the variable cur_term to nterm, and makes all of
the terminfo(5V) boolean, numeric and string vari-
ables 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 avail-
able for further use. If oterm is the same as
cur_term, then references to any of the ter-
minfo(5V) boolean, numeric and string variables
thereafter may refer to invalid memory locations
until another setupterm() has been called.
restartterm (term, fildes, errret)
Like setupterm() after a memory restore.
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 output it. str
must be a terminfo(5V) string variable or the
return value from tparm(), tgetstr(), tigetstr() or
tgoto(). count is the number of lines affected, or
1 if not applicable. putchar() is a putc(3s)-like
routine to which the characters are passed, one at
a time.
putp (str) A routine that calls tputs() (str, 1, putc(3s).
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 putc(3s)-like routine putc(3s).
vidattr (attrs) Like vidputs(), except that it outputs through
putc(3s).
tigetflag (capname) The value -1 is returned if capname is not a bool-
ean capability.
tigetnum (capname) The value -2 is returned if capname is not a
numeric capability.
tigetstr (capname) The value (char *) -1 is returned if capname is not
a string capability.
Termcap Emulation
These routines are included as a conversion aid for programs that use
the termcap(3X) library. Their parameters are the same and the rou-
tines are emulated using the terminfo(5V) database.
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 (codes) 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.
char *tgoto (cap, col, row)
Instantiate the parameters into the given capabil-
ity. The output from this routine is to be passed
to tputs().
tputs (str, affcnt, putc)
See tputs() above, under Terminfo-Level Manipula-
tions.
Miscellaneous
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.().
fixterm() Replaced by reset_prog_mode().
nocrmode() Replaced by nocbreak().
resetterm() Replaced by reset_shell_mode().
saveterm() Replaced by def_prog_mode().
setterm() Replaced by setupterm().
SYSTEM V ATTRIBUTES
The following video attributes, defined in <curses.h>, can be passed to
the routines attron(), attroff(), and attrset(), or OR'ed with the
characters passed to addch().
; l l l . A_STANDOUT Terminal's best highlighting mode A_UNDER-
LINE Underlining A_REVERSE Reverse video A_BLINK Blinking
A_DIM Half bright A_BOLD Extra bright or bold
A_ALTCHARSET Alternate character set
A_CHARTEXT Bit-mask to extract character (described under winch)
A_ATTRIBUTES Bit-mask to extract attributes (described under winch)
A_NORMAL Bit mask to reset all attributes off (for example:
`attrset (A_NORMAL)'
SYSTEM V FUNCTION KEYS
The following function keys, defined in <curses.h>, might be returned
by getch() if keypad() has been enabled. Note: not all of these may be
supported on a particular terminal 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(5V) database.
center; l l l . 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 Pre-
vious page KEY_STAB 0524 Set TAB KEY_CTAB 0525 Clear TAB
KEY_CATAB 0526 Clear all TAB characters 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 key-
pad KEY_B2 0536 Center of keypad KEY_C1 0537 Lower left of keypad
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_MES-
SAGE 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 mes-
sage 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 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 waddce. When defined for the terminal, the variable
will have the A_ALTCHARSET bit turned on. Otherwise, the default char-
acter listed below will be stored in the variable. The names were cho-
sen to be consistent with the DEC VT100 nomenclature.
l c l . Name Default Glyph Description
ACS_ULCORNER + upper left corner ACS_LLCORNER + lower left
corner ACS_URCORNER + upper right corner ACS_LRCORNER + lower (stip-
ple)
RETURN VALUES
Unless otherwise noted in the preceding routine descriptions, all rou-
tines return:
OK on success.
ERR on failure.
SYSTEM V RETURN VALUES
All macros return the value of their w version, except setscrreg(),
wsetscrreg(), getsyx(), getyx(), getbegy(), getmaxyx(), which return no
useful value.
Routines that return pointers always return (type *) NULL on failure.
FILES
.profile
SYSTEM V FILES
/usr/share/lib/terminfo
SEE ALSO
cc(1V), ld(1), ioctl(2), getenv(3V), plot(3X), printf(3V), putc(3S),
scanf(3V), stdio(3V), system(3), varargs(3), vprintf(3V), termio(4),
tty(4), term(5V), termcap(5), terminfo(5V), tic(8V)
SYSTEM V WARNINGS
The plotting library plot(3X) and the curses library curses(3V) 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 than the curses(3V) code, and/or `#undef move' and `#undef 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 generate output. Using sys-
tem calls or the "standard I/O package" (see stdio(3V)) for output dur-
ing that time can cause unpredictable results.
4th Berkeley Distribution 21 January 1990 CURSES(3V)