CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
NAME
curses - terminal screen handling and optimization package
NOTE:
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, descriptions of each curses routines, are grouped under the
appropriate topics:
- 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
Followed by sections on:
- ATTRIBUTES
- COLORS
- FUNCTION KEYS
- LINE GRAPHICS
SYNOPSIS
cc [flag ...] file ... -lcurses [library ...]
#include <curses.h> (automatically includes <stdio.h>,
<termio.h>, and <unctrl.h>).
The parameters in the following summary are the arguments
used by the curses library routines: they are not global
variables. All routines return the int values ERR or OK
unless it is stated otherwise in the ROUTINES section. Rou-
tines that return pointers always return NULL on error.
(ERR, OK, and NULL are all defined in <curses.h>.)
bool bf
Printed 1/15/91 Page 1
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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
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()
Page 2 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
erasechar()
filter()
flash()
flushinp()
garbagedlines(win, begline, numlines)
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)
Printed 1/15/91 Page 3
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
newpad(nlines, ncols)
newterm(type, outfd, infd)
newwin(nlines, ncols, begin_y, begin_x)
nl()
nocbreak()
nodelay(win, bf)
noecho()
nonl()
noraw()
notimeout(win, bf)
overlay(srcwin, dstwin)
pair_content(pair, &f, &b)
overwrite(srcwin, dstwin)
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_attroff(attrs)
slk_attron(attrs)
slk_attrset(attrs)
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)
Page 4 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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)
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.
Printed 1/15/91 Page 5
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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 excep-
tions 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); 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 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 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 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
show up in modes such as underlined or in reverse video on
terminals that support such display enhancements. Line
drawing characters may be specified to be output. On input,
curses is also able to translate arrow and function keys
that transmit escape sequences into single values. The
video attributes, line drawing characters, and input values
use names, defined in <curses.h>, such as A_REVERSE,
ACS_HLINE, and KEY_LEFT.
Page 6 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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 foreground color
(for characters) and a background pair (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
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
in 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.
Printed 1/15/91 Page 7
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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 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 successfully completed. These constants are also
defined in <curses.h>.
The integer values LINES and COLS are defined in <curses.h>
and will be initialized 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 sucess-
fully 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 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
Page 8 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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 ripoffline().) This will determine
the terminal type and initialize all curses data
structures. 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; other-
wise, 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 applica-
tion.
endwin() A program should always call endwin() before exit-
ing or escaping from curses 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 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 routine. newterm() should be called once for
each terminal. It returns a variable of type
SCREEN* that should be saved as a reference 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 terminal, the
first terminal referred to must be the last one
for which endwin() is called.
Printed 1/15/91 Page 9
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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 which manipulates SCREEN
pointers; all other routines affect only the
current terminal.
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 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 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 window's cur-
sor. The number of characters output to the terminal
is returned.
Note that refresh() is a macro.
wnoutrefresh(win)
doupdate()
These two routines allow multiple updates to the physi-
cal 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 ter-
minal screen: a physical 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 transmit-
ted and certainly less processor time used.
WINDOW *newwin(nlines, ncols, begin_y, begin_x)
Page 10 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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 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), 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 both windows. When using this rou-
tine, 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 associ-
ated with it. In the case of overlapping windows,
subwindows should be deleted before the main window.
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 res-
tricted by the screen size and is not necessarily asso-
ciated 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 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
Printed 1/15/91 Page 11
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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 touch-
line() on orig before calling prefresh().
col)
prefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smax-
smaxcol)
pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow,
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 rec-
tangles must be entirely contained within their respec-
tive 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.
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 clrtoeol() before moving. Tabs are con-
sidered to be at every eighth column. If ch is another
control character, it will be drawn in the ^X notation.
(Calling winch() after adding a control character will
not return the control character, but instead will
return the representation of the control character.)
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 stan-
dout(), below.
Page 12 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
Note that ch is actually of type chtype, not a charac-
ter.
Note that addch(), mvaddch(), and mvwaddch() are mac-
ros.
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) followed by a call to
prefresh(pad). The knowledge that only a single char-
acter is being output is taken into consideration and,
for non-control characters, 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 charac-
ter.
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.
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. These attributes are defined in
<curses.h> and can be combined with the C logical OR (
| ) operator.
Printed 1/15/91 Page 13
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
The current attributes of a window are applied to all
characters that are written into the window with
waddch(). Attributes are a property of the character,
and move with the character through any scrolling and
insert/delete line/character operations. To the extent
possible on the particular terminal, 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 wat-
trset (win, 0), that is, it turns off all attributes.
Note that wattroff(), wattron(), wattrset(), wstan-
dend(), and wstandout() return 1 at all times.
Note that attrs is actually of type chtype, not a char-
acter.
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
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 neither signal is possible, nothing
will happen. Nearly all terminals have an audible sig-
nal (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 appropri-
ate 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)
Page 14 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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 window 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 pro-
cessor 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 the left one position and the last charac-
ter 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 mac-
ros.
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 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. This is implemented as a
Printed 1/15/91 Page 15
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
macro, so no ``&'' is necessary before the variables.
getbegyx(win, y, x)
getmaxyx(win, y, x)
Like getyx(), these routines store the current begin-
ning coordinates and size of the specified window.
Note that getbegyx() and getmaxyx() are macros.
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 char-
acter 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 charac-
ter.
Note that insch(), mvinsch(), and mvwinsch() are mac-
ros.
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 refresh() 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 srcwin on top of dstwin; that
is, all text in srcwin is copied into dstwin. srcwin
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.
row,
copywin(srcwin, dstwin, sminrow, smincol, dminrow, dmincol, dmax-
dmaxcol, overlay)
This routine provides a finer grain of control over the
Page 16 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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 coordinates of the
source window, (sminrow, 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(3S). The string
which would be output by printf(3S) 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 argu-
ments, 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.
scroll(win)
The window is scrolled up one line. This involves mov-
ing 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 overlapping windows,
since a change to one window will affect the other win-
dow, 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 (NOCBREAK mode). In HALF-DELAY
mode, the program will hang until a character is typed
Printed 1/15/91 Page 17
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
or the specified timeout has been reached. Unless noe-
cho() 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 produce undesirable results.
If wgetch() encounters a ^D, it is 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,
otherwise 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 that getch(), mvgetch(), and mvwgetch() are mac-
ros.
getstr(str)
wgetstr(win, str)
mvgetstr(y, x, str)
mvwgetstr(win, y, x, str)
A series of calls to getch() is made, until a newline,
carriage return, or enter key is received. The result-
ing value is placed in the area pointed at by the char-
acter pointer str. The user's erase and kill charac-
ters are interpreted. As in mvgetch(), no refresh() is
done between the move() and getstr() within the rou-
tines mvgetstr() and mvwgetstr().
Note that getstr(), mvgetstr(), and mvwgetstr() are
macros.
flushinp()
Throws away any typeahead that has been typed by the
Page 18 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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().
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 throw away any characters supplied
by ungetch()
inch()
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 than the stdio
routines (especially ^D).
vwscanw(win, fmt, ap)
This routine is similar to vwprintw() above in that
performs a wscanw() 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
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().
Printed 1/15/91 Page 19
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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.
idlok(win, bf)
If enabled (bf is TRUE), curses will consider using the
hardware ``insert/delete-line'' feature of terminals so
equipped. If disabled (bf is FALSE), curses will very
seldom use this feature. (The ``insert/delete-
character'' feature is always considered.) This option
should be enabled only if your application needs
``insert/delete-line'', for example, for a screen edi-
tor. 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'' cannot be used, curses will
redraw the changed portions of all lines. Not calling
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 cursor 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
cursor 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 scrol-
ling 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 scrol-
ling region or ``insert/delete-line'' capability, they
will probably be used by the output routines.)
Note that setscrreg() and wsetscrreg() are macros.
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 bottom line, or
Page 20 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
typing the last character of the last line. If dis-
abled (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 win-
dow 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 on
curses in the Programmer's Guide.
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 pro-
gram and erase/kill character processing is not per-
formed. When in NOCBREAK mode, the tty driver will
buffer characters typed until a newline or carriage
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
nocbreak() explicitly. Most interactive programs using
curses will set CBREAK mode.
Note that cbreak() performs a subset of the functional-
ity of raw(). See wgetch() under "Input" for a discus-
sion of how these routines interact with echo() and
noecho().
echo()
noecho()
These routines control whether characters typed by the
user are echoed by wgetch() as they are typed. Echoing
by the tty driver is always disabled, but 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 noecho(). See wgetch() under "Input" for a
discussion of how these routines interact with cbreak()
and nocbreak().
nl()
nonl()
Printed 1/15/91 Page 21
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
These routines control whether carriage return is
translated into newline on input by wgetch(). Ini-
tially, 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 char-
acters 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
settings. 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 specially 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.
meta(win, bf)
Initially, whether the terminal returns 7 or 8 signifi-
cant 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 argu-
ment, win, is always ignored. if the terminfo(4) capa-
bilities smm (meta_on) and rmm (meta_off) are defined
for the terminal, 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 dis-
abled, wgetch() will hang until a key is pressed.
Page 22 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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 dif-
ferentiate between sequences received from a function
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 pro-
gram. The differences are that in RAW mode, the inter-
rupt, quit, suspend, and flow control 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 tty(7) driver that are not set by curses.
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() routine 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 that fildes is a file descriptor, not a <stdio.h>
FILE pointer.
Environment Queries
baudrate()
Returns the output speed of the terminal. 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
Printed 1/15/91 Page 23
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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() or idlok().
char killchar()
The user's current line-kill character is returned.
char *longname()
This routine returns a pointer to a static area con-
taining a verbose description of the current terminal.
The maximum length of a verbose description 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.
start_color()
This routine requires no arguments. It must be called
if the user wants to use colors, and before any other
color manipulation routine is called. It is good prac-
tice to call this routine right after initscr().
start_color() initializes 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 turned on.
init_pair(pair, f, b)
This routine changes the definition of a color-pair.
It takes three arguments: the number of the color-pair
to be changed, the foreground color number, and the
background color number. The value of the first argu-
ment 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.
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 followed by three RGB values (for the amounts
of red, green, and blue components). The value of the
Page 24 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
first argument must be between 0 and COLORS-1. (See the
section COLOR for the default color index.) The last
three arguments must each be a value between 0 and
1000. When init_color() is used, all occurences of
that color on the screen immediately change to the new
definition.
has_colors()
This routine requires no arguments. It returns TRUE if
the terminal can manipulate colors, FALSE otherwise.
This routine facilitates writing terminal-independent
programs. For example, a programmer can use it to
decide whether to use color or some other video attri-
bute.
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 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 components 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).
pair_content(pair, &f, &b)
This routine allows users to find out what colors a
given color-pair consists of. It requires three argu-
ments: 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.
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,
reducing the size of stdscr and the variable LINES. curses
standardizes on 8 labels of 8 characters each.
slk_init(labfmt)
Printed 1/15/91 Page 25
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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 emulate
the soft labels, then labfmt determines how the labels
are arranged on the screen. Setting labfmt to 0 indi-
cates 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 routines 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 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.
slk_attron(attrs)
slk_attrset(attrs)
slk_attroff(attrs)
These routines correspond to attron(), attrset(), and
attroff(). They will have effect only if soft labels
are simulated on the bottom line of the screen.
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
Page 26 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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 termi-
nal 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 rou-
tines getsyx() and setsyx() are designed to be used by
a library routine which manipulates curses windows but
does not want to mess up the current position of the
program's cursor. The library routine would call get-
syx() at the beginning, do its manipulation of its own
windows, do a wnoutrefresh() on its windows, call set-
syx(), 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. rip-
offline() must be called before initscr() or newterm()
is called. If line is positive, 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 argu-
ments: 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 rou-
tine, 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
Printed 1/15/91 Page 27
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
allowable to call wnoutrefresh() during the initializa-
tion routine.
ripoffline() can be called up to five times before cal-
ling 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 filename,
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 ini-
tialize the curses data structures about what the ter-
minal 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 pro-
cess which has done a scr_dump() after its endwin()
call. The data will be declared invalid if the ter-
minfo(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
affect the contents of the screen, but will make the
tty's time-stamp old.
curs_set(visibility)
The cursor 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; otherwise, ERR is returned.
draino(ms)
Wait until the output has drained enough that it will
only take ms more milliseconds 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 any-
thing written 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 communications 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
Page 28 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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 run-
ning in a layer, 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, initializing the
terminfo(4) 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 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
Printed 1/15/91 Page 29
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
status of 1 in errret is normal, 0 means that the ter-
minal 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 structure of type TERMINAL. After
setupterm() returns successfully, the variable 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.
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 output 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(3S) is a putchar()-like routine to
which the characters are passed, one at a time.
Page 30 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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()-like routine putc(3S).
vidattr(attrs)
Like vidputs(), except that it outputs through putchar
(see putc(3S)).
The following routines return the value of the capability
corresponding to the terminfo(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
terminfo(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.
Printed 1/15/91 Page 31
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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 out-
put the returned string.
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 Manipula-
tions".
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 customers 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
Page 32 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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
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
A_NORMAL Bit mask to reset all attributes off
(for example: wattrset (A_NORMAL)
COLOR_PAIR(n) Color-pair defined in n (note that this is a macro)
The following bit-masks may be AND'ed with characters
returned by winch().
Printed 1/15/91 Page 33
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
A_CHARTEXT Extract character
A_ATTRIBUTES Extract character
A_COLOR Extract color-pair field information
The following macro is the reverse of COLOR_PAIR(n).
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
COLOR_MAGENTA 5
COLOR_YELLOW 6
COLOR_WHITE 7
FUNCTION-KEYS
The following function keys, defined in <curses.h>, might be
returned by getch() if keypad() has been enabled. Note that
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(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 f .
KEY_DL 0510 Delete line n
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
Page 34 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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
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
Printed 1/15/91 Page 35
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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
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 charcter 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
Page 36 Printed 1/15/91
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
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
RETURN VALUES
All routines return the integer OK upon successful comple-
tion and the integer ERR upon failure, unless otherwise
noted in the preceding routine descriptions.
All macros return the value of their w version, except
setscrreg(), wsetscrreg(), getsyx(), getyx(), getbegy(),
getmaxyx(). For these macros, no useful value is returned.
Routines that return pointers always return (type *) NULL on
error.
ERRORS
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 will be changed when proper ker-
nel 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.
WARNINGS
To use the new curses features, use the Release 3.2 version
of curses on UNIX System V Release 3.2. All programs that
ran with System V Release 2, Release 3.0, or Release 3.1
curses will run with System V Release 3.2. You can link
applications with object files based on the Release 2 or
Release 3 Bcurses/terminfo with both the Release 3.0 and the
Release 3.1 libcurses.a library; however, you cannot link
applications with object files based on the Release 3.1 or
Release 3.2 curses/terminfo with the Release 2 or Release
3.0 libcurses.a library.
Printed 1/15/91 Page 37
CURSES(3X-SysV) RISC/os Reference Manual CURSES(3X-SysV)
The plotting library plot(3X) and the curses library 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 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).
SEE ALSO
ioctl(2), plot(3X), printf(3S), putc(3S), scanf(3S),
stdio(3S), system(3S), vprintf(3S), profile(4), term(4),
terminfo(4), varargs(5).
cc(1), ld(1), tput(1) in the User's Reference Manual.
termio(7), tty(7) in the System Administrator's Reference
Manual.
Chapter 12, "curses/terminfo", in the Programmer's Guide.
Page 38 Printed 1/15/91