CURSES(3X) (Terminal Information Utilities) CURSES(3X)
NAME
curses - terminal screen handling and optimization package
TABLE OF CONTENTS
Page
SYNOPSIS.................................... 1
- compiling information
- summary of parameters used by curses routines
- alphabetical list of curses routines showing their parameters,
with a key to the section of ROUTINES in which they are discussed.
DESCRIPTION................................. 6
- An overview of how curses routines should be used
ROUTINES.................................... 8
- Each curses routine is described in the appropriate section:
Page
Section 1: Overall Screen Manipulation 9
Section 2: Window and Pad Manipulation10
Section 3: Output..........12
Section 4: Input...........17
Section 5: Output Options Setting19
Section 6: Input Options Setting20
Section 7: Environment Queries22
Section 8: Color Manipulation22
Section 9: Soft Labels.....23
Section 10: Low-Level curses Access24
Section 11: Terminfo-Level Manipulations27
Section 12: Termcap Emulation29
Section 13: Miscellaneous...29
Section 14: Use of curscr...30
Section 15: Obsolete Calls..30
ATTRIBUTES..................................30
COLORS......................................31
FUNCTION KEYS...............................31
LINE GRAPHICS...............................33
SYNOPSIS
cc [flag ...] file ... -lcurses [library ...]
Page 1 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
#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.
Routines that return pointers always return NULL on error.
(ERR, OK, and NULL are all defined in <curses.h>.)
bool bf;
char **area,*boolnames[], *boolcodes[], *boolfnames[], *bp;
char *cap, *capname, codename[2], erasechar, *filename, *fmt;
char *keyname, killchar, *label, *longname;
char *name, *numnames[], *numcodes[], *numfnames[];
char *slk_label, *str, *strnames[], *strcodes[], *strfnames[];
char *term, *tgetstr, *tigetstr, *tgoto, *tparm, *type;
chtype attrs, ch, horch, vertch;
FILE *infd, *outfd;
int begin_x, begin_y, begline, bot, c, col, count;
int dmaxcol, dmaxrow, dmincol, dminrow, *errret, fildes;
int (*init( )), labfmt, labnum, line;
int ms, ncols, new, newcol, newrow, nlines, numlines;
int oldcol, oldrow, overlay;
int p1, p2, p9, pmincol, pminrow, (*putc( )), row;
int smaxcol, smaxrow, smincol, sminrow, start;
int tenths, top, visibility, x, y;
short pair, color, f, r, g, b;
SCREEN *new, *newterm, *set_term;
TERMINAL *cur_term, *nterm, *oterm;
valist varglist;
WINDOW *curscr, *dstwin, *initscr, *newpad, *newwin, *orig;
WINDOW *pad, *srcwin, *stdscr, *subpad, *subwin, *win;
NAME PAGE
addch(ch) %addch%
addstr(str) %addstr%
attroff(attrs) %attroff%
Page 2 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
attron(attrs) %attron%
attrset(attrs) %attrset%
baudrate() %baudrate%
beep() %beep%
box(win, vertch, horch) %box%
canchangecolor() %can_change_color%
cbreak() %cbreak%
clear() %clear%
clearok(win, bf) %clearok%
clrtobot() %clrtobot%
clrtoeol() %clrtoeol%
colorcontent(color, &r, &g, &b) %color_content%
copywin(srcwin, dstwin, sminrow, smincol,
dminrow, dmincol, dmaxrow, dmaxcol, overlay) %copywin%
cursset(visibility) %curs_set%
defprogmode() %def_prog_mode%
defshellmode() %def_shell_mode%
NAME PAGE
delcurterm(oterm) %del_curterm%
delayoutput(ms) %delay_output%
delch() %delch%
deleteln() %deleteln%
delwin(win) %delwin%
doupdate() %doupdate%
draino(ms) %draino%
echo() %echo%
echochar(ch) %echochar%
endwin() %endwin%
erase() %erase%
erasechar() %erasechar%
filter() %filter%
flash() %flash%
flushinp() %flushinp%
garbagedlines(win, begline, numlines) %garbagedlines%
getbegyx(win, y, x) %getbegyx%
getch() %getch%
getmaxyx(win, y, x) %getmaxyx%
getstr(str) %getstr%
Page 3 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
getsyx(y, x) %getsyx%
getyx(win, y, x) %getyx%
halfdelay(tenths) %halfdelay%
hascolors() %has_colors%
hasic() %has_ic%
hasil() %has_il%
idlok(win, bf) %idlok%
inch() %inch%
initcolor(color, r, g, b) %init_color%
initpair(pair, f, b) %init_pair%
initscr() %initscr%
insch(ch) %insch%
insertln() %insertln%
intrflush(win, bf) %intrflush%
isendwin() %isendwin%
keyname(c) %keyname%
keypad(win, bf) %keypad%
killchar() %killchar%
leaveok(win, bf) %leaveok%
longname() %longname%
meta(win, bf) %meta%
move(y, x) %move%
mvaddch(y, x, ch) %mvaddch%
mvaddstr(y, x, str) %mvaddstr%
mvcur(oldrow, oldcol, newrow, newcol) %mvcur%
mvdelch(y, x) %mvdelch%
NAME PAGE
mvgetch(y, x) %mvgetch%
mvgetstr(y, x, str) %mvgetstr%
mvinch(y, x) %mvinch%
mvinsch(y, x, ch) %mvinsch%
mvprintw(y, x, fmt [, arg...]) %mvprintw%
mvscanw(y, x, fmt [, arg...]) %mvscanw%
mvwaddch(win, y, x, ch) %mvwaddch%
mvwaddstr(win, y, x, str) %mvwaddstr%
mvwdelch(win, y, x) %mvwdelch%
mvwgetch(win, y, x) %mvwgetch%
mvwgetstr(win, y, x, str) %mvwgetstr%
Page 4 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
mvwin(win, y, x) %mvwin%
mvwinch(win, y, x) %mvwinch%
mvwinsch(win, y, x, ch) %mvwinsch%
mvwprintw(win, y, x, fmt [, arg...]) %mvwprintw%
mvwscanw(win, y, x, fmt [, arg...]) %mvwscanw%
napms(ms) %napms%
newpad(nlines, ncols) %newpad%
newterm(type, outfd, infd) %newterm%
newwin(nlines, ncols, begin_y, begin_x) %newwin%
nl() %nl%
nocbreak() %nocbreak%
nodelay(win, bf) %nodelay%
noecho() %noecho%
nonl() %nonl%
noraw() %noraw%
notimeout(win, bf) %notimeout%
overlay(srcwin, dstwin) %overlay%
overwrite(srcwin, dstwin) %overwrite%
paircontent(pair, &f, &b) %pair_content%
pechochar(pad, ch) %pechochar%
pnoutrefresh(pad, pminrow, pmincol, sminrow,
smincol, smaxrow, smaxcol) %pnoutrefresh%
prefresh(pad, pminrow, pmincol, sminrow,
smincol, smaxrow, smaxcol) %prefresh%
printw(fmt [, arg...]) %printw%
putp(str) %putp%
raw() %raw%
refresh() %refresh%
resetprogmode() %reset_prog_mode%
resetshellmode() %reset_shell_mode%
resetty() %resetty%
restartterm(term, fildes, errret) %restartterm%
ripoffline(line, init) %ripoffline%
savetty() %savetty%
scanw(fmt [, arg...]) %scanw%
NAME PAGE
scrdump(filename) %scr_dump%
scrinit(filename) %scr_init%
Page 5 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
scrrestore(filename) %scr_restore%
scroll(win) %scroll%
scrollok(win, bf) %scrollok%
setcurterm(nterm) %set_curterm%
setterm(new) %set_term%
setscrreg(top, bot) %setscrreg%
setsyx(y, x) %setsyx%
setupterm(term, fildes, errret) %setupterm%
slkattroff(attrs) %slk_attroff%
slkattron(attrs) %slk_attron%
slkattrset(attrs) %slk_attrset%
slkclear() %slk_clear%
slkinit(fmt) %slk_init%
slklabel(labnum) %slk_label%
slknoutrefresh() %slk_noutrefresh%
slkrefresh() %slk_refresh%
slkrestore() %slk_restore%
slkset(labnum, label, fmt) %slk_set%
slktouch() %slk_touch%
standend() %standend%
standout() %standout%
startcolor() %start_color%
subpad(orig, nlines, ncols, begin_y, begin_x) %subpad%
subwin(orig, nlines, ncols, begin_y, begin_x) %subwin%
tgetent(bp, name) %tgetent%
tgetflag(codename) %tgetflag%
tgetnum(codename) %tgetnum%
tgetstr(codename, area) %tgetstr%
tgoto(cap, col, row) %tgoto%
tigetflag(capname) %tigetflag%
tigetnum(capname) %tigetnum%
tigetstr(capname) %tigetstr%
touchline(win, start, count) %touchline%
touchwin(win) %touchwin%
tparm(str, p1, p2, ..., p9) %tparm%
tputs(str, count, putc) %tputs%
traceoff() %traceoff%
traceon() %traceon%
Page 6 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
typeahead(fildes) %typeahead%
unctrl(c) %unctrl%
ungetch(c) %ungetch%
vidattr(attrs) %vidattr%
vidputs(attrs, putc) %vidputs%
vwprintw(win, fmt, varglist) %vwprintw%
NAME PAGE
vwscanw(win, fmt, varglist) %vwscanw%
waddch(win, ch) %waddch%
waddstr(win, str) %waddstr%
wattroff(win, attrs) %wattroff%
wattron(win, attrs) %wattron%
wattrset(win, attrs) %wattrset%
wclear(win) %wclear%
wclrtobot(win) %wclrtobot%
wclrtoeol(win) %wclrtoeol%
wdelch(win) %wdelch%
wdeleteln(win) %wdeleteln%
wechochar(win, ch) %wechochar%
werase(win) %werase%
wgetch(win) %wgetch%
wgetstr(win, str) %wgetstr%
winch(win) %winch%
winsch(win, ch) %winsch%
winsertln(win) %winsertln%
wmove(win, y, x) %wmove%
wnoutrefresh(win) %wnoutrefresh%
wprintw(win, fmt [, arg...]) %wprintw%
wrefresh(win) %wrefresh%
wscanw(win, fmt [, arg...]) %wscanw%
wsetscrreg(win, top, bot) %wsetscrreg%
wstandend(win) %wstandend%
wstandout(win) %wstandout%
DESCRIPTION
The curses routines give the user a terminal-independent
method of updating screens with reasonable optimization.
The file <curses.h> must be included at the beginning of
programs that use any curses routines. In addition, the
Page 7 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
routine initscr() or newterm() must be called before any of
the other routines that deal with windows and screens are
used. (Three exceptions are noted where they apply.) The
routine endwin() must be called before exiting. To get
character-at-a-time input without echoing (most interactive,
screen-oriented programs want this), after calling initscr()
you should call ``cbreak(); noecho();'' Most programs would
additionally call ``nonl(); intrflush (stdscr, FALSE);
keypad(stdscr, TRUE);''.
Before a curses program is run, a terminal's tab stops
should be set and its initialization strings, if defined,
must be output. To do this, execute tput init after the
shell environment variable TERM has been set and 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
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 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 stdscr. The characters in a window are
actually of type chtype, defined in <curses.h>, 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
Page 8 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
Manipulation" for more information.
In addition to drawing characters on the screen, video
attributes may be included which cause the characters to be
underlined or shown in reverse video on terminals that
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 AREVERSE, ACSHLINE, and KEYLEFT.
Routines that manipulate color on color alphanumeric
terminals are new in this release of curses. To use these
routines startcolor() must be called, usually right after
initscr(). Colors are always used in pairs (referred to as
color-pairs). A color-pair consists of a foregound color
(for characters) and a background color (for the field the
characters are displayed on). A programmer initializes a
color-pair with the routine initpair(). After it has been
initialized, COLORPAIR(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 initcolor() to change the
definition of a color. The routines hascolor() and
canchangecolor() return TRUE or FALSE, depending on
whether the terminal has color capabilities and whether the
user can change the colors. The routine colorcontent()
allows a user to identify the amounts of red, green, and
blue components in an initialized color. The routine
paircontent() 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
Page 9 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
is immediately cleared and repainted from scratch. This is
how most programs would implement a ``repaint-screen''
function. 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
compiled 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
directories.) However, if TERMINFO is set to $HOME/myterms,
curses will first check $HOME/myterms/a/att4425, and, if
that fails, will then check /usr/lib/terminfo/a/att4425.
This is useful for developing experimental definitions or
when write permission on /usr/lib/terminfo is not available.
The integer variables LINES and COLS are defined in
<curses.h>, and will be initialized by initscr() with the
size of the screen. (For more information, see the
subsection "Terminfo-Level Manipulations".) The integer
variables COLORS and COLORPAIRS 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 startcolor(). 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>.
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
Page 10 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
without a prefix generally use stdscr.
The routines prefixed with mv require y and x coordinates to
move to before performing the appropriate action. The mv()
routines imply a call to move() before the call to the other
routine. The window argument is always specified before the
coordinates. y always refers to the row (of the window),
and x always refers to the column. The upper left corner is
always (0,0), not (1,1). The routines prefixed with mvw
take both a window argument and y and x coordinates.
In each case, win is the window affected and pad is the pad
affected. (win and pad are always of type WINDOW *.)
Option-setting routines require a boolean flag bf with the
value TRUE or FALSE. (bf is always of type bool.) The types
WINDOW, bool, and chtype are defined in <curses.h>. See the
SYNOPSIS for a summary of what types all variables are.
All routines return either the integer ERR or the integer
OK, unless otherwise noted. Routines that return pointers
always return NULL on error.
Sometimes the description of a routine refers to a second
routine. If the routine referred to is prefixed with a w,
then you should assume that other versions of the second
routine behave similarly. For example, the description of
initscr() refers to wrefresh(). This implies that the same
result will occur if refresh() is called.
Page 11 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
Section 1: Overall Screen Manipulation
WINDOW *initscr()
The first routine called should almost always be
initscr(). (The exceptions are slkinit(),
filter(), and ripoffline().) This will determine
the terminal type and initialize all curses data
structures. initscr() also arranges that the
first call to wrefresh() will clear the screen.
If errors occur, initscr() will write an
appropriate error message to standard error and
exit; otherwise, a pointer to stdscr is returned.
If the program wants an 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
exiting 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
Page 12 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
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.
SCREEN *setterm(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.
Page 13 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
Section 2: 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 cursor. 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
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
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
Page 14 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
only one burst of output, with probably fewer
total characters transmitted and certainly less
processor time used.
WINDOW *newwin(nlines, ncols, begin_y, begin_x)
Create and return a pointer to a new window with
the given number of lines (or rows), nlines, and
columns, ncols. The upper left corner of the
window is at line begin_y, column begin_x. If
either nlines or ncols is 0, they will be set to
the value of lines-begin_y and cols-begin_x. A
new full-screen window is created by calling
newwin(0, 0, 0, 0).
mvwin(win, y, x)
Move the window so that the upper left corner will
be at position (y, x). If the move would cause
any portion of the window to be moved off the
screen, it is an error and the window is not
moved.
WINDOW *subwin(orig, nlines, ncols, begin_y, begin_x)
Create and return a pointer to a new window with
the given number of lines (or rows), nlines, and
columns, ncols. The window is at position
(begin_y, begin_x) on the screen. (This position
is relative to the screen, and not to the window
orig.) The window is made in the middle of the
window orig, so that changes made to one window
will affect the character image of both windows.
When changing the image of a subwindow, it will be
necessary to call touchwin() or touchline() on
orig before calling wrefresh() on orig.
delwin(win)
Delete the named window, freeing all memory
associated with it. If you try to delete a main
window before all of its subwindows have been
deleted, ERR will be returned.
Page 15 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
WINDOW *newpad(nlines, ncols)
Create and return a pointer to a new pad data
structure with the given number of lines (or
rows), nlines, and columns, ncols. A pad is a
window that is not restricted by the screen size
and is not necessarily associated with a
particular part of the screen. Pads can be used
when a large window is needed, and only a part of
the window will be on the screen at one time.
Automatic refreshes of pads (e.g. from scrolling
or echoing of input) do not occur. It is not
legal to call wrefresh() with a pad as an
argument; the routines prefresh() or
pnoutrefresh() should be called instead. Note
that these routines require 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 the
character image of both windows. When changing
the image of a subwindow, it will be necessary to
call touchwin() or touchline() on orig before
calling prefresh() on orig.
smaxcol)
prefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow,
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
Page 16 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
rectangle to be displayed. sminrow, smincol,
smaxrow, and smaxcol specify the edges, on the
screen, of the rectangle to be displayed in. The
lower right corner in the pad of the rectangle to
be displayed is calculated from the screen
coordinates, since the rectangles must be the same
size. Both rectangles must be entirely contained
within their respective structures. Negative
values of pminrow, pmincol, sminrow, or smincol
are treated as if they were zero.
Section 3: Output
These routines are used to manipulate text in windows.
addch(ch)
waddch(win, ch)
mvaddch(y, x, ch)
mvwaddch(win, y, x, ch)
The character ch is put into the window at the
current cursor position of the window and the
position of the window cursor is advanced. Its
function is similar to that of putchar (see
putc(3S)). At the right margin, an automatic
newline is performed. At the bottom of the
scrolling region, if scrollok() is enabled, the
scrolling region will be scrolled up one line.
If ch is a tab, newline, or backspace, the cursor
will be moved appropriately within the window. A
newline also does a wclrtoeol() before moving.
Tabs are considered to be at every eighth column.
If ch is another control character, it will be
drawn in the ^X notation. (Calling winch() on a
position in the window containing a control
character will not return the control character,
but instead will return one character of the
representation of the control 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
Page 17 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
winch() and waddch().) See wstandout(), below.
Note that ch is actually of type chtype, not a
character.
Note that addch(), mvaddch(), and mvwaddch(), are
macros.
echochar(ch)
wechochar(win, ch)
pechochar(pad, ch)
These routines are functionally equivalent to a
call to addch(ch) 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 character 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
character.
Note that echochar() is a macro.
Page 18 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
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 ASTANDOUT,
AREVERSE, ABOLD, ADIM, ABLINK, AUNDERLINE,
and AALTCHARSET, as well as the macro
COLORPAIR(n). These attributes are defined in
<curses.h> and can be combined with the C logical
OR (| ) operator.
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
Page 19 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
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, ASTANDOUT).
wstandend(win, attrs) is the same as wattrset(win,
0), that is, it turns off all attributes.
Note that wattroff(), wattron(), wattrset(),
wstandend(), and wstandout() return 1 at all
times.
Note that attrs is actually of type chtype, not a
character.
Note that attroff(), attron(), attrset(),
standend(), and standout() are macros.
Page 20 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
beep()
flash() These routines are used to signal the 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 signal (bell
or beep) but only some can flash the screen.
box(win, vertch, horch)
A box is drawn around the edge of the window, win.
vertch and horch are the characters the box is to
be drawn with. If vertch and horch are 0, then
appropriate default characters, ACSVLINE and
ACSHLINE, will be used.
Note that vertch and horch are actually of type
chtype, not characters.
erase()
werase(win)
These routines copy blanks to every position in
the window.
Note that erase() is a macro.
clear()
wclear(win)
These routines are like erase() and werase(), but
they also call clearok(), arranging that the
screen will be cleared completely on the next call
to wrefresh() for that window, and repainted from
scratch.
Note that clear() is a macro.
clrtobot()
wclrtobot(win)
All lines below the cursor in this 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)
Page 21 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
The current line to the right of the cursor,
inclusive, is erased.
Note that clrtoeol() is a macro.
delayoutput(ms)
Insert a ms millisecond pause in the output. It
is not recommended that this routine be used
extensively, because padding characters are used
rather than a processor pause.
Page 22 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
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 that delch(), mvdelch(), and mvwdelch() are
macros.
deleteln()
wdeleteln(win)
The line under the cursor in the window is
deleted. All lines below the current line are
moved up one line. The bottom line of the window
is cleared. The 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.
Note that getyx() is a macro, so no ``&'' is
necessary before the variables y and x.
getbegyx(win, y, x)
getmaxyx(win, y, x)
The current beginning coordinates (getbegyx()) or
size (getmaxyx()) of the specified window are
placed in the two integer variables y and x.
Note that getbegyx() and getmaxyx() are macros, so
no ``&'' is necessary before the variables y and
x.
insch(ch)
winsch(win, ch)
mvwinsch(win, y, x, ch)
mvinsch(y, x, ch)
Page 23 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
The character ch is inserted before the character
under the cursor. All characters to the right are
moved one space to the right, losing the rightmost
character of the line. The cursor position does
not change (after moving to (y, x), if specified).
(This does not imply use of the hardware
``insert-character'' feature.)
Note that ch is actually of type chtype, not a
character.
Note that insch(), mvinsch(), and mvwinsch() are
macros.
Page 24 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
insertln()
winsertln(win)
A blank line is inserted above the current line
and the bottom line is lost. (This does not imply
use of the hardware ``insert-line'' feature.)
Note that insertln() is a macro.
move(y, x)
wmove(win, y, x)
The cursor associated with the window is moved to
line (row) y, column x. This does not move the
physical cursor of the terminal until wrefresh()
is called. The position specified is relative to
the upper left corner of the window, which is (0,
0).
Note that move() is a macro.
overlay(srcwin, dstwin)
overwrite(srcwin, dstwin)
These routines overlay text from srcwin on top of
text from dstwin wherever the two windows overlap.
The difference is that overlay() is non-
destructive (blanks are not copied), while
overwrite() is destructive.
dmaxrow,
copywin(srcwin, dstwin, sminrow, smincol, dminrow, dmincol,
dmaxcol, overlay)
This routine provides finer control over the
overlay() and overwrite() routines. As 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(3). The
string which would be output by printf(3) is
instead output using waddstr() on the given
Page 25 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
window.
vwprintw(win, fmt, varglist)
This routine corresponds to vfprintf(3S). It
performs a wprintw() using a variable argument
list. The third argument is a va_list, a pointer
to a list of arguments, as defined in <varargs.h>.
See the vprintf(3S) and varargs(5) manual pages
for a detailed description on how to use variable
argument lists.
scroll(win)
The window is scrolled up one line. This involves
moving the lines in the window data structure.
touchwin(win)
touchline(win, start, count)
Throw away all optimization information about
which parts of the window have been touched, by
pretending that the entire window has been drawn
on. This is sometimes necessary when using
overlapping windows, since a change to one window
will affect the other window, but the records of
which lines have been changed in the other window
will not reflect the change. touchline() only
pretends that count lines have been changed,
beginning with line start .
Section 4: 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
Page 26 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
program will hang until a character is typed or
the specified timeout has been reached. Unless
noecho() has been set, the character will also be
echoed into the designated window.
When wgetch() is called, before getting a
character, it will call wrefresh() if anything in
the window has changed (for example, the cursor
has moved or text changed).
When using getch(), wgetch(), mvgetch(), or
mvwgetch(), do not set both NOCBREAK mode
(nocbreak()) and ECHO mode (echo()) at the same
time. Depending on the state of the tty(7) driver
when each character is typed, the program may
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
macros.
getstr(str)
wgetstr(win, str)
mvgetstr(y, x, str)
Page 27 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
mvwgetstr(win, y, x, str)
A series of calls to wgetch() is made, until a
newline, carriage return, or enter key is
received. The resulting value (except for this
terminating character) is placed in the area
pointed at by the character pointer str. The
user's erase and kill characters are interpreted.
See wgetch() for how it handles characters
differently from stdio routines (especially ^D).
Note that getstr(), mvgetstr(), and mvwgetstr()
are macros.
ungetch(c)
Place c onto the input queue, to be returned by
the next call to wgetch().
flushinp()
Throws away any typeahead that has been typed by
the user and has not yet been read by the program.
Note that flushinp() will not throw away any
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 ACHARTEXT and AATTRIBUTES,
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.
Page 28 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
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() in that it
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.
Section 5: Output Options Setting
These routines set options within curses that deal with
output. All options are initially FALSE, unless otherwise
stated. It is not necessary to turn these options off
before calling endwin().
clearok(win, bf)
If enabled (bf is TRUE), the next call to
wrefresh() with this window will clear the screen
completely and redraw the entire screen from
scratch. This is useful when the contents of the
screen are uncertain, or in some cases for a more
pleasing visual effect.
idlok(win, bf)
If enabled (bf is TRUE), curses will consider
using the hardware ``insert/delete-line'' feature
Page 29 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
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 editor. It is disabled
by default because ``insert/delete-line'' tends to
be visually annoying when used in applications
where it isn't really needed. If
``insert/delete-line'' 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 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.
setscrreg(top, bot)
wsetscrreg(win, top, bot)
These routines allow the user to set a software
scrolling region in a window. top and bot are the
line numbers of the top and bottom margin of the
scrolling region. (Line 0 is the top line of the
window.) If this option and scrollok() are
enabled, an attempt to move off the bottom margin
line will cause all lines in the scrolling region
to scroll up one line. (Note that this has
nothing to do with use of a physical scrolling
region capability in the terminal, like that in
the DEC VT100. Only the text of the window is
scrolled; if idlok() is enabled and the terminal
has either a scrolling region or ``insert/delete-
line'' capability, they will probably be used by
the output routines.)
Page 30 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
Note that setscrreg() is a macro.
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 typing the last character of the
last line. If disabled (bf is FALSE), the cursor
is left on the bottom line at the location where
the offending character was entered. If enabled
(bf is TRUE), wrefresh() is called on the window,
and then the physical terminal and window are
scrolled up one line. (Note that in order to get
the physical scrolling effect on the terminal, it
is also necessary to call idlok().)
Note that scrollok() will always return OK.
Section 6: 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().
cbreak()
nocbreak()
These two routines put the terminal into and out
of CBREAK mode, respectively. In CBREAK mode,
characters typed by the user are immediately
available to the program and erase/kill character
processing is not performed. 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
functionality of raw(). See wgetch() under
Page 31 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
"Input" for a discussion 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() These routines control whether carriage return is
translated into newline on input by wgetch().
Initially, this translation is done; nonl() turns
the translation off. Note that translation by the
tty(7) driver is disabled in CBREAK mode.
halfdelay(tenths)
Half-delay mode is similar to CBREAK mode in that
characters typed by the user are immediately
available to the program. However, after blocking
for tenths tenths of seconds, ERR will be returned
if nothing has been typed. tenths must be a
number between 1 and 255. Use nocbreak() to leave
half-delay mode.
intrflush(win, bf)
If this option is enabled, when an interrupt key
is pressed on the keyboard (interrupt, break,
quit) all output in the tty driver queue will be
flushed, giving the effect of faster response to
the interrupt, but causing curses to have the
wrong idea of what is on the screen. Disabling
the option prevents the flush. The default for
the option is inherited from the tty driver
settings. The window argument is ignored.
Page 32 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
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
KEYLEFT. 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
significant bits on input depends on the control
mode of the tty driver (see termio(7)). To force
8 bits to be returned, invoke meta (win, TRUE).
To force 7 bits to be returned, invoke meta (win,
FALSE). The window argument, win, is always
ignored. If the terminfo(4) capabilities smm
(meta_on) and rmm (meta_off) are defined for the
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 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.
Page 33 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
raw()
noraw() The terminal is placed into or out of RAW mode.
RAW mode is similar to CBREAK mode, in that
characters typed are immediately passed through to
the user program; however, in RAW mode, the
interrupt, quit, suspend, and flow control
characters are passed through uninterpreted,
instead of generating a signal as they do in
CBREAK mode. The behavior of the BREAK key
depends on other bits in the tty(7) driver that
are not set by curses.
typeahead(fildes)
curses does ``line-breakout 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 wrefresh() or doupdate() is called again.
This allows faster response to commands typed in
advance. Normally, the file descriptor for the
input FILE pointer passed to newterm(), 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.
Section 7: 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.
hasic() True if the terminal has insert- and delete-
Page 34 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
character capabilities.
hasil() 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() or idlok().
char killchar()
The user's current line-kill character is
returned.
char *longname()
This routine returns a pointer to a static area
containing a verbose description of the current
terminal. The maximum length of a verbose
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 setterm(), so the value should
be saved between calls to newterm() if longname()
is going to be used with multiple terminals.
Section 8: Color Manipulation
This section describes the color manipulation routines
introduced in this release of curses.
startcolor()
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 practice to call this routine right
after initscr(). startcolor() initializes eight
basic colors (black, blue, green, cyan, red,
magenta, yellow, and white), and two global
variables, COLORS and COLORPAIRS (respectively
defining the maximum number of colors and color-
pairs the terminal can support). It also restores
the terminal's colors to the values they had when
the terminal was just turned on.
Page 35 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
initpair(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 argument must be between 1 and
COLORPAIRS-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.
initcolor(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 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
initcolor() is used, all occurrences of that
color on the screen immediately change to the new
definition.
hascolors()
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 attribute.
canchangecolor()
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.
Page 36 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
colorcontent(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).
paircontent(pair, &f, &b)
This routine allows users to find out what colors
a given color-pair consists of. It requires three
arguments: the color-pair number, and two
addresses of shorts for storing the foreground and
the background color numbers. The value of the
first argument must be between 1 and COLORPAIRS-
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.
Section 9: 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, curses can simulate
them by taking over the bottom line of stdscr, reducing the
size of stdscr and the variable LINES. curses standardizes
on 8 labels of 8 characters each. If a curses program
changes the values of the soft labels, it can restore them
only to the default settings for that terminal. (Note also
that soft labels are shown in reverse video by default.)
Therefore, if before calling a curses program a user changes
the values of the soft labels, those values cannot be reset
when the curses program terminates.
slkinit(labfmt)
In order to use soft labels, this routine must be
Page 37 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
called before initscr() or newterm() is called.
If initscr() winds up using a line from stdscr to
emulate the soft labels, then labfmt determines
how the labels are arranged on the screen.
Setting labfmt to 0 indicates that the labels are
to be arranged in a 3-2-3 arrangement; 1 asks for
a 4-4 arrangement.
slkset(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.
slkrefresh()
slknoutrefresh()
These routines correspond to the routines
wrefresh() and wnoutrefresh(). Most applications
would use slknoutrefresh() because a wrefresh()
will most likely soon follow.
char *slklabel(labnum)
The current label for label number labnum is
returned, in the same format as it was in when it
was passed to slkset(); that is, how it looked
prior to being justified according to the labfmt
argument of slkset().
slkclear()
The soft labels are cleared from the screen.
slkrestore()
The soft labels are restored to the screen after a
slkclear().
slktouch()
All of the soft labels are forced to be output the
next time a slknoutrefresh() is performed.
Page 38 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
slkattron(attrs)
slkattrset(attrs)
slkattroff(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.
Section 10: Low-Level curses Access
The following routines give low-level access to various
curses functionality. These routines typically would be
used inside library routines.
defprogmode()
defshellmode()
Save the current terminal modes as the ``program''
(in curses) or ``shell'' (not in curses) state for
use by the resetprogmode() and
resetshellmode() routines. This is done
automatically by initscr().
resetprogmode()
resetshellmode()
Restore the terminal to ``program'' (in curses) or
``shell'' (out of curses) state. These are done
automatically by endwin() and doupdate() after an
endwin(), so they normally would not be called.
resetty()
savetty() These routines save and restore the state of the
terminal modes. savetty() saves the current state
of the terminal in a buffer and resetty() restores
the state to what it was at the last call to
savetty().
getsyx(y, x)
The current coordinates of the virtual screen
cursor are returned in y and x. If leaveok() is
currently TRUE, then -1,-1 will be returned. If
lines have been removed from the top of the screen
using ripoffline(), y and x include these lines;
therefore, y and x should be used only as
arguments for setsyx().
Note that getsyx() is a macro, so no ``&'' is
Page 39 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
necessary before the variables y and x.
setsyx(y, x)
The virtual screen cursor is set to y, x. If y
and x are both -1, then leaveok() will be set.
The two routines getsyx() and setsyx() are
designed to be used by a library routine which
manipulates curses windows but does not want to
change the current position of the program's
cursor. The library routine would call getsyx()
at the beginning, do its manipulation of its own
windows, do a wnoutrefresh() on its windows, call
setsyx(), and then call doupdate().
ripoffline(line, init)
This routine provides access to the same facility
that slkinit() uses to reduce the size of the
screen. ripoffline() 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 arguments:
a window pointer to the 1-line window that has
been allocated and an integer with the number of
columns in the window. Inside this initialization
routine, the integer variables LINES and COLS
(defined in <curses.h>) are not guaranteed to be
accurate and wrefresh() or doupdate() must not be
called. It is allowable to call wnoutrefresh()
during the initialization routine.
ripoffline() can be called up to five times before
calling initscr() or newterm().
scrdump(filename)
The current contents of the virtual screen are
written to the file filename.
scrrestore(filename)
The virtual screen is set to the contents of
Page 40 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
filename, which must have been written using
scrdump(). ERR is returned if the contents of
filename are not compatible with the current
release of curses software. The next call to
doupdate() will restore the screen to what it
looked like in the dump file.
scrinit(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. scrinit() would be used after initscr()
or a system(3S) call to share the screen with
another process which has done a scrdump() after
its endwin() call. The data will be declared
invalid if the terminfo(4) capability nrrmc is
true or the time-stamp of the tty is old. Note
that keypad(), meta(), slkclear(), cursset(),
flash(), and beep() do not affect the contents of
the screen, but will make the tty's time-stamp
old.
cursset(visibility)
The cursor state is set to invisible, normal, or
very visible for visibility equal to 0, 1 or 2.
If the terminal supports the visibility requested,
the previous cursor state is returned; 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
Page 41 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
having anything 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
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.
Section 11: Terminfo-Level Manipulations
These low-level routines must be called by programs that
need to deal directly with the terminfo(4) database to
handle certain terminal capabilities, such as programming
function keys. For all other functionality, curses routines
are more suitable and their use is recommended.
Initially, setupterm() should be called. (Note that
setupterm() 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) variables 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 running in a layer (see layers(1)), the
size of the current layer is used. Otherwise, the values
for lines and columns specified in the terminfo(4) database
are used.
The header files <curses.h> and <term.h> should be included,
in this order, to get the definitions for these strings,
numbers, and flags. Parameterized strings should be passed
Page 42 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
through tparm() to instantiate them. All terminfo(4)
strings (including the output of tparm()) should be printed
with tputs() or putp(). Before exiting, resetshellmode()
should be called to restore the tty modes. Programs which
use cursor addressing should output entercamode upon
startup and should output exitcamode before exiting (see
terminfo(4)). (Programs desiring shell escapes should call
resetshellmode() and output exitcamode before the shell
is called and should output entercamode and call
resetprogmode() 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 status of 1 in errret is normal, 0 means that
the terminal could not be found, and -1 means that
the terminfo(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 curterm (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 curterm.
Page 43 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
setcurterm(nterm)
nterm is of type TERMINAL *. setcurterm() sets
the variable curterm to nterm, and makes all of
the terminfo(4) boolean, numeric and string
variables use the values from nterm.
delcurterm(oterm)
oterm is of type TERMINAL *. delcurterm() frees
the space pointed to by oterm and makes it
available for further use. If oterm is the same
as curterm, 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 scrrestore(). 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 is a
putchar(3S)-like routine to which the characters
are passed, one at a time.
putp(str) A routine that calls tputs (str, 1, putchar).
vidputs(attrs, putc)
Page 44 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
Output a string that puts the terminal in the
video attribute mode attrs, which is any
combination of the attributes listed below. The
characters are passed to the putchar(3S)-like
routine putc().
vidattr(attrs)
Similar to vidputs(), except that it outputs
through putchar(3S).
The following routines return the value of the capability
corresponding to the character string containing 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.
Section 12: Termcap Emulation
These routines are included as a conversion aid for programs
that use the termcap library. Their parameters are the same
Page 45 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
and the routines are emulated using the terminfo(4)
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(codename)
Get numeric entry for codename.
char *tgetstr(codename, area)
Return the string entry for codename. If area is
not NULL, then also store it in the buffer pointed
to by area and advance area. tputs() should be
used to output the returned string.
char *tgoto(cap, col, row)
Instantiate the parameters into the given
capability. The output from this routine is to be
passed to tputs().
tputs(str, affcnt, putc)
See tputs() above, under "TERMINFO-LEVEL
MANIPULATIONS".
Section 13: 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.
Page 46 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
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.
Section 14: Use of curscr
The special window curscr can be used in only a few
routines. If the window argument to clearok() is curscr,
the next call to wrefresh() with any window will cause the
screen to be cleared and repainted from scratch. If the
window argument to wrefresh() is curscr, the screen is
immediately cleared and repainted from scratch. (This is
how most programs would implement a ``repaint-screen''
routine.) 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.
Section 15: 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 resetprogmode().
gettmode() A no-op.
nocrmode() Replaced by nocbreak().
Page 47 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
resetterm() Replaced by resetshellmode().
saveterm() Replaced by defprogmode().
setterm() Replaced by setupterm().
ATTRIBUTES
The following video attributes, defined in <curses.h>, can
be passed to the routines wattron(), wattroff(), and
wattrset(), 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 Turn all attributes off, for example:
wattrset (win, ANORMAL)
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().
A_CHARTEXT Extract character
A_ATTRIBUTES Extract attributes
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
Page 48 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
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 wgetch() 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 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
Page 49 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
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
Page 50 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
KEY_PREVIOUS 0562 previous object key
KEY_REDO 0563 redo key
KEY_REFERENCE 0564 ref(erence) key
KEY_REFRESH 0565 refresh key
KEY_REPLACE 0566 replace key
KEY_RESTART 0567 restart key
KEY_RESUME 0570 resume key
KEY_SAVE 0571 save key
KEY_SBEG 0572 shifted beginning key
KEY_SCANCEL 0573 shifted cancel key
KEY_SCOMMAND 0574 shifted command key
KEY_SCOPY 0575 shifted copy key
KEY_SCREATE 0576 shifted create key
KEY_SDC 0577 shifted delete char key
KEY_SDL 0600 shifted delete line key
KEY_SELECT 0601 select key
KEY_SEND 0602 shifted end key
KEY_SEOL 0603 shifted clear line key
KEY_SEXIT 0604 shifted exit key
KEY_SFIND 0605 shifted find key
KEY_SHELP 0606 shifted help key
KEY_SHOME 0607 shifted home key
KEY_SIC 0610 shifted input key
KEY_SLEFT 0611 shifted left arrow key
KEY_SMESSAGE 0612 shifted message key
KEY_SMOVE 0613 shifted move key
KEY_SNEXT 0614 shifted next key
KEY_SOPTIONS 0615 shifted options key
KEY_SPREVIOUS 0616 shifted prev key
KEY_SPRINT 0617 shifted print key
KEY_SREDO 0620 shifted redo key
KEY_SREPLACE 0621 shifted replace key
KEY_SRIGHT 0622 shifted right arrow
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
Page 51 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
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 AALTCHARSET bit
turned on. Otherwise, the default character listed below
will be stored in the variable. The names were chosen to be
consistent with the DEC VT100 nomenclature.
Name Default Glyph Description
ACS_ULCORNER + upper left corner
ACS_LLCORNER + lower left corner
ACS_URCORNER + upper right corner
ACS_LRCORNER + lower right corner
ACS_RTEE + right tee (-|)
ACS_LTEE + left tee (†)
ACS_BTEE + bottom tee (|)
|) ACS_TTEE + top tee (
ACS_HLINE - horizontal line
ACS_VLINE | vertical line
ACS_PLUS + plus
ACS_S1 - scan line 1
ACS_S9 _ scan line 9
ACS_DIAMOND + diamond
ACS_CKBOARD : checker board (stipple)
ACS_DEGREE ' degree symbol
ACS_PLMINUS # plus/minus
ACS_BULLET o bullet
ACS_LARROW < arrow pointing left
ACS_RARROW > arrow pointing right
ACS_DARROW v arrow pointing down
ACS_UARROW ^ arrow pointing up
ACS_BOARD # board of squares
ACS_LANTERN # lantern symbol
ACS_BLOCK # solid square block
DIAGNOSTICS
All routines return the integer OK upon successful
Page 52 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
completion and the integer ERR upon failure, unless
otherwise noted in the preceding routine descriptions.
All macros return the value of their w version, except
getsyx(), getyx(), getbegyx(), getmaxyx(). For these
macros, no useful value is returned.
Routines that return pointers always return (type *) NULL on
error.
BUGS
Currently typeahead checking is done using a nodelay read
followed by an ungetch() of any character that may have been
read. Typeahead checking is done only if wgetch() has been
called at least once. This may change when proper kernel
support is available. Programs which use a mixture of their
own input routines with curses input routines may wish to
call typeahead(-1) to turn off typeahead checking.
The argument to napms() is currently rounded up to the
nearest second.
draino (ms) only works for ms equal to 0.
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 Release 2, Release 3.0, or Release 3.1 curses will
also run on UNIX System V Release 3.2. You can link
applications with object files based on Release 2 or Release
3.0 curses/terminfo with both the Release 3.1 and the
Release 3.2 libcurses.a library; however, you cannot link
applications with object files based on Release 3.1 or
Release 3.2 curses/terminfo with the Release 2 or Release
3.0 libcurses.a library.
The plotting library plot(3X) and the curses library
curses(3X) both use the names erase() and move(). The
curses versions are macros. If you need both libraries, put
the plot(3X) code in a different source file than the
curses(3X) code, and/or #undef move() and erase() in the
Page 53 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
plot(3X) code.
Page 54 May 1989
CURSES(3X) (Terminal Information Utilities) CURSES(3X)
Between the time a call to initscr() and endwin() has been
issued, use only the routines in the curses library to
generate output. Using system calls or the "standard I/O
package" (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
cc(1), ld(1), tput(1) in the User's Reference Manual.
ioctl(2), plot(3X), putc(3S), scanf(3S), stdio(3S),
system(3S), vprintf(3S) in the Programmer's Reference
Manual.
profile(4), term(4), terminfo(4), varargs(5), termio(7),
tty(7) in the System Administrator's Reference Manual.
curses/terminfo Chapter 10 of the Programmer's Guide.
Page 55 May 1989