CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
NAME
curses -- terminal-screen handling and optimization package
SYNOPSIS
The curses manual page is organized as follows.
o In SYNOPSIS
-- Compiling information
-- Summary of parameters used by curses routines
-- Alphabetical list of curses routines showing their
parameters
o In DESCRIPTION
-- An overview of how curses routines should be used
o In ROUTINES, descriptions of each curses routine are
grouped under the following 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
-- Using curscr
Next are sections on the following.
-- ATTRIBUTES
-- FUNCTION-KEYS
-- LINE GRAPHICS
-- cc [flag...] file... -lcurses [library ...]
-- #include curses.h (automatically includes stdio.h,
termio.h, and unctrl.h)
The parameters in the following list are not global vari-
ables, but rather a summary of the parameters used by 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).
SUPER-UX Last change: May 16, 1997 1
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
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[], *strf-
names[]
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 pl, 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, dmin-
col, 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)
SUPER-UX Last change: May 16, 1997 2
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
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)
SUPER-UX Last change: May 16, 1997 3
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
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)
SUPER-UX Last change: May 16, 1997 4
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
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
curses routines give users a terminal-independent method of
updating screens with reasonable optimization.
To initialize the library correctly, include the curses.h
header file in front of the file used for the curses
library. The initscr() or newterm() routine 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 endwin() routine must be called before exiting.
SUPER-UX Last change: May 16, 1997 5
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
To get character-at-a-time input without echoing, (most
interactive, screen-oriented programs want this) after call-
ing initscr(), call cbreak(); noecho();. Most programs would
additionally call nonl(); intrflush(stdscr, FALSE); key-
pad(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(l), and
the "Tabs and Initialization" subsection in terminfo(4).
The curses library contains routines that manipulate data
structures called windows that can be thought of as two-
dimensional arrays of characters representing all or part of
a terminal screen. A default window called stdscr is sup-
plied, which is the size of the terminal screen. Others can
be created with newwin(). Windows are referred to by vari-
ables declared as WINDOW *; the type WINDOW is defined in
curses.h to be a C structure. These data structures are
manipulated with routines described later, among which the
most basic are move() and addch().
NOTE
More general versions of these routines are included with
names beginning with "w" that allow users to specify a
window. The routines not beginning with w usually affect
stdscr.
After the data structures are manipulated with the routines,
refresh() is called, telling the routines to make the user's
terminal screen look like stdscr. The characters in a window
are actually chtype, so that other information about the
character can also be stored with each character.
Special windows called pads can also be manipulated. These
are windows that are not constrained to the size of the
screen and whose contents need not be displayed completely.
See the description of newpad() under "Window and Pad Manip-
ulation" for more information.
In addition to drawing characters on the screen, video
attributes can be included that underline or highlight
(reverse video) characters on terminals that support such
display enhancements. Line drawing characters can be speci-
fied to be output. On input, curses is also able to trans-
late arrow and function keys that transmit escape sequences
into single values. The video attributes, line drawing char-
acters, and input values use names (defined in curses.h)
such as A_REVERSE, ACS_HLINE, and KEY_LEFT.
SUPER-UX Last change: May 16, 1997 6
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
curses also defines the WINDOW * variable curscr that 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 clears and
repaints the screen from scratch. If the window argument to
wrefresh() is curscr, the screen in immediately cleared and
repainted from scratch. This is how most programs would
implement a repaint-screen function. More information on
using curscr is provided where its use is appropriate.
The environment variables LINES and COLUMNS can be set to
override terminfo's idea of how large a screen is. These can
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 checks for a local terminal definition before
checking in the standard place. For example, if the environ-
ment variable TERM is set to att4425, then the compiled ter-
minal 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 first checks
$HOME/myterms/a/att4425, and, if that fails, checks
/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 are filled in by initscr() with the size of
the screen. (For more information, see the subsection on
terminfo-level manipulations.) The constants TRUE and FALSE
have the values 1 and 0, respectively. The ERR and OK con-
stants are returned by routines to indicate whether the rou-
tine successfully completed. These constants are also
defined in curses.h.
ROUTINES
Many of the following routines have two or more versions.
The routines prefixed with "w" require a window argument.
The routines prefixed with "p" require a pad argument. Those
without a prefix generally use stdscr.
The routines prefixed with "mv" require y and x coordinates
to move to before performing the appropriate action. The
mv() routines imply a call to move() before the call to the
other routine. The window argument is always specified
before the coordinates. y always refers to the row (of the
window), and x always refers to the column. The upper-left
corner is always (0,0), not (1,1). The routines prefixed
with "mvw" take both a window argument and y and x
SUPER-UX Last change: May 16, 1997 7
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
coordinates.
In each case, win is the window affected and pad is the pad
affected. (win and pad are always a WINDOW * type.) Option-
setting routines require a boolean flag -bf with the value
TRUE or FALSE. (bf is always a bool type.) The WINDOW, bool,
and chtype types 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(), fil-
ter(), and ripoffline().) This determines the
terminal type and initializes all curses data
structures. initscr() also arranges that the
first call to wrefresh() clears the screen. If
errors occur, initscr() writes an appropriate
error message to standard error and exit; other-
wise, a pointer to stdscr is returned. If the
program wants an indication of error conditions,
newterm() should be used instead of initscr().
initscr() should only be called once per appli-
cation.
endwin()
A program should always call endwin() before
exiting or escaping from curses mode temporar-
ily, to do a shell escape or system(3S) call.
This routine restores tty(7) modes, moves the
cursor to the lower-left corner of the screen
and resets the terminal into the proper non-
visual mode. To resume after a temporary escape,
call wrefresh() or doupdate().
isendwin()
Returns TRUE if endwin() was 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 can 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 SCREEN-type
SUPER-UX Last change: May 16, 1997 8
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
variable that should be saved as a reference to
that terminal. The arguments are the terminal
type 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 rou-
tine. This is the only routine that 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 rou-
tines merely manipulate data structures. wre-
fresh() copies the named window to the physical
terminal screen, taking into account what is
already there in order to minimize the amount of
information sent to the terminal (called opti-
mization).
refresh() does the same thing, except it uses
stdscr as a default window. Unless leaveok() was
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. refresh() is a macro.
wnoutrefresh(win)
doupdate()
These two routines allow multiple updates to the
physical doupdate() 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
SUPER-UX Last change: May 16, 1997 9
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
programmer wants to have on the screen. wre-
fresh() works by first calling wnoutrefresh(),
which copies the named window to the virtual
screen, and then by calling doupdate(), that
compares the virtual screen to the physical
screen and does the actual update. If the pro-
grammer wishes to output several windows at
once, a series of calls to wrefresh() result in
alternating calls to wnoutrefresh() and doup-
date(), 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)
Creates and returns 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 are 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)
Moves the window so that the upper-left corner
is 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)
Creates and returns a pointer to a new window
with the given number of lines or rows nlines,
and columns ncols. The window is at the begin_y,
begin_x position 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
affect both windows. To change the image of one
part of the window, it is necessary to call
touchwin() or touchline() in orig before calling
wrefresh() in orig.
delwin(win)
Deletes the named window, freeing up all memory
associated with it. Trying to cancel the main
window before all parts of the window causes an
ERR to be returned.
WINDOW *newpad(nlines, ncols)
Creates and returns a pointer to a new pad data
structure with the given number of lines or rows
SUPER-UX Last change: May 16, 1997 10
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
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 is on the screen at one time. Automatic
refreshes of pads (from scrolling or echoing of
input) do not occur. It is not legal to call
wrefresh() with a pad as an argument; the pre-
fresh() or pnoutrefresh() routines should be
called instead.
NOTE
These routines require additional parameters to
specify the part of the pad to display and the loca-
tion on the screen to use for display.
WINDOW *subpad(orig, nlines, ncols, begin_y, begin_x)
Creates and returns a pointer to a sub-window
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
the (begin_y, begin_x) position on the pad. The
window is made in the middle of the window orig,
so that changes made to one window affect both
windows. To change the image of one part of the
window, it is necessary to call touchwin() or
touchline() in orig before calling prefresh() in
orig.
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 win-
dows, 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 rectan-
gle to be displayed. sminrow, smincol, smaxrow,
and smaxcol specify the edges on the screen of
the rectangle in which to be displayed. 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 con-
tained within their respective structures. Nega-
tive values of pminrow, pmincol, sminrow, or
smincol are treated as if they were zero.
Output
These routines are used for treating the text in
SUPER-UX Last change: May 16, 1997 11
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
window.
addch(ch)
waddch(win, ch)
mvaddch(y, x, ch)
mvwaddch(win, y, x, ch)
The ch character 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). An automatic new line is performed at
the right margin. At the bottom of the scrolling
region, if scrollok() is enabled, the scrolling
region is scrolled up one line.
If ch is a tab, new line, or back space, the
cursor is moved appropriately within the window.
A new line also does a wclrtoeol() before mov-
ing. Tabs are considered to be at every eighth
column. If ch is another control character, it
is drawn with "^X" notation. (Calling winch()
after adding a control character does not return
the control character, but instead returns the
representation of the control character.)
Video attributes can be combined with a charac-
ter by OR-ing them into the parameter. This
results in these attributes also being set.
(The intent here is that text, including
attributes, can be copied from one place to
another using winch() and waddch().) See wstand-
out() described later.
NOTE
ch is actually a chtype, not a character. 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 wad-
dch(pad, ch) followed by a call to pre-
fresh(pad). The knowledge that only a single
character is being output is taken into consid-
eration and, for non-control characters, a sig-
nificant performance gain can be seen by using
these routines instead of their equivalents. In
the case of pechochar(), the last location of
SUPER-UX Last change: May 16, 1997 12
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
the pad on the screen is reused for the argu-
ments to prefresh(). 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 wad-
dch() once for each character in the string.
attroff(attrs)
wattroff(win, attrs)
attron(attrs)
wattron(win, attrs)
attrset(attrs)
wattrset(win, attrs)
standend()
wstandend(win)
stantout()
wstantout(win)
These routines manipulate current attributes of
the named window. These attributes can be any
combination of A_STANDOUT, A_REVERSE, A_BOLD,
A_DIM,ABINK, 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 win-
dow with waddch(). Attributes are property of
the character and move with the character
through any scrolling and insert/delete
line/character operations. To the extent possi-
ble on a terminal, they are 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 named attributes without turn-
ing off others. wattron(win, attrs) turns on
attributes without affecting others. wstand-
out(win) is the same as wattron(win,
A_STANDOUT). wstandend(win) is the same as wat-
trset(win, 0) -- it turns off all attributes.
wattroff(), wattron(), wattrset(), wstandend(),
and wstandout() usually return 1.
attrs is actually a chtype, not a character.
SUPER-UX Last change: May 16, 1997 13
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
attroff(), attron(), attrset(), standend(), and
standout() are macros.
beep()
flash()
These routines are used to signal the terminal
user. beep() sounds an audible alarm on the ter-
minal or flashes a visible bell. flash() flashes
the screen or sounds an audible signal. If nei-
ther signal is possible, nothing happens. Nearly
all terminals have an audible or visible signal.
box(win, vertch, horch)
Draws a box around a window. vertch and horch
are characters that draw the box. If they are 0,
the appropriate default characters ACS_VLINE and
ACS_HLINE are used.
vertch and horch are chtype, not characters.
erase()
werase(win)
These routines copy blanks to every position in
the window. erase() is a macro.
clear()
wclear(win)
These routines are like erase and werase but
they also call clearok(), clearing the screen
completely on the next call to wrefresh() for
that window, and repaint it.
clrtobot()
wclrtobot(win)
Erases all lines below the cursor in a window.
Also, the current line to the right of the cur-
sor is erased. clrtobot is a macro.
clrtoeol()
wclrtoeol(win)
Erases the current line to the right of the cur-
sor. clrtoeol is a macro.
delay_output(ms)
Inserts a millisecond pause in the output. It is
not recommended to use this routine often
because padding characters are used rather than
a processor pause.
delch()
wdelch(win)
mvdelch(y, x)
SUPER-UX Last change: May 16, 1997 14
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
mvwdelch(win, y, x)
Deletes the character under the cursor in the
window. 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 the use of the hardware "delete-character"
feature. delch(), mvdelch(), and mvwdelch() are
macros.
deleteln()
wdeleteln(win)
Deletes the line under the cursor in the window.
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. deleteln() is a macro.
getyx(win, y, x)
Places the cursor position of the window in two
integer variables. This is implemented as a
macro, so an ampersand (&) is necessary before
the variables.
getbegyx(win, y, x)
getmaxyx(win, y, x)
Like getyx(), these routines store the current
beginning corrdinates and size of the specified
window. They are macros.
insch(ch)
winsch(win, ch)
wvwinsch(win, y, x, ch)
mvinsch(y, x, ch)
Inserts the ch character before the character
under the cursor. All characters to the right
are moved one space to the right, possibly los-
ing the rightmost character of the line. The
cursor position does not change after moving to
(y, x), if specified. This does not imply the
use of the hardware "insert-character" feature.
ch is actually a chtype, not a character.
insch(), mvinsch(), and mvwinsch() are macros.
insertln()
winsertln(win)
Inserts a blank line above the current line and
the bottom line is lost. This does not imply
the use of the hardware "insert-line" feature.
insertln() is a macro.
move(y, x)
SUPER-UX Last change: May 16, 1997 15
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
wmove(win, y, x)
Moves the cursor associated with the window 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 (0,0).
move() is a macro.
overlay(srcwin, dstwin)
overwrite(srcwin, dstwin)
These routines overaly srcwin on top of dstwin;
that is, all text in srcwin is copied into dst-
win. They need not be the same size window; only
text where the two windows overlap is copied.
The difference is that overlay() is non-
destructive (blanks are not copied), while over-
write() is.
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 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, copying is non-destructive, as in over-
lay().
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 that is output by printf(3) is instead
output using waddstr() in a window.
vwprintw(win, fmt, varglist)
This routine corresponds to vfprintf(3S). It
performs a wprintw() using a variable argument
list. The third argument is va_list, a pointer
to a list of arguments, as defined in varargs.h.
See vprintf(3S) and varargs(5) manual pages for
a detailed description on how to use variable
argument lists.
scroll(win)
Scrolls the window up one line. This involves
moving the lines in the window data structure.
touchwin(win)
touchline(win, start, count)
Throws away all optimization information about
SUPER-UX Last change: May 16, 1997 16
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
which parts of the window have been touched by
pretending that the entire window has been drawn
on. This is sometimes necessary when using over-
lapping windows, since a change to one window
affects the other window, but the records of
which lines have been changed in the other win-
dow do not reflect the change. touchline() only
pretends that count line has been changed,
beginning with the start line.
Input
getch()
wgetch(win)
mvgetch(y, x)
mvwgetch(win, y, x)
Reads a character 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 hangs until the system
passes text through to the program. Depending on
the setting of cbreak(), this is after one char-
acter (CBREAK mode) or after the first new line
(NOCBREAK mode). In HALF-DELAY mode, the program
hangs until the character is typed or the speci-
fied time-out is reached. Unless noecho() is
set, the character is also echoed into a window.
When wgetch() is called, if some parts of the
window are changed (moving the cursor or chang-
ing text), call wrefresh() before obtaining the
character.
When using getch(), wgetch(), mvgetch(), or
mvwgetch(), do not set both NOBREAK 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
can produce some undesirable results.
If keypad(win, TRUE) is called and a function
key pressed, the token for that function is
returned instead of raw characters. (See key-
pad() under "Input Option Settings.") Possible
function keys are defined in curses.h with inte-
gers beginning with 0401, whose names begin with
KEY_. If a character is received that could be
the beginning of a function (such as esape),
curses sets a timer. If the remainder of the
sequence is not received within the designated
time, the character is passed through, otherwise
the function key value is returned. For this
reason, on many terminals there is a delay after
a user presses Esc because a single-character
routine is discouraged. See notimeout()
SUPER-UX Last change: May 16, 1997 17
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
described later. getch(), mvgetch(), and
mvwgetch() are macros.
getstr(str)
wgetstr(win, str)
mvgetstr(y, x, str)
mvwgetstr(win, y, x, str)
A series of calls to wgetch() is made until a
new line, Return, or Enter key is received. The
resulting value is placed in the area pointed to
by the character pointer str. The user's erase
and kill characters are interpreted. getstr(),
mvgetstr(), and mvwgetstr() are macros.
ungetch(c)
Places c back onto the input queue to be
returned by the next call to wgetch().
flushinp()
Throws away any typeahead that was typed by the
user and has not yet been read by the program.
flushinp() does not abandon any character given
by ungetch().
inch()
winch(win)
mvinch(y, x)
mvwinch(win, y, x)
Returns the character chtype at the current
position in a window. If any attributes are set
for that position, their values are OR-ed into
the value returned. The predefined constants
A_CHARTEXT and A_ATTRIBUTES, defined in
curses.h, can be used with the C logical AND (&)
operator to extract the character or attributes
alone. 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 a window and the resulting line is
used as input for the scan. The returned value
of these functions is the number of the conver-
sion argument by fmt; the arguments that are not
converted are lost.
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
SUPER-UX Last change: May 16, 1997 18
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
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 vari-
able argument lists.
Output Option Settings
These routines set options within curses that deal with out-
put. All options are initially FALSE, unless otherwise
stated. It is not necessary to turn these options off before
calling endwin().
clearok(win, bf)
If enabled (bf is TRUE), the next call to wre-
fresh() with this window clears the screen com-
pletely and redraws the entire screen. 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 considers using
the hardware "insert/delete line" feature of
terminals so equipped. If disabled (bf is
FALSE), curses seldom uses this feature,
although it is always considered. This option
should be enabled only if an application needs
an insert/delete line, i.e., for a screen edi-
tor. It is disabled by default because this fea-
ture tends to be visually annoying when used in
applications where it is not required. If
"insert/delete line" cannot be used, curses
redraws the changed portion of all lines. By not
calling idlok(), approximately 5,000 bytes of
memory are saved.
leaveok(win, bf)
The hardware cursor is usually left at the loca-
tion of the window cursor being refreshed. This
option allows the cursor to be left wherever the
update happens to leave it. It is useful for
applications where the cursor is not used, since
it reduces the need for cursor motions. If pos-
sible, 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 in
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
SUPER-UX Last change: May 16, 1997 19
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
margin line causes all lines in the scrolling
region to scroll up one line. This has nothing
to do with the 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 are probably used by out-
put routines. setscrreg() is a macro.
scrollok(win, bf)
This option controls what happens when the cur-
sor of a window is moved off the edge of the
window or scrolling region, either from a new
line 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 the physical terminal
and window are scrolled up one line. In order to
get the physical scrolling effect on the termi-
nal, it is also necessary to call idlok().
scrollok() usually returns OK.
Input Option Settings
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().
See the SUPER-UX Programmer's Guide for more information on
these options.
cbreak()
nocbreak()
These routines put the terminal into and out of
CBREAK mode. In CBREAK mode, characters typed by
the user are immediately available to the pro-
gram and erase/kill character processing is not
performed. When in NOCBREAK mode, the tty driver
buffers characters typed until a new line or
Return is entered. 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 set CBREAK mode.
cbreak() is the subset of the raw() function.
This can be said to be the middle of NOCBREAK
mode and RAW mode. See wgetch() under "Input"
for a discussion of how these routines interact
SUPER-UX Last change: May 16, 1997 20
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
with echo() and noecho().
echo()
noecho()
These routines control whether charactes typed
by the user are echoed by wgetch() as they are
typed. Echoing by the tty driver is always dis-
abled, 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().
halfdelay(tenths)
Half-delay mode is similar to CBREAK mode in
that characters typed by the user are immedi-
ately available to the program. However, after
blocking for tenths of seconds, ERRO is returned
if nothing is typed. tenths must be between 1
and 255. Use nocbreak() to leave half-delay
mode.
nl()
nonl()
These functions control whether or not conver-
sion returns to new line during input time
according to wgetch(). At the early state,
returns are converted to new line, which cancels
the conversion. There is no conversion by the
tty(7) driver in CBREAK mode.
intrflush(win, bf)
If this option is enabled, an interrupt key is
pressed on the keyboard (interrupt, break,
quit). All output in the tty driver queue is
flushed, giving the effect of faster response to
the interrupt, but causing curses to have the
wrong idea of what is on the screen. Disabling
the option prevents the flush. The default for
the option is inherited from the tty driver set-
tings. The window argument is ignored.
keypad(win, bf)
This option enables the keypad of the user's
terminal. If enabled, the user can press a func-
tion key (such as an arrow) and wgetch() returns
a single value representing the function, as in
KEY_LEFT. If disabled, curses does 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
SUPER-UX Last change: May 16, 1997 21
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
(made to transmit), the keypad(win, TRUE) call
switches it on.
meta(win, bf)
During the initial state, the terminal returns 7
or 8 bits during input time by following the
control mode of the tty driver. See termio(7).
To return 8 bits, call meta(win, TRUE). To
return 7 bits, specify FALSE. win is usually
ignored. If the smm (meta_on) and rmm (meta_off)
of terminfo(4) function is defined by the termi-
nal, smm is sent to the terminal if TRUE is set,
and rmm is sent if FALSE is.
nodelay(win, bf)
This option causes wgetch() to be a non-blocking
call. If no input is ready, wgetch() returns
ERR. If disabled, wgetch() hangs until a key is
pressed.
notimeout(win, bf)
While intrepreting an input-escape sequence,
wgetch() sets a timer while waiting for the next
character. If notimeout(win, TRUE) is called,
wgetch() does 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.
This 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 unin-
terpreted, instead of generating a signal. 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 look-
ing for typeahead periodically while updating
the screen. If input is found, and it is coming
from a tty, the current update is postponed
until wrefresh() or doupdate() are called again.
This allows faster response to commands typed in
advance. Usually, the file descriptor for the
input FILE pointer passed to newterm(), or stdin
if initscr() is used, do this typeahead check-
ing. The typeahead() routine specifies that the
file descriptor fildes is to be used to check
for typeahead instead. If fildes is -1, no
SUPER-UX Last change: May 16, 1997 22
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
typeahead checking is done. 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 exam-
ple 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 scroll
regions. This might be used to turn on physical
scrolling with 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 set_term(), so
the value should be saved between calls to
newterm() if longname() is used with multiple
terminals.
Soft Labels
If desired, curses manipulates the set of soft, function-key
labels that exist on many terminals. For those terminals
that do not have soft labels, to simulate them, curses takes
over the bottom line of stdscr, reducing the size of it and
the variable LINES. curses standardizes on eight labels of
eight characters each.
If the curses program changes the value of the soft levels,
only the optional establishment of the terminal is recov-
ered. As a result, if the user changes the value of the soft
labels before calling curses, that value is not re-
established when terminating curses.
slk_init(labfmt)
To use soft labels, call this routine before
SUPER-UX Last change: May 16, 1997 23
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
initscr() or newterm(). If initscr() winds up
using a line from stdscr to emulate soft labels,
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 on the label of up to eight charac-
ters. A NULL string or pointer puts up a blank
label. labfmt is one of 0, 1, or 2 to indicate
the label as left justified, centered, or right-
justified.
slk_refresh()
slk_noutrefresh()
These routines correspond to wrefresh() and
wnoutrefresh(). Most applications use
slk_noutrefresh() because wrefresh() usually
follows.
char *slk_label(labnum)
Returns the current label of labnum, which has
the same format at the time when slk_set() is
delivered. In other words, it is the format fol-
lowing the labfmt argument to slk_set().
slk_clear()
Clears soft labels from the screen.
slk_restore()
Restores soft labels to the screen after a
slk_clear().
slk_touch()
Outputs all the soft labels the next time a
slk_noutrefresh() occurs.
Low-Level curses Access
The following routines give low-level access to various
curses functionality. The routines are typically used inside
library routines.
def_prog_mode()
def_shell_mode()
Saves the current terminal modes as a "program"
(in curses) or "shell" (not curses) state for
use by reset_prog_mode() and reset_shell_mode().
This is done automatically by initscr().
reset_prog_mode()
reset_shell_mode()
Restores the terminal to a "program" in curses
SUPER-UX Last change: May 16, 1997 24
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
or "shell" out of curses state. These are done
automatically by endwin() and doupdate() after
an endwin(), so they are not usually 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 restty()
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 do not take an ampersand (&)
before them. If leaveok() is currently TRUE, -1
is returned. If the lines from the uppermost
area of the screen are erased with ripoffline(),
the variables are included. As a result, y and x
should be used as the argument of setsyx(). get-
syx is a macro.
setsyx(y, x)
The virtual screen cursor is set to y, x. If
they are both -1, leaveok() is set. getsyx() and
setsyx() are designed for a library routine that
manipulates curses windows but does not want to
disturb the current position of the program's
cursor. The library routine calls getsyx() at
the beginning, does its manipulation of its win-
dows, does a wnoutrefresh() on them, then calls
setsyx() and doupdate().
ripoffline(line, init)
This routine provides access to the same facil-
ity that slk_init() uses to reduce the size of
the screen. ripoffline() must be called before
initscr() or newterm(). If line is positive, a
line is removed from the top of stdscr; if nega-
tive, it is removed from the bottom. When this
is done inside initscr(), the init() routine is
called with two arguments: a window pointer to
the 1-line window that is allocated, and an
integer with the number of columns in the win-
dow. 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 allowed to call wnoutrefresh() during the
initialization routine.
ripoffline() can be called up to five times
before initscr() or newterm().
SUPER-UX Last change: May 16, 1997 25
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
scr_dump(filename)
Writes the current contents of the virtual
screen to filename.
scr_restore(filename)
Sets the virtual screen to the contents of file-
name, which must have been written using
scr_dump(). If the contents and the current
curses are incompatible, ERR is returned. The
next call to doupdate() restores the screen to
what it looked like in the dump file.
scr_init(filename)
Reads in the contents of filename and uses it to
initialize curses data structures about what the
terminal currently has on screen. If the data is
valid, curses bases its next screen update 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 that has
done a scr_dump() after its endwin(). The data
is declared invalid if the time-stamp of the tty
is old or the terminfo(4) capability nrrmc is
TRUE.
keypad(), meta(), slk_clear(), curs_set(),
flash(), and beep make the time-stamp of tty old
without affecting the screen.
curs_set(visibility)
Sets the cursor to invisible(0), normal(1), or
very visible(2).
draino(ms)
Waits until the output has drained enough that
it only takes ms to drain completely.
garbagedlines(win, begline, numlines)
This routine indicates to curses that a screen
line is garbage and should be thrown away before
having anything written over it. It can be used
for editor programs that want a command to
redraw a single line. It could be used in cases
where there is a noisy communications line and
redrawing the entire screen is unnecessary.
Redrawing a single line gives some semblance of
hope that it shows up unblemished. The current
window location is used to determine the lines
to be redrawn.
napms(ms)
Sleeps for ms milliseconds.
SUPER-UX Last change: May 16, 1997 26
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
mvcur(oldrow, oldcol, newrow, newcol)
The cursor operation of the lower label.
Terminfo-Level Manipulations
These low-level routines must be called by programs that
need to deal directly with the terminfo(4) data base to han-
dle certain terminal capabilities such as function-key pro-
gramming. For other functionality, curses routines are more
suitable and recommended.
Initially, setupterm() should be called. setupterm() is
automatically called by initscr() and newterm(). This
defines the set of terminal-dependent variables defined in
the terminfo(4) data base. The terminfo(4) variables lines
and columns are initialized by setupterm() as follows. If
the environment variables LINES and COLUMNS exist, their
values are used. Otherwise, the values for lines and
columns in the terminfo(4) data base are used.
The curses.h and term.h header files should be included, in
this order, to get the definitions of these strings, num-
bers, 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 that use
cursor addressing should output enter_ca_mode upon startup
and should output exit_ca_mode before exiting. See ter-
minfo(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. This is
different from curses routines. See endwin().
setupterm(term, fildes, erret)
Reads in the terminfo(4) data base, initializing
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 is used. All output goes to the file
descriptor, fildes. If erret is not NULL,
setupterm() returns OK or ERR and stores a sta-
tus value in the integer pointer to by erret. A
1 status in erret is normal; 0 means that the
terminal could not be found, and -1 means that
the terminfo(4) data base could not be found. If
erret is NULL, setupterm() prints an error mes-
sage upon finding an error and exits. Thus, the
simplest call is
setupterm((char *)0,1,(int *)0)
that uses all the defaults.
SUPER-UX Last change: May 16, 1997 27
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
The terminfo(4) boolean, numeric, and string
variables are stored in a TERMINAL structure
type. After setupterm() returns successfully,
the cur_term variable (TERMINAL * type) is
intialized with all the information to which the
terminfo(4) boolean, numeric, and string vari-
ables point to. The pointer can be saved before
calling setupterm() again. Further calls to
setupterm() allocate new space rather than reuse
the space pointed to by cur_term.
set_curterm(nterm)
nterm is a TERMINAL * type. set_curterm() sets
the cur_term to nterm, and makes all the ter-
minfo(4) boolean, numeric, and string variables
use the values from nterm.
del_curterm(oterm)
oterm is a TERMINAL * type. del_curterm() frees
space pointed to by oterm and makes it available
for further use. If oterm is the same as
cur_term, references to any terminfo(4) boolean,
numeric, and string variables thereafter can
refer to invalid memory locations until another
setupterm() is called.
restartterm(term, fildes, erret)
Like setupterm() after a memory restore.
char *tparm(str, p1, p2, ...p9)
Instantiates str with parms pi. A pointer is
returned to the result of str with the parame-
ters applied.
tputs(str, count, putc)
Applies padding to str and outputs 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 characters are
passed one at a time.
putp(str)
A routine that calls tputs(str, 1, putchar()).
vidputs(attrs, putc)
Outputs a string that puts the terminal in the
video attribute mode attrs, which is any combi-
nation of the following attributes. The charac-
ters are passed to the putchar(3S)-like routine
putc().
SUPER-UX Last change: May 16, 1997 28
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
vidattr(attrs)
Like vidputs(), except that it outputs through
putchar(3S).
mvcur(oldrow, oldcol, newrow, newcol)
Low-level cursor motion.
The following functions transfer a character string that
includes the capname of terminfo(4) and returns the value of
that corresponding function. For example, rc = tiget-
str(acsc) is the value of acsc returned to rc.
tigetflag(capname)
The value of -1 returned if capname is not a
boolean capability. When capname does not
define this terminal, it returns a 0 value.
tigetnum(capname)
The value of -2 is returned if capname is not a
numeric capability. When capname does not
define this terminal, it returns a -1 value.
tigetstr(capname)
The value (char *) -1 is returned if capname is
not a string capability. When capname does not
define this terminal, it returns a NULL value.
char *boolnames[], *boolcodes[], *boolfnames[]
char *numnames[], *numcodes[], *numfnames[]
char *strnames[], *strcodes[], *strfnames[]
These NULL-terminated arrays contain the cap-
name, termcap, and full C names for each of the
terminfo(4) variables.
Termcap Emulation
These routines are included as a conversion aid for programs
that use the termcap library. Their parameters are the same
and the routines are emulated using the terminfo(4) data
base.
tgetent(bp, name)
Looks up the termcap entry for name. The emula-
tion ignores the buffer pointer bp.
tgetflag(codename)
Gets the boolean entry for codename.
tgetnum(codes)
Gets the numeric entry for codename.
char *tgetstr(codename, area)
Returns the string entry for codename. If area
is not NULL, it also stores it in the buffer
pointed to by area and advance area. tputs()
SUPER-UX Last change: May 16, 1997 29
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
should be used to output the returned string.
char *tgoto(cap, col, row)
Instantiates the parameters into the given capa-
bility. The output from this routine is passed
to tputs().
tputs(str, affcnt, putc)
See tputs() previously mentioned in "terminfo-
Level Manipulations."
Miscellaneous
traceon()
Turn debugging trace output off and on when
using the debug version of the curses library,
/usr/lib/libdcurses.a. This facility is avail-
able only to customers with source licenses.
unctrl(c)
This macro expands to a character string that is
a printable representation of the c character.
Control characters are displayed in ^X notation.
Printing characters are displayed as is.
unctrl() is defined in unctrl.h, which curses.h
automatically includes.
char *keyname(c)
Returns a character string corresponding to the
c key.
filter()
This routine is one of the few that is called
before initscr() or newterm(). It arranges
things so that curses thinks that there is a
1-line screen. curses does not use any terminal
capabilities that assume they know what line on
the screen the cursor is on.
Using curscr
The special window curscr can be used in a few routines. If
the window argument to clearok() is curscr, the next call to
wrefresh() with any window causes the screen to be cleared
and repainted from scratch. If the window arguement to wre-
fresh() is curscr, the screen is immediately cleared and
repainted. (This is how most programs would implement a
"repaint screen" routine.) The source window argument to
overlay(), overwrite(), and copywin() can be curscr, in
which case the current contents of the virtual terminal
screen are accessed.
Obsolete Calls
Various routines are provided to maintain compatibility in
programs written for older versions of the curses library.
SUPER-UX Last change: May 16, 1997 30
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
These routines are all emulated as follows.
Routine Replaced by
crmode() cbreak()
fixterm() reset_prog_mode()
gettmode() A no-op
nocrmode() nocbreak()
resetterm() reset_shell_mode()
saveterm() def_prog_mode()
setterm() setupterm()
ATTRIBUTES
The following video attributes, defined in curses.h, can be
passed to the wattron(), wattroff(), and wattrset() rou-
tines, or OR-ed with the characters passed to waddch().
Attribute Name Video Attribute Affect
A_STANDOUT Highlight mode
A_UNDERLINE Underline
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 (also
described under winch())
A_NORMAL Bit mask to reset all attributes off
(for example, wattrset(win,
A_NORMAL)
FUNCTION KEYS
The following function keys, defined in curses.h, might be
returned by wgetch() if keypad() is enabled. Not all these
can be supported on a terminal if it does not transmit a
unique code when a key is pressed, or the definition for the
key is not present in the terminfo(4) data base.
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.
64 spaces for function keys reserved
KEY_F(n) (KEY_F0+(n)) Formula for fn.
SUPER-UX Last change: May 16, 1997 31
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
KEY_DL 0510 Delete line
KEY_IL 0511 Insert line
KEY_DC 0512 Delete character
KEY_IC 0513 Insert char or enter insert mode
KEY_EIC 0514 Exit insert char mode
KEY_CLEAR 0515 Clear screen
KEY_EOS 0516 Clear to end of screen
KEY_EOL 0517 Clear to end of line
KEY_SF 0520 Scroll 1 line forward
KEY_SR 0521 Scroll 1 line backwards
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 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
SUPER-UX Last change: May 16, 1997 32
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
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 character listed as fol-
lows is 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
SUPER-UX Last change: May 16, 1997 33
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
ACS_S9 _ scan line 9
ACS_DIAMOND + diamond
ACS_CKBOARD : checker board (stipple)
ACS_DEGREE ' degree symbol
ACS_PLMINUS # plus/minus
ACS_BULLET o bullet
ACS_LARROW < arrow pointing left
ACS_RARROW > arrow pointing right
ACS_DARROW v arrow pointing down
ACS_UARROW ^ arrow pointing up
ACS_BOARD # board of squares
ACS_LANTERN # lantern symbol
ACS_BLOCK # solid square block
RETURN VALUE
All routines return the integer OK upon successful comple-
tion and the integer ERR upon failure, unless otherwise
noted in preceding routine descriptions.
All macros return the value of their w version, except get-
syx(), getbegyx(), and getmaxyz(). For these macros, no
useful value is returned.
Routines that return pointers always return (type *) NULL on
error.
SEE ALSO
cc(1), ld(1), ioctl(2), profile(4), term(4), terminfo(4),
varargs(5), termio(7), tty(7), putc(3S), scanf(3S),
stdio(3S), system(3S), vprintf(3S).
WARNINGS
The plotting library plot(3X) and the curses library
curses(3X) both use the names erase() and move(). The curses
versions are macros. If users need both libraries, put the
plot(3X) code in a different source file from the curses(3X)
code; and/or #undef move() and erase() in the plot(3X) code.
Between the time a call to initscr() and endwin() is issued,
use only the routines in the curses library to generate out-
put. Using system calls or the "standard I/O package" for
output during that time can cause unpredictable results. See
stdio(3S).
When the pointer that is transferred to the functions as a
window argument is NULL or exceeds the range, the result is
not guaranteed. (There are cases of core dumps).
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() was called
at least once. This is changed when proper kernel support is
SUPER-UX Last change: May 16, 1997 34
CURSES(3X) MISCELLANEOUS LIBRARY FUNCTIONS CURSES(3X)
available. Programs that use a mixture of their own input
routines with curses input routines may wish to call typea-
head(-1) to turn off typeahead checking.
The argument to napms() is currently rounded up to the near-
est second.
draino(ms) only works for ms equal to 0.
SUPER-UX Last change: May 16, 1997 35
G1AB02E Programmer's Reference Manual