CURSES(3X) SysV CURSES(3X)
NAME
curses - terminal screen handling and optimization package
SYNOPSIS
The curses manual page is organized as follows:
In SYNOPSIS
- compiling information
- summary of parameters used by curses routines
- alphabetical list of curses routines, showing their parameters
In DESCRIPTION:
- An overview of how curses routines should be used
In ROUTINES, 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
- Soft Labels
- Low-level curses Access
- Terminfo-Level Manipulations
- Termcap Emulation
- Miscellaneous
- Use of curscr
Then come sections on:
- ATTRIBUTES
- FUNCTION CALLS
- LINE GRAPHICS
cc [flag ...] file ... -lcurses [library ...]
#include <curses.h> (automatically includes <stdio.h>,
<termio.h>, and <unctrl.h>).
The parameters in the following list are not global variables, but rather
this is a summary of the parameters used by the curses library routines.
All routines return the int values ERR or OK unless otherwise noted.
Routines that return pointers always return NULL on error. (ERR, OK, and
NULL are all defined in <curses.h>.) Routines that return integers are
not listed in the parameter list below.
bool bf
char **area,*boolnames[], *boolcodes[], *boolfnames[], *bp
char *cap, *capname, codename[2], erasechar, *filename, *fmt
char *keyname, killchar, *label, *longname
char *name, *numnames[], *numcodes[], *numfnames[]
char *slk_label, *str, *strnames[], *strcodes[], *strfnames[]
char *term, *tgetstr, *tigetstr, *tgoto, *tparm, *type
chtype attrs, ch, horch, vertch
FILE *infd, *outfd
int begin_x, begin_y, begline, bot, c, col, count
int dmaxcol, dmaxrow, dmincol, dminrow, *errret, fildes
int (*init( )), labfmt, labnum, line
int ms, ncols, new, newcol, newrow, nlines, numlines
int oldcol, oldrow, overlay
int p1, p2, p9, pmincol, pminrow, (*putc( )), row
int smaxcol, smaxrow, smincol, sminrow, start
int tenths, top, visibility, x, y
SCREEN *new, *newterm, *set_term
TERMINAL *cur_term, *nterm, *oterm
va_list varglist
WINDOW *curscr, *dstwin, *initscr, *newpad, *newwin, *orig
WINDOW *pad, *srcwin, *stdscr, *subpad, *subwin, *win
addch(ch)
addstr(str)
attroff(attrs)
attron(attrs)
attrset(attrs)
baudrate()
beep()
box(win, vertch, horch)
cbreak()
clear()
clearok(win, bf)
clrtobot()
clrtoeol()
copywin(srcwin, dstwin, sminrow, smincol, dminrow, dmincol,
dmaxrow, dmaxcol, overlay)
curs_set(visibility)
def_prog_mode()
def_shell_mode()
del_curterm(oterm)
delay_output(ms)
delch()
deleteln()
delwin(win)
doupdate()
draino(ms)
echo()
echochar(ch)
endwin()
erase()
erasechar()
filter()
flash()
flushinp()
garbagedlines(win, begline, numlines)
getbegyx(win, y, x)
getch()
getmaxyx(win, y, x)
getstr(str)
getsyx(y, x)
getyx(win, y, x)
halfdelay(tenths)
has_ic()
has_il()
idlok(win, bf)
inch()
initscr()
insch(ch)
insertln()
intrflush(win, bf)
isendwin()
keyname(c)
keypad(win, bf)
killchar()
leaveok(win, bf)
longname()
meta(win, bf)
move(y, x)
mvaddch(y, x, ch)
mvaddstr(y, x, str)
mvcur(oldrow, oldcol, newrow, newcol)
mvdelch(y, x)
mvgetch(y, x)
mvgetstr(y, x, str)
mvinch(y, x)
mvinsch(y, x, ch)
mvprintw(y, x, fmt [, arg...])
mvscanw(y, x, fmt [, arg...])
mvwaddch(win, y, x, ch)
mvwaddstr(win, y, x, str)
mvwdelch(win, y, x)
mvwgetch(win, y, x)
mvwgetstr(win, y, x, str)
mvwin(win, y, x)
mvwinch(win, y, x)
mvwinsch(win, y, x, ch)
mvwprintw(win, y, x, fmt [, arg...])
mvwscanw(win, y, x, fmt [, arg...])
napms(ms)
newpad(nlines, ncols)
newterm(type, outfd, infd)
newwin(nlines, ncols, begin_y, begin_x)
nl()
nocbreak()
nodelay(win, bf)
noecho()
nonl()
noraw()
notimeout(win, bf)
overlay(srcwin, dstwin)
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_clear()
slk_init(fmt)
slk_label(labnum)
slk_noutrefresh()
slk_refresh()
slk_restore()
slk_set(labnum, label, fmt)
slk_touch()
standend()
standout()
subpad(orig, nlines, ncols, begin_y, begin_x)
subwin(orig, nlines, ncols, begin_y, begin_x)
tgetent(bp, name)
tgetflag(codename)
tgetnum(codename)
tgetstr(codename, area)
tgoto(cap, col, row)
tigetflag(capname)
tigetnum(capname)
tigetstr(capname)
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 you a terminal-independent way to update screens
with reasonable optimization.
In order to initialize the routines, the routine initscr() or newterm()
must be called before any of the other routines that deal with windows
and screens are used. (Three exceptions are noted where they apply.)
The routine endwin() must be called before exiting. To get character-
at-a-time input without echoing, (most interactive, screen oriented
programs want this) after calling initscr() you should call ``cbreak();
noecho();'' Most programs would additionally call ``nonl(); 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. (The "windows"
managed by curses bear no relation to the windows managed by the Domain
system's Display Manager, and are typically used by dumb terminals and,
to some extent, by terminal emulation packages that run on Domain/OS
SysV.) A default window called stdscr is supplied, which is the size of
the terminal screen. Others may be created with newwin().
Windows are referred to by variables declared as WINDOW *; the type
WINDOW is defined in <curses.h> to be a C structure. These data
structures are manipulated with routines described below, among which the
most basic are move() and addch(). (More general versions of these
routines are included with names beginning with w, allowing you to
specify a window. The routines not beginning with w usually affect
stdscr.) Then refresh() is called, telling the routines to make the
user's terminal screen look like 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 Manipulation" 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.
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" 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 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
/usr/lib/terminfo. For example, if the environment variable TERM is set
to apollo_19l, then the compiled terminal definition is found in
/usr/lib/terminfo/a/apollo_19l. (The a is copied from the first letter
of apollo_19l to avoid creation of huge directories.) However, if
TERMINFO is set to $HOME/myterms, curses will first check
$HOME/myterms/a/apollo_19l. If that fails, it then will check
/usr/lib/terminfo/a/apollo_19l. This is useful for developing
experimental definitions or when write permission on /usr/lib/terminfo is
not available.
The integer variables LINES and COLS are defined in <curses.h>, and will
be filled in by initscr() with the size of the screen. (For more
information, see the subsection "terminfo-Level Manipulations".) The
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 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.
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; 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 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 *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 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
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 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 routine, often it will be necessary
to call touchwin() or touchline() on orig before
calling wrefresh().
delwin(win) Delete the named window, freeing up all memory
associated with it. In the case of overlapping
windows, subwindows should be deleted before the main
window.
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 (for
example 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 both windows. When using
this routine, often it will be necessary to call
touchwin() or touchline() on orig before calling
prefresh().
prefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol)
pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol)
These routines are analogous to wrefresh() and
wnoutrefresh() except that pads, instead of windows,
are involved. The additional parameters are needed
to indicate what part of the pad and screen are
involved. pminrow and pmincol specify the upper left
corner, in the pad, of the rectangle to be displayed.
sminrow, smincol, smaxrow, and smaxcol specify the
edges, on the screen, of the rectangle to be
displayed in. The lower right corner in the pad of
the rectangle to be displayed is calculated from the
screen coordinates, since the rectangles must be the
same size. Both rectangles must be entirely
contained within their respective structures.
Negative values of pminrow, pmincol, sminrow, or
smincol are treated as if they were zero.
Output
These routines are used to "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 considered 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
ORing them into the parameter. This will result in
these attributes also being set. (The intent here is
that text, including attributes, can be copied from
one place to another using inch() and addch().) See
standout(), below.
Note 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.
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 A_STANDOUT, A_REVERSE, A_BOLD, A_DIM,
A_BLINK, A_UNDERLINE, and A_ALTCHARSET. These
constants 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.
attrset(attrs) sets the current attributes of the
given window to attrs. attroff(attrs) turns off the
named attributes without turning on or off any other
attributes. attron(attrs) turns on the named
attributes without affecting any others. standout()
is the same as attron(A_STANDOUT). standend() is the
same as attrset (0), that is, it turns off all
attributes.
Note that attrs is actually of type chtype, not a
character.
Note that attroff(), attron(), attrset(), standend(),
and standout() are macros.
beep()
flash() These routines are used to signal the terminal user.
beep() will sound the audible alarm on the terminal,
if 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, ACS_VLINE and
ACS_HLINE, will be used.
Note that vertch and horch are actually of type
chtype, not characters.
erase()
werase(win) These routines copy blanks to every position in the
window.
Note that erase() is a macro.
clear()
wclear(win) These routines are like erase() and werase(), but
they also call clearok(), arranging that the screen
will be cleared completely on the next call to
wrefresh() for that window, and repainted from
scratch.
Note that clear() is a macro.
clrtobot()
wclrtobot(win) All lines below the cursor in this 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 processor pause.
delch()
wdelch(win)
mvdelch(y, x)
mvwdelch(win, y, x) The character under the cursor in the window is
deleted. All characters to the right on the same
line are moved to 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. This is implemented
as a macro, so no "&" is necessary before the
variables.
getbegyx(win, y, x)
getmaxyx(win, y, x) Like getyx(), these routines store the current
beginning 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 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.
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. scrwin
and dstwin need not be the same size; only text where
the two windows overlap is copied. The difference is
that overlay() is non-destructive (blanks are not
copied), while overwrite() is destructive.
copywin(srcwin, dstwin, sminrow, smincol, dminrow, dmincol, dmaxrow,
dmaxcol, overlay)
This routine provides a finer grain of control over
the overlay() and overwrite() routines. Like in the
prefresh() routine, a rectangle is specified in the
destination window, (dminrow, dmincol) and (dmaxrow,
dmaxcol), and the upper-left-corner 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 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. As an
optimization, if the window is stdscr and the
scrolling region is the entire window, the physical
screen will be scrolled at the same time.
touchwin(win)
touchline(win, start, count)
Throw away all optimization information about which
parts of the window have been touched, by 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 .
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 or the specified time-out has been
reached. Unless noecho() has been set, the character
will also be echoed into the designated window. No
refresh() will occur between the move() and the
getch() done within the routines mvgetch() and
mvwgetch().
When using getch(), wgetch(), mvgetch(), or
mvwgetch(), do not set both NOCBREAK mode
(nocbreak()) and ECHO mode (echo()) at the same time.
Depending on the state of the tty(7) driver when each
character is typed, the program may produce
undesirable results.
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)
mvwgetstr(win, y, x, str)
A series of calls to getch() is made, until a
newline, carriage return, or enter key is received.
The resulting value is placed in the area pointed at
by the character pointer str. The user's erase and
kill characters are interpreted. As in mvgetch(), no
refresh() is done between the move() and getstr()
within the routines mvgetstr() and mvwgetstr().
Note that getstr(), mvgetstr(), and mvwgetstr() are
macros.
flushinp() Throws away any typeahead that has been typed by the
user and has not yet been read by the program.
ungetch(c) Place c back onto the input queue to be returned by
the next call to wgetch().
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 ORed 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.
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 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 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.
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.)
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 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().)
nl()
nonl() These routines control whether newline is translated
into carriage return and linefeed on output, and
whether return is translated into newline on input.
Initially, the translations do occur. By disabling
these translations using nonl(), curses is able to
make better use of the linefeed capability, resulting
in faster cursor motion.
Input Options Setting
These routines set options within curses that deal with input. The
options involve using ioctl(2) and therefore interact with curses
routines. It is not necessary to turn these options off before calling
endwin().
For more information on these options, see the Domain/OS Programming
Environment Reference.
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() overrides raw(). See getch()
under "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 getch() as they are typed.
Echoing by the tty driver is always disabled, but
initially getch() is in ECHO mode, so characters
typed are echoed. Authors of most interactive
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
getch() under "Input" for a discussion of how these
routines interact with cbreak() and nocbreak().
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.
keypad(win, bf) This option enables 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)
and off (made to work locally), turning on this
option will cause the terminal keypad to be turned on
when wgetch() is called.
meta(win, bf) If enabled, characters returned by wgetch() are
transmitted with all 8 bits, instead of with the
highest bit stripped. In order for meta() to work
correctly, the km (has_meta_key) capability has to be
specified in the terminal's terminfo(4) entry.
nodelay(win, bf) This option causes wgetch() to be a non-blocking
call. If no input is ready, wgetch() will return
ERR. If disabled, wgetch() will hang until a key is
pressed.
notimeout(win, bf) While interpreting an input escape sequence, wgetch()
will set a timer while waiting for the next
character. If notimeout(win, TRUE) is called, then
wgetch() will not set a timer. The purpose of the
time-out is to differentiate 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
program. The differences are that in RAW mode, the
interrupt, 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
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().
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 set_term(), so the value should be saved
between calls to newterm() if longname() is going to
be used with multiple terminals.
Soft Labels
If desired, curses will manipulate the set of soft function-key labels
that exist on many terminals. For those terminals that do not have soft
labels, if you want to simulate them, curses will take over the bottom
line of stdscr, reducing the size of stdscr and the variable LINES.
curses standardizes on 8 labels of 8 characters each.
slk_init(labfmt) In order to use soft labels, this routine must be
called before initscr() or newterm() is called. If
initscr() winds up using a line from stdscr to
emulate the soft labels, then labfmt determines how
the labels are arranged on the screen. Setting
labfmt to 0 indicates that the labels are to be
arranged in a 3-2-3 arrangement; 1 asks for a 4-4
arrangement.
slk_set(labnum, label, labfmt)
labnum is the label number, from 1 to 8. label is
the string to be put on the label, up to 8 characters
in length. A NULL string or a NULL pointer will put
up a blank label. labfmt is one of 0, 1 or 2, to
indicate whether the label is to be left-justified,
centered, or right-justified within the label.
slk_refresh()
slk_noutrefresh() These routines correspond to the 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.
Low-Level curses Access
The following routines give low-level access to various curses
functionality. These routines typically would be used inside of library
routines.
def_prog_mode()
def_shell_mode() Save the current terminal modes as the "program" (in
curses) or "shell" (not in curses) state for use by
the reset_prog_mode() and reset_shell_mode()
routines. This is done automatically by initscr().
reset_prog_mode()
reset_shell_mode() Restore the terminal to "program" (in curses) or
"shell" (out of curses) state. These are done
automatically by endwin() and doupdate() after an
endwin(), so they normally would not be called.
resetty()
savetty() These routines save and restore the state of the
terminal modes. savetty() saves the current state of
the terminal in a buffer and resetty() restores the
state to what it was at the last call to savetty().
getsyx(y, x) The current coordinates of the virtual screen cursor
are returned in y and x. Like getyx(), the variables
y and x do not take an "&" before them. If leaveok()
is currently TRUE, then -1,-1 will be returned. If
lines may have been removed from the top of the
screen using ripoffline() and the values are to be
used beyond just passing them on to setsyx(), the
value y+stdscr->_yoffset should be used for those
other uses.
Note that getsyx() is a macro.
setsyx(y, x) The virtual screen cursor is set to y, x. If y and x
are both -1, then leaveok() will be set. The two
routines getsyx() and setsyx() are designed to be
used by a library routine which manipulates curses
windows but does not want to mess up 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 slk_init() 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().
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
initialize the curses data structures about what the
terminal currently has on its screen. If the data is
determined to be valid, curses will base its next
update of the screen on this information rather than
clearing the screen and starting from scratch.
scr_init() would be used after initscr() or a
system(3S) call to share the screen with another
process which has done a scr_dump() after its
endwin() call. The data will be declared invalid if
the time-stamp of the tty is old or the terminfo(4)
capability nrrmc is true.
curs_set(visibility)
The cursor is set to invisible, normal, or very
visible for visibility equal to 0, 1 or 2.
draino(ms) Wait until the output has drained enough that it will
only take ms more milliseconds to drain completely.
garbagedlines(win, begline, numlines)
This routine indicates to curses that a screen line
is garbaged and should be thrown away before having
anything written over the top of it. It could be
used for programs such as editors 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.
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 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 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
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
terminfo(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)
Like setupterm() after a memory restore.
char *tparm(str, p1, p2, ..., p9)
Instantiate the string str with parms pi. A pointer
is returned to the result of str with the parameters
applied.
tputs(str, count, putc)
Apply padding to the string str and output it. str
must be a terminfo(4) string variable or the return
value from tparm(), tgetstr(), tigetstr() or tgoto().
count is the number of lines affected, or 1 if not
applicable. putc() is a putchar(3S)-like routine to
which the characters are passed, one at a time.
putp(str) A routine that calls tputs (str, 1, putchar()).
vidputs(attrs, putc)
Output a string that puts the terminal in the video
attribute mode attrs, which is any combination of the
attributes listed below. The characters are passed
to the putchar(3S)-like routine putc().
vidattr(attrs) Like vidputs(), except that it outputs through
putchar(3S).
mvcur(oldrow, oldcol, newrow, newcol)
Low-level cursor motion.
The following routines return the value of the capability corresponding
to the terminfo(4) capname passed to them, such as xenl.
tigetflag(capname) The value -1 is returned if capname is not a Boolean
capability.
tigetnum(capname) The value -2 is returned if capname is not a numeric
capability.
tigetstr(capname) The value (char *) -1 is returned if capname is not a
string capability.
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) database.
tgetent(bp, name) Look up termcap entry for name. The emulation
ignores the buffer pointer bp.
tgetflag(codename) Get the Boolean entry for codename.
tgetnum(codes) Get numeric entry for codename.
char *tgetstr(codename, area)
Return the string entry for codename. If area is not
NULL, then also store it in the buffer pointed to by
area and advance area. tputs() should be used to
output the returned string.
char *tgoto(cap, col, row)
Instantiate the parameters into the given capability.
The output from this routine is to be passed to
tputs().
tputs(str, affcnt, putc)
See tputs() above, under "Terminfo-Level
Manipulations".
Miscellaneous
traceoff()
traceon() Turn off and on debugging trace output when using the
debug version of the curses library,
/usr/lib/libdcurses.a. This facility is available
only to 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 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.
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 attron(), attroff(), and attrset(), or OR'ed with the
characters passed to addch().
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_CHARTEXT Bit-mask to extract character (described under winch())
A_ATTRIBUTES Bit-mask to extract attributes (described under winch())
A_NORMAL Bit mask to reset all attributes off
(for example: attrset (A_NORMAL)
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
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
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
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 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 setscrreg(),
wsetscrreg(), getsyx(), getyx(), getbegy(), 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 will be
changed 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
All programs that ran with Domain/IX curses also will run on SysV.
However, the new features implemented in the present version of curses
are available only under SysV. You may link applications with object
files based on the Domain/IX curses/terminfo with the SysV libcurses.a
library. You may link applications with object files based on SysV
curses/terminfo with the Domain/IX libcurses.a library, so long as they
do not use the new features in SysV curses/terminfo.
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
plot(3X) code.
Between the time a call to initscr() and endwin() has been issued, use
only the routines in the curses library to generate output. Using system
calls or the "standard I/O package" (see stdio(3S)) for output during
that time can cause unpredictable results.
SEE ALSO
cc(1), ld(1), ioctl(2), plot(3X), putc(3S), scanf(3S), stdio(3S),
system(3S), vprintf(3S), profile(4), term(4), terminfo(4), varargs(5).
termio(7), tty(7) in Domain/OS System Administration Reference.
Domain/OS Programming Environment Reference.
NOTES
*DEC and VT100 are registered trademarks of the Digital Equipment
Corporation.