curses(3) CLIX curses(3)
NAME
curses - Terminal screen handling and optimization package
LIBRARY
Curses Library (libcurses.a)
SYNOPSIS
The following provides a list of curses() library functions along with
their associate nonglobal parameters. Unless otherwise noted, these
functions return the int values of ERR or OK. The functions that return
pointers always return NULL if an error occurs. The ERR, OK, and NULL are
defined in <curses.h>.
#include <curses.h> (automatically includes <stdio.h>, <termio.h>, and
<unctrl.h>).
bool bf
char **area, *boolnames[], *boolcodes[], *boolfnames[], *bp
char *cap, *capname, codename[2], erasechar, *filename, *fmt
char *keyname, killchar, *label, *longname
char *name, *numnames[], *numcodes[], *numfnames[]
char *slk_label, *str, *strnames[], *strcodes[], *strfnames[]
char *term, *tgetstr, *tigetstr, *tgoto, *tparm, *type
chtype attrs, ch, horch, vertch
FILE *infd, *outfd
int begin_x, begin_y, begline, bot, c, col, count
int dmaxcol, dmaxrow, dmincol, dminrow, *errret, fildes
int (*init()), labfmt, labnum, line
int ms, ncols, new, newcol, newrow, nlines, numlines
int oldcol, oldrow, overlay
int p1, p2, p9, pmincol, pminrow, (*putc()), row
int smaxcol, smaxrow, smincol, sminrow, start
2/94 - Intergraph Corporation 1
curses(3) CLIX curses(3)
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)
2 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
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()
2/94 - Intergraph Corporation 3
curses(3) CLIX curses(3)
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)
4 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
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()
2/94 - Intergraph Corporation 5
curses(3) CLIX curses(3)
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()
6 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
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)
timeout(delay)
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)
2/94 - Intergraph Corporation 7
curses(3) CLIX curses(3)
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)
wtimeout(win, delay)
PARAMETERS
See the SYNOPSIS section. The parameters are located next to their
8 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
associate library function(s) which use them.
DESCRIPTION
This descriptive section is explained within the context of the following
subsections:
⊕ General
⊕ Functions
⊕ Attributes
⊕ Function Keys
⊕ Line Graphics
General
The curses() function provides the user with a terminal-independent method
of updating screens with reasonable optimization. To initialize the
function properly, enter:
#include <curses.h>
at the beginning of all files that use curses() functions. In addition,
the function initscr() or newterm() must be called before any window or
screen functions are used. (Three exceptions are noted where they apply.)
The endwin() function must be called before exiting. To get character-
at-a-time input without echoing-most interactive, screen-oriented programs
utilize this method-the user may, after invoking initscr(), call cbreak();
noecho(). Most programs also call: nonl(); intrflush(stdscr, FALSE;
keypad(stdscr, TRUE).
Before a curses() program is run, the 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(),
tput(), and the subsection Tabs and Initialization, of terminfo().
The curses() library contains functions that manipulate data structures
called windows that can be thought of as two-dimensional arrays of
characters representing all or part of a terminal screen. A default
window called stdscr is supplied, which is the size of the terminal
screen. Others may be created with the newwin() function. Windows are
referred to by variables declared as WINDOW*; the type WINDOW is defined
in <curses.h> to be a structure.
These data structures are manipulated with the functions described below.
The most basic of these functions are move() and addch(). Generic
2/94 - Intergraph Corporation 9
curses(3) CLIX curses(3)
versions of these functions are included and are easily recognizable by
having names beginning with w. These functions allow the user to specify
a window. The functions not beginning with w usually affect the standard
screen (stdscr()).
The refresh() function is called to instruct related functions to make the
user's terminal screen look like a standard screen (stdsc()). The
characters in a window are actually a part of the chtype() function 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. For more information 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, the
curses() function 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
⊕ KEY_LEFT
The curses() function also defines the WINDOW* variable and the curscr
variable which is only used for certain low-level operations like clearing
and redrawing a garbaged screen. This variable, curscr, when used with
the window argument clearok and the next call to wrefresh() inside any
window, causes the screen to be cleared and redrawn from scratch. In
addition, if curscr is the window argument to wrefresh(), the screen is
also immediately cleared and redrawn from scratch. This is the standard
program procedure for implementing a repaint-screen function. More
information on using the curscr variable is provided where appropriate.
The environment variables LINES and COLUMNS may be set to override the
specifications for the size of the screen stipulated in TERMINFO. These
may be used in conjunction with terminals which permit the user to change
the size of the screen.
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 environment variable TERM is set to
att4425, then the compiled terminal definition is found in
10 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
/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 OME/myterms, the curses() function first
checks OME/myterms/a/att4425. If that fails, curses() 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 the initscr() function 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 functions to indicate whether the
process successfully completed. These constants are also defined in
<curses.h>.
Functions
This subsection provides a description of curses() functions grouped
within the following activities:
⊕ General
⊕ 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()
2/94 - Intergraph Corporation 11
curses(3) CLIX curses(3)
⊕ Obsolete Calls
General
Many of the following functions have two or more versions. Functions
prefixed with w require a window argument. Functions prefixed with p
require a pad argument. Those without a prefix generally use stdscr.
The functions prefixed with mv require y and x coordinates in order to
perform the appropriate action. The mv() functions imply a call to move()
before the call to the other function. (The window argument is always
specified before the coordinates.) The y coordinate always refers to the
row (of the window), and x always refers to the column. The upper left
corner is always line/column (0, 0), not (1, 1).
Functions 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. The
win and pad arguments are always a type of WINDOW*. Option-setting
functions require a boolean flag (bf) with the value TRUE or FALSE. (The
bf argument is always a type of bool.) The types WINDOW bool and chtype
are defined in <curses.h>. See SYNOPSIS for a summary of variable types.
Unless other wise noted, functions return either the integer ERR or the
integer OK. Functions returning pointers always return NULL on error.
Sometimes a function description refers to a second function. If the
function referred to is prefixed with a w, then assume that other versions
of the second function behave similarly. For example, the description of
initscr() refers to wrefresh(). This implies that the same result occurs
if refresh() is called.
Overall Screen Manipulation
WINDOW *initscr()
The first function called should almost always be initscr(). (The
exceptions are slk_init(), filter(), and ripoffline().) The
initscr() function determines the terminal type and initializes all
curses() data structures. The initscr() function also arranges
that the first call to wrefresh() clears the screen. If errors
occur, the initscr() function writes an appropriate error message
to stderr and exit. If no errors occur, a pointer to stdscr is
returned. If the program needs an indication of error conditions,
the newterm() function should be used instead of initscr(). The
initscr() function should be called only once per application.
endwin()
The endwin() program should always be called before exiting or
escaping from the curses() utility program either temporarily as
well as executing a momentary shell escape. This function restores
12 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
tty() modes, moves the cursor to the lower left corner of the
screen and resets the terminal into the proper nonvisual mode. To
resume after a temporary escape, use the wrefresh() or doupdate()
command.
isendwin()
The isendwin() function returns a TRUE value if endwin() has been
called without any subsequent calls to wrefresh().
SCREEN *newterm(type, outfd, infd)
The newterm() function is used when output must be sent to more
than one terminal instead of using initscr(), which is used
primarily for individual terminals. This function is also used for
programs which need an indication of error conditions in order to
run in a line-oriented mode (that is, especially, if the terminal
cannot support a screen-oriented program). The newterm() function
should be called once for each terminal. It returns a variable
indicating the type SCREEN() (This information should be saved for
future reference. The following defines the valid arguments for
newterm():
type The type of the terminal to be used in place of the
environment variable TERM.
outfd A stdio() file pointer for output to the terminal.
infd Another file pointer for input from the terminal.
When the program has finished running, it 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 the endwin() is called.
SCREEN *set_term(new)
The set_term() function is used to switch between different
terminals. The screen variable new indicates the new current
terminal. A pointer to the screen of the previous terminal is
returned by the function. Only this function manipulates SCREEN
pointers. Other functions affect only the current terminal.
Window and Pad Manipulation
refresh()
wrefresh(win)
These functions (or prefresh(), pnoutrefresh(), wnoutrefresh(), or
doupdate() are called to write output to the terminal (most other
functions merely manipulate data structures). The wrefresh()
function 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 is sent to the terminal (called
optimization). The refresh function carries out the same task,
2/94 - Intergraph Corporation 13
curses(3) CLIX curses(3)
except it uses stdscr() as a default window. Unless leaveok() has
been enabled, the physical cursor of the terminal is located at the
window cursor. The number of characters output to the terminal is
returned.
Note that refresh() is a macro.
wnoutrefresh(win)
doupdate()
These two functions allow multiple updates to the physical terminal
screen with more efficiency than wrefresh() alone. This is
accomplished in the following manner:
First, the curses() package maintains two data structures, one
representing a physical terminal screen, describing what is
actually on the screen, and a second data structure representing
the virtual terminal screen, describing what the programmer wants
to have on the screen. The wrefresh() function works by first
calling wnoutrefresh(), which copies the named window to the
virtual screen; and then by calling doupdate(), which compares the
virtual screen to the physical screen and then does the actual
update.
If the programmer wishes to output several windows at once, a
series of calls to wrefresh() results 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. This results in only one
burst of output, with fewer total characters transmitted and 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)
When moving the window so that the upper left corner is at position
y, x,, if for any reason, the move causes any portion of the window
to be moved off the screen, an error message returns 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
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
14 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
window affect the character image of both windows. When changing
the image of a subwindow, it is necessary to call touchwin() or
touchline() on the original window (orig) before calling wrefresh()
on orig.
delwin(win)
Deletes the named window, and frees all memory associated with it.
If you try to delete a main window before all the subwindows are
deleted, ERR is returned.
WINDOW *newpad(nlines, ncols)
Creates and returns 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, especially if only a
part of the window is on the screen at one time. Automatic
refreshes of pads (for example, from scrolling or echoing of input)
do not occur in this mode. It is not permitted to use wrefresh()
with a pad as an argument to the function. Either prefresh() or
pnoutrefresh() should be called instead. Note that these functions
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)
Creates and returns a pointer to a subwindow within a pad with the
given number of lines (or rows), nlines, and columns, ncols.
Unlike the subwin() function, which uses screen coordinates, the
window is already 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 affect the character image of both windows.
When changing the image of a subwindow, 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 functions 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. The pminrow and pmincol arguments specify the upper
left corner (inside the pad) of the rectangle to be displayed. The
sminrow, smincol, smaxrow, and smaxcol variables specify the edges
of the screen, where the sides of the rectangle are displayed. The
lower right corner of the displayed rectangle is calculated from
the screen coordinates, since the sides of 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
2/94 - Intergraph Corporation 15
curses(3) CLIX curses(3)
The following functions are used to manipulate text in windows.
addch(ch)
waddch(win, ch)
mvaddch(y, x, ch)
mvwaddch(win, y, x, ch)
If the variable character, ch, is typed at the current cursor
position inside the window, the window cursor is advanced. Its
function is similar to that of putchar. (See putc(3).) At the
right margin, an automatic newline is given. At the bottom of the
scrolling region, if scrollok() is enabled, the scrolling region
scrolls up one line. If ch is a tab, newline, or backspace, the
cursor moves appropriately within the window. A newline also does
a wclrtoeol() before moving. Tabs are considered to be at every
eighth column. If ch is another control character, it is drawn in
the ^X notation. (Calling winch() to a position in the window
containing a control character will not return the control
character, but returns one character of the representation of the
control character.)
Video attributes can be combined with a character by OR-ing them
into the parameter. This 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
wstandout() on the next page.
Note that ch is actually a part of the chtype() function, and not a
character; whereas, addch(), mvaddch(), and mvwaddch() are macros.
echochar(ch)
wechochar(win, ch)
pechochar(pad, ch)
These functions are equivalent to using the addch(ch) function
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). 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,
and not a character. Also, note that echochar() is a macro.
addstr(str)
waddstr(win, str)
mvwaddstr(win, y, x, str)
mvaddstr(y, x, str)
These functions write all the characters of the null-terminated
character str to 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)
16 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
attron(attrs)
wattron(win, attrs)
attrset(attrs) 1
wattrset(win, attrs)
standend() 1
wstandend(win)
standout()
wstandout(win)
These functions 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, 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 any line/character operations. They
are displayed as a graphic representation of the characters shown
on the screen to the extent possible on the particular terminal.
These functions perform the following tasks:
wattrset(win, attrs)
Sets the current attributes of the given window to attrs.
wattroff(win, attrs)
Turns off the named attributes without turning on or off any
other attributes.
wattron(win, attrs)
Turns on the named attributes without affecting any others.
wstandout(win, attrs)
Is the same as wattron(win, A_STANDOUT)
wstandend(win, attrs)
Is the same as wattrset(win, 0); that is, it turns off all
attributes.
Note that wattroff(), wattron(), wattrset(), wstandend(),
and wstandout() return 1 at all times. Also note that attrs
is actually of type chtype, and not a character. Five of
these attributes (attroff(), attron(), attrset(),
standend(), and standout()) are macros.
beep()
flash()
These functions are used to signal the terminal user. The beep()
function sounds the audible alarm on the terminal, if possible. If
2/94 - Intergraph Corporation 17
curses(3) CLIX curses(3)
not possible, the beep() function causes the screen to flash
(equivalent to a visible bell). The flash() function causes the
screen to flash. If it is not possible for the screen to flash, an
audible sound is generated. Nearly all terminals have an audible
signal (bell or beep) but only some can flash the screen.
box(win, vertch, horch)
The win attribute is used to draw a box around the edge of the
window, otherwise the vertch and horch attributes may be used to
draw a box. If vertch and horch are 0, then appropriate default
characters, ACS_VLINE and ACS_HLINE, are used. Note that vertch
and horch are type chtype(), and not characters.
erase()
werase(win)
These functions copy blanks to every position in the window. The
erase() function is a macro.
clear()
wclear(win)
These functions are similar to erase() and werase(), but they also
call clearok(), so that the screen is completely cleared and
redrawn on the next call to wrefresh(). Note that clear() is a
macro.
clrtobot()
wclrtobot()
Using either of these two functions causes all lines below the
window cursor to be 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)
This function is used to insert a ms millisecond pause in user
output. Do not use this function extensively, because padding
characters should be used rather than a processor pause.
delch()
wdelch(win)
mvdelch(y, x)
mvwdelch(win, y, x)
These functions cause the character under the cursor in the window
to be 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 the use of
the hardware delete-character feature.) Note that delch(),
18 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
mvdelch(), and mvwdelch() are macros.
deleteln()
wdeleteln(win)
Both of these functions cause the line below the cursor to be
deleted. All lines below the current line are moved up one line
and the bottom line of the window cleared. The cursor position
does not change. (This does not imply use of the hardware delete-
line feature.) Note that deleteln() is a macro.
getyx(win, y, x)
The cursor position of the window is placed in the two integer
variables y and x. Note that getyx() is a macro, so no & is
necessary before the variables y and x.
getbegyx(win, y, x)
getmaxyx(win, y, x)
The current beginning coordinates (getbegyx()) or size (getmaxyx())
of the specified window are placed in the two integer variables y
and x. Note that getbegyx() and getmaxyx() are macros; therefore
it is not necessary to have an & before the variables y and x.
insch(ch)
winsch(win, ch)
mvwinsch(win, y, x, ch)
mvinsch(y, x, ch)
The ch is inserted before the character under the cursor. All
characters to the right of the cursor are then moved one space to
the right, losing the rightmost character of the line. The cursor
position does not change (after moving to y, x, if specified).
(This does not imply use of the hardware insert-character feature.)
Note that the ch variable is a member of chtype, and therefore not
a character. Note that insch(), mvinsch(), and mvwinsch() are
macros.
insertln()
winsertln(win)
When utilizing this function, 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)
When using this function, the cursor associated with the window
moves to line (row) y, column x. This does not move the physical
cursor of the terminal until wrefresh() is called. The position
specified is relative to the upper left corner of the window, which
is (0, 0). Note that move() is a macro.
overlay(srcwin, dstwin)
2/94 - Intergraph Corporation 19
curses(3) CLIX curses(3)
overwrite(srcwin, dstwin)
These functions overlay text from srcwin on top of text from dstwin
wherever the two windows overlap. The difference between the two
is that overlay() is nondestructive (blanks are not copied), while
overwrite() is destructive.
dmaxcol, overlay)
copywin(srcwin, dstwin, sminrow, smincol, dminrow, dmincol, dmaxrow,
This function provides finer control over the overlay() and
overwrite() functions. As in the prefresh() function, 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 nondestructive, as in overlay().
printw(fmt [, arg ... ])
wprintw(win, fmt [, arg ... ])
mvprintw(y, x, fmt [, arg ... ])
mvwprintw(win, y, x, fmt [, arg ... ])
These functions are analogous to printf(3). The string which would
be output by printf(3) is instead output by using waddstr() on the
given window.
vwprintw(win, fmt, varglist)
This function corresponds to vfprintf(3). 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 the
vprintf() and varargs() manual pages for a detailed description on
how to use variable argument lists.
scroll(win)
This function scrolls the window up one line. It involves moving
the lines in the window data structure.
touchwin(win)
touchline(win, start, count)
These two functions literally throw away all optimization
information concerning 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 affects the other window. The records of which lines
have been changed in the other window will not reflect the change.
The touchline() function only pretends that count lines have been
changed, beginning with line start.
Input
getch()
wgetch(win)
mvgetch(y, x)
mvwgetch(win, y, x)
20 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
A character is read from the terminal associated with the window.
In the NODELAY mode, if there is no input waiting, the value ERR is
returned. In the DELAY mode, the program hangs until the system
passes text through to the program. Depending on the setting of
cbreak(), this occurs after one character (CBREAK mode), or after
the first newline (NOCBREAK mode). In HALF-DELAY mode, the program
hangs until a character is typed or until the specified timeout is
reached. Unless noecho() is set, the character echoes into the
designated window.
When wgetch() is called, if anything in the window has changed (for
example, the cursor has moved or text changed), wgetch() calls
wrefresh() before getting a character.
When using getch(), wgetch(), mvgetch(), or mvwgetch(), do not set
both the NOCBREAK mode (nocbreak()) and ECHO mode (echo()) at the
same time. Depending on the state of the tty() driver, the program
may produce undesirable results when each character is typed. If
wgetch() encounters a ^D, it is returned (unlike stdio functions
which return a null string and have a return code of -1).
If keypad(win, TRUE) is called, and a function key is pressed, the
token for that function key is returned instead of the raw
characters. (See keypad() in the subsection: 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() 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 the Escape key and before the escape is returned to the
program. (Programmer use of the ESCAPE key for a single character
function 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)
When utilizing these functions, a series of calls are made to
wgetch() until a newline, carriage return, or enter key is
received. The resulting value (except for this terminating
character) is placed in the area pointed at by the character
pointer str. The user's erase and kill characters are then
interpreted. See wgetch() for how it handles characters
differently from stdio(3) functions (especially ^D).
Note that getstr(), mvgetstr(), and mvwgetstr() are macros.
2/94 - Intergraph Corporation 21
curses(3) CLIX curses(3)
ungetch(c)
To utilize this function, c must be placed into the input queue,
and it is returned by the next call to wgetch().
flushinp()
This function throws away any typeahead characters that may have
been typed by the user but have not been read by the program.
Note that flushinp() will not throw away any characters supplied by
ungetch().
inch()
winch(win)
mvinch(y, x)
mvwinch(win, y, x)
When utilizing these functions, the character type chtype, is
returned to the current position in the named window. If any
attributes are set for that position, their values are OR'ed to the
returned value. The predefined constants A_CHARTEXT and
A_ATTRIBUTES, defined in <curses.h>, can be used with logical C,
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 functions correspond to scanf(3), as do their arguments and
return values. The wgetstr() function is called in the window, and
the resulting line is used as input for the scan. The return value
for these functions is the number of arg values that are converted
by fmt. The arg values that are not converted are lost. See
wgetstr() for how it handles strings differently from the stdio
functions (especially ^D).
vwscanw(win, fmt, ap)
This function is similar to vwprintw() in that it performs a
wscanw() using a variable argument list. The third argument is a
va_list, a pointer to a list of arguments, as defined in
<varargs.h>. See the vprintf(3) and varargs(0) manual pages for a
detailed description on how to use variable argument lists.
Output Options Setting
These functions set options within the curses() function that deal with
output. All options are initially FALSE, unless otherwise stated. It is
not necessary to turn these options off before calling the endwin()
function.
clearok(win, bf)
22 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
If this function is enabled (bf is TRUE), then the next call to
wrefresh() within this window clears the screen completely and
redraws the entire screen from scratch. This is useful when the
contents of the screen are uncertain and in some cases for a more
pleasing visual effect.
idlok(win, bf)
If this function is enabled (bf is TRUE), the curses() function
considers using the hardware insert/delete-line feature of
terminals so equipped. If disabled (bf is FALSE), the curses()
function seldom uses this feature. (The insert/delete-character
feature is always considered.) This option should be enabled only
if your application needs an insert/delete-line facility (that is,
for a screen editor). It is disabled by default since the
insert/delete-line feature tends to be visually annoying when used
in applications where it isn't really needed. If the
insert/delete-line hardware feature cannot be used, the curses()
function redraws the changed portions of all lines. By not calling
idlok() you save about 5000 bytes of memory.
leaveok(win, bf)
Normally, the hardware cursor is left at the location of the window
cursor being refreshed. This option allows the cursor to be left
wherever the update happens to leave it. It is useful for
applications where the cursor is not used, since it reduces the
need for cursor motions. If possible, the cursor is made invisible
when this option is enabled.
setscrreg(top, bot)
wsetscrreg(win, top, bot)
These functions allow the user to set a software scrolling region
in a window. The top and bot variables are the line numbers for
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 causes all
lines in the scrolling region to scroll up one line. (Note that
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 the output functions.) Note
that setscrreg() is a macro.
scrollok(win, bf)
This option controls what happens when the window cursor is moved
off the edge of the window or scrolling region, either from a
newline on the bottom line, or by 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 inside the
window, and then both the physical terminal screen and window are
2/94 - Intergraph Corporation 23
curses(3) CLIX curses(3)
scrolled up one line. (Note that in order to get the physical
scrolling effect on the terminal, it is also necessary to call
idlok().) The scrollok() function always has a return value of OK.
Input Options Setting
These functions set curses() input options. The options utilize ioctl()
and interacts with the curses() functions. It is not necessary to turn
these options off before calling endwin(). For more information on these
options, refer to the AT&T UNIX System V Programmer's Guide.
cbreak()
nocbreak()
These two functions put the terminal into and out of the CBREAK
mode, respectively. In the CBREAK mode, characters typed by the
user are immediately available to the program and erase/kill
character processing is not performed. When in the NOCBREAK mode,
the tty driver buffers characters typed until a newline or carriage
return is typed. Interrupt and flow-control characters are
unaffected by this mode. (See termio(). Initially the terminal
may or may not be in the CBREAK mode, therefore, a program has to
call cbreak() or nocbreak() explicitly. Most interactive programs
using curses() sets the CBREAK mode.
Note that cbreak() performs a subset of the functionality of raw().
See wgetch() under the subsection Input for a discussion of how
these functions interact with the echo() and noecho() functions.
echo()
noecho()
These functions control if characters typed by the user are echoed
by wgetch() as they are typed. Echoing by the tty driver is always
disabled. Initially wgetch() is in the ECHO mode, therefore the
typed characters are echoed. Authors of most interactive programs
prefer to do their own echoing in a controlled area of the screen,
or not echo at all. To disable echoing, users can call noecho().
See wgetch() under subsection Input for a discussion of how these
functions interact with cbreak() and nocbreak().
nl()
nonl() These functions control whether carriage return translates into a
newline on input by wgetch(). Initially, this translation is done.
The nonl() function turns the translation off. Note that
translation by the tty() driver is disabled in the CBREAK mode.
halfdelay(tenths)
The halfdelay() mode is similar to the CBREAK mode in that
characters typed by the user are available to the program.
However, after blocking for tenths of seconds, The ERR is returned
if nothing is typed. The tenths must be a number between 1 and
255. Use nocbreak() to leave the half-delay mode.
24 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
Note: the halfdelay() mode is only in effect for the next read,
and can be affected by other mode settings. Use timeout() or
wtimeout() for better delay mode control.
intrflush(win, bf)
If this option is enabled, when an interrupt key is pressed on the
keyboard (either Interrupt, Break, or Quit) all output in the tty
driver queue is flushed, giving a faster response to the interrupt,
but causing the curses() function to incorrectly interpret what is
on the screen. Disabling this 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 curses() function to obtain information
from the user's keypad. If enabled, the user can press a function
key (such as an arrow key) and the wgetch() function returns a
single value representing the function key, as in KEY_LEFT. If
disabled, the curses() function will not treat function keys
specially, and the program has to interpret the escape sequences
itself. If the keypad of the terminal is capable of transmitting,
the keypad can be activated by calling keypad(win, TRUE).
meta(win, bf)
Whether the terminal returns seven or eight significant bits on
input depends initially upon the control mode of the tty driver.
To force eight bits to be returned, invoke meta (win, TRUE). To
force seven bits to be returned, invoke meta (win, FALSE). The
window argument, win, is always ignored. If the terminfo()
capabilities, smm (meta_on) and rmm (meta_off), are defined for the
terminal, smm is sent to the terminal when meta(win, TRUE) is
called and rmm is sent when meta(win, FALSE) is called.
nodelay(win, bf)
This option causes wgetch() to be a nonblocking call. If no input
is ready, wgetch() returns ERR. If disabled, wgetch() hangs until
a key is pressed.
notimeout(win, bf)
When interpreting an input escape sequence, wgetch() normally sets
a timer while waiting for the next character. However, if
notimeout(win, TRUE) is called, then wgetch() will not set a timer.
The purpose of the timeout is to differentiate between sequences
received from a function key and those typed by a user.
raw()
noraw()
These functions allow the terminal to be placed into or out of the
RAW mode. The RAW mode is similar to the CBREAK mode, in that
characters typed are immediately and passed through to the user
2/94 - Intergraph Corporation 25
curses(3) CLIX curses(3)
program. However, in the RAW mode, the interrupt, quit, uspend,
and flow-control characters pass through uninterpreted, instead of
generating a signal as they do in RAW mode. The behavior of the
<Break> key depends on other bits in the tty() driver that are not
set by the curses() function.
typeahead(fildes)
The curses() function does line-breakout optimization by looking
for typeahead text periodically while updating the screen. If
input is found, and if it is coming from a tty, the current update
is postponed until wrefresh() or doupdate() is called again. This
allows faster response to commands typed in advance. Normally, the
file descriptor for the input FILE pointer (passed to newterm(), or
stdin(), especially if initscr() was called), isused to do this
typeahead checking. The typeahead() function specifies that the
file descriptor fildes be used to check for typeahead instead. If
fildes is -1, then no typeahead checking is done.
Note that fildes is a file descriptor, not a <stdio.h> FILE
pointer.
timeout(delay)
wtimeout(win, delay)
The timeout() and wtimeout() functions set blocking or non-blocking
read for a given window (timeout sets it for stdscr). If delay is
negative, blocking read is used (that is, the program waits
indefinitely for input). If delay is 0, then non-blocking read is
used (that is, read returns ERR if no input is waiting). If delay
is positive, then read blocks for delay milliseconds, and returns
ERR if there is still no input. Therefore, these routines provide
the same functionality as nodelay(), plus the additional capability
of being able to block for only delay milliseconds (where delay is
positive).
Environment Queries
baudrate()
This function returns the output speed of the terminal. The number
returned is in bits per second; for example, 9600 (is an integer).
char erasechar()
Returns the user's current erase character.
has_ic()
This function is set to TRUE if the terminal has insert- and
delete-character capabilities.
has_il()
This function is set to true if the terminal has insert- and
delete-line capabilities, or can simulate them using scrolling
26 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
regions. This is used to check if it is appropriate to turn on
physical scrolling using scrollok() or idlok().
char killchar()
This function returns the user's current line-kill character.
char *longname()
This function 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().
Therefore, the value should be saved between calls to newterm() if
longname() is going to be used with multiple terminals.
Soft Labels
If desired, the curses() function can be used to 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, the
curses() function takes over the bottom line of stdscr, reducing the size
of stdscr and the variable LINES. The curses() function standardizes the
use of 8 labels of 8 characters each. If a curses() program changes the
values of the soft labels, it can restore them only to the default
settings for that terminal. Therefore, if before calling a curses()
program a user changes the values of the soft labels, those values cannot
be reset when the curses() program terminates.
slk_init(labfmt)
In order to use soft labels, this function 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)
The labnum variable is the label number, from 1 to 8. The label
variable is a string containing up to 8 characters in length. A
NULL string or a NULL pointer generates a blank label. The labfmt
variable can be either a 0, 1, or 2, which indicates if the label
is left-justified, centered, or right-justified.
slk_refresh()
slk_noutrefresh()
These functions correspond to the functions wrefresh() and
wnoutrefresh(). Most applications use slk_noutrefresh because
wrefresh() usually follows.
char *slk_label(labnum)
The current label for label number labnum is returned in the same
2/94 - Intergraph Corporation 27
curses(3) CLIX curses(3)
format as it was in when it was passed to slk_set(), that is, how
it looked prior to being justified according to the labfmt argument
of slk_set().
slk_clear()
This function clears soft labels from the screen.
slk_restore()
This function restores soft labels to the screen after the
slk_clear() function has been used.
slk_touch()
Forces all of the soft labels to be output the next time a
slk_noutrefresh() is performed.
Low-Level curses() Access
The following functions give low-level access to various curses()
functionality. These functions typically would be used inside of library
functions.
def_prog_mode()
def_shell_mode()
Saves the current terminal mode in curses() (if the user was in a
program) or to the ``shell'' state if the terminal was not in
curses(). The terminal state information is saved automatically by
initscr() for later use by reset_prog_mode() and
reset_shell_mode().
reset_prog_mode()
reset_shell_mode()
Restores the terminal to the program mode or shell mode depending
upon whether or not the terminal state information is stored in
curses() or out of curses(). This is done automatically by
endwin() and doupdate(). These functions are not normally called
after performing endwin().
resetty()
savetty()
These functions save and restore the state (or mode) of the
terminal. The savetty() function saves the current state of the
terminal in a buffer and resetty() restores the terminal to the
state at the last call to savetty().
getsyx(y, x)
The current co-ordinates of the virtual screen cursor return in y
and x. If leaveok() is currently TRUE, then -1, -1 returns. If
lines have been removed from the top of the screen using
ripoffline(), y and x include these lines; therefore, y and x
should be used only as arguments for setsyx().
28 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
Note that getsyx() is a macro, so no ``&'' is necessary before the
variables y and x.
setsyx(y, x)
The virtual screen cursor is usually initially set to y, x. If y
and x are both -1, then leaveok() is set. The two functions
getsyx() and setsyx() are designed to be used by a library function
which manipulates curses() windows but will not change the current
position of the program's cursor. Ideally, the library function
calls getsyx() initially to perform manipulation of its own
windows, then does a wnoutrefresh() on its windows, calls setsyx(),
and then calls doupdate().
ripoffline(line, init)
This function provides access to the same facility that slk_init
uses to reduce the size of the screen. The ripoffline() function
must be called before initscr() or newterm() is called. If line is
positive, a line is removed from the top of stdscr(); if negative,
a line is removed from the bottom. When this is done inside
initscr(), the function init() 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 window. Inside this
initialization function, the integer variables lines and cols
(defined in <curses.h>) are not guaranteed accurate and wrefresh()
or doupdate() must not be called. However, it is permissible to
call wnoutrefresh() during the initialization function.
The ripoffline() function 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. An error (ERR) is returned if
the contents of filename are not compatible with the current
release of the curses() software. The next call to doupdate()
restores 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 concerning what is currently on the
terminal screen. If the data is determined to be valid, curses()
bases its next screen update on this information rather than
clearing the screen and starting from scratch. The scr_init()
function is used after the initscr() function or a system() call to
share the screen with another process which has done a scr_dump()
after its endwin() call. The data is declared invalid if the
terminfo(4) capability nrrmc is true or the time-stamp of the tty
2/94 - Intergraph Corporation 29
curses(3) CLIX curses(3)
is old.
Note that keypad(), meta(), slk_clear(), curs_set(), flash() and
beep(), do not affect the contents of the screen but make the tty
time-stamp old.
curs_set(visibility)
Using this function, the cursor state is set to invisible, normal,
or very visible for visibility equal to 0, 1, or 2. If the
terminal supports the visibility requested, the previous cursor()
state is returned; otherwise, ERR is returned.
draino(ms)
This function waits until the output drains enough such that it
takes a few more milliseconds (ms) to drain completely.
garbagedlines(win, begline, numlines)
This function communicates to curses() that a screen line is
garbaged and should be thrown away before having anything
overwritten. It can be used for programs (such as editors) which
want a command to redraw just a single line. Such a command can 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)
This function allows the program or system to sleep for a specified
number of milliseconds (ms).
mvcur(oldrow, oldcol, newrow, newcol)
This function indicates low-level cursor motion.
Terminfo-Level Manipulations
This function consists of low-level functions which must be called by
programs that need to deal directly with the terminfo() database to handle
certain terminal functions, such as programming function keys. For all
other purposes, curses() functions are more suitable and its use is
recommended. Initially, setupterm() should be called.
Note that setupterm() is automatically called by initscr() and newterm().
This defines the set of terminal-dependent variables defined in the
terminfo() database. The terminfo() variables lines and columns are
initialized by setupterm(), as follows: (1) if environment variables LINES
and COLUMNS exist, their values are used; and (2) if the above environment
variables do not exist and the program is running in a layer, the size of
the current layer is used (see layers(1)). Otherwise, the values for
LINES and COLUMNS specified in the terminfo() database are used.
30 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
The header files <curses.h> and <term.h> should be included, in this
order, to get the definitions for the strings, numbers, and flags.
Parameterized strings should be passed through tparm() to instantiate
them. All terminfo() tparm() should be printed with tputs() or putp().
Before exiting, the reset_shell_mode() function should be called to
restore the tty modes. Programs which use cursor addressing should output
the enter_ca_mode function upon startup and should output the exit_ca_mode
before exiting (see terminfo().
Programs desiring shell escapes should call reset_shell_mode and output
exit_ca_mode before the shell is called and should output enter_ca_mode
and call reset_prog_mode after returning from the shell. Note this is
different from the curses() functions (see endwin().
setupterm(term, fildes, errret)
This function reads in the terminfo() database, while initializing
the terminfo() function not set up in 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 is to the file descriptor fildes. If errret is
not NULL, then setupterm() returns OK or ERR and store a status
value in the integer pointed to by errret. A status of 1 in the
error return file (errret) is normal; 0 means that the terminal
could not be found, and -1 means that the terminfo() database could
not be found. If errret is NULL, setupterm() displays 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() boolean, numeric and string variables are stored in
structure type TERMINAL. After setupterm() returns successfully,
the variable cur_term (type TERMINAL) is initialized with all of
the information that the terminfo() boolean, numeric and string
variables refer to. The pointer may 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)
The nterm variable is type TERMINAL. The set_curterm() function
sets the variable cur_term to nterm, and makes all of the
terminfo() boolean, numeric and string variables use the values
from nterm.
del_curterm(oterm)
The oterm variable is a member of type TERMINAL. The del_curterm
frees the space pointed to by oterm and makes it available for
further use. If the oterm variable is the same as the cur_term
variable, then references to any of the terminfo() boolean, numeric
and string variables thereafter may refer to invalid memory
locations until another setupterm() has been called.
restartterm(term, fildes, errret)
2/94 - Intergraph Corporation 31
curses(3) CLIX curses(3)
This function is similar to setupterm(), except that it is called
after restoring memory to a previous state for example, after a
call to scr_restore(). It assumes that the windows and the input
and output options are the same as when memory was saved, but the
terminal type and baud rate may be different.
char *tparm(str, p1, p2, ... , p9)
Instantiates or compiles the string str with parms pi. A pointer
is returned to the result of the str variable with the parameters
applied.
tputs(str, count, putc)
This function applies padding to the string (str) and outputs it.
The str variable must be a terminfo() string variable or the return
value from tparm(), tgetstr(), tigetstr(), or tgoto(). The count
is the number of lines affected, or a 1 will appear if not
applicable. The putc variable is a putchar()-like function to
which characters are passed one at a time.
putp(str)
This function calls the tputs() function (str, 1, putchar).
vidputs(attrs, putc)
Function which outputs a string that puts the terminal in the video
attribute mode (attrs), which is any combination of the attributes
listed in the section ATTRIBUTES. The characters are passed to the
putchar()-like function putc().
vidattr(attrs)
This function is similar to vidputs(), except that it outputs
through putchar().
The following functions return the value of the capability corresponding
to the character string containing the terminfo() capname passed to them.
For example,
rc = tigetstr("acsc")
causes the value of acsc to be returned in rc.
tigetflag(capname)
The value -1 is returned if capname is not a boolean capability.
The value 0 is returned if capname is not defined for the terminal.
tigetnum(capname)
The value -2 is returned if capname is not a numeric capability.
The value -1 is returned if capname is not defined for the
terminal.
tigetstr(capname)
This function causes the value (char *)-1 to be returned if capname
32 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
is not a string capability. A null value is returned if capname is
not defined for the terminal.
char *boolnames[], *boolcodes[], *boolfnames[], *numnames[],
char *numcodes[], *numfnames[], *strnames[], *strcodes[], *strfnames[]
These null-terminated arrays contain the capnames, the termcap
codes, and the full C names, for each of the terminfo() variables.
Termcap Emulation
These functions are included as a conversion aid for programs that use the
termcap library. Their parameters are the same and the functions are
emulated using the terminfo() database.
tgetent(bp, name)
This function looks up the termcap entry for the name. The
emulation ignores the buffer pointer bp.
tgetflag(codename)
Gets the boolean entry for codename.
tgetnum(codename)
Gets the numeric entry for codename.
char *tgetstr(codename, area)
Returns the string entry for codename. If area is not NULL, then
it also stores it in the buffer pointed to by area and advance
area. The tputs() function should be used to output the returned
string.
char *tgoto(cap, col, row)
This function compiles the parameters into the given capability.
The output from this function is passed to the tputs() function.
tputs(str, affcnt, putc)
For information on this function, see tputs() under in the
subsection Terminfo-Level Manipulations.
Miscellaneous
traceoff()
traceon()
This function turns debugging trace output on and off when using
the debug version of the curses() library, <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 displayable
representation of the character c. Control characters are
displayed in the ^X notation. Displaying characters are displayed
as is.
2/94 - Intergraph Corporation 33
curses(3) CLIX curses(3)
The unctrl() function is a macro, defined in <unctrl.h>, which is
automatically included by <curses.h>.
char *keyname(c)
When using this function a character string corresponding to the
key c is returned.
filter()
This function must be called before initscr() or newterm() is
called. It causes the curses() function to work on the premise
that there is a 1-line screen, since curses() will not use any
terminal capabilities which define or already know which line of
the screen the cursor is on.
Use of curscr()
The special window function, curscr() can be used in only a few functions.
If the window argument to clearok() is curscr(), the next call to
wrefresh() (inside any window) causes the screen to clear and redrawn from
scratch. If the window argument to wrefresh() is curscr(), the screen
clears and redrawns from scratch. (This is the standard procedure on how
most programs implement a repaint-screen function.) If the source window
argument for overlay(), overwrite(), or copywin() is curscr(), the current
contents of the virtual terminal screen are accessed.
Obsolete Calls
Various functions maintain compatibility in programs written for older
versions of the curses() library. These functions are implemented 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()
34 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
ATTRIBUTES
The following video attributes, defined in <curses.h>, can be passed to
the functions wattron(), wattroff(), and wattrset, or OR'ed with the
characters passed to waddch().
A_STANDOUT The terminal's 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: wattrset(win, A_NORMAL)
A_INVIS Blanking (invisible)
A_PROTECT Protected
FUNCTION KEYS
The following function keys, defined in <curses.h>, might be returned by
wgetch() if keypad() is 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 if the definition for the key is
not present in the terminfo(4) database.
KEY_BREAK 0401 break key (unreliable)
KEY_DOWN 0402 The four arrow keys ...
KEY_UP 0403
KEY_LEFT 0404
KEY_RIGHT 0405 ...
KEY_HOME 0406 Home key (upward+left arrow)
KEY_BACKSPACE 0407 backspace (unreliable)
KEY_F0 0410 Function keys. Space for 64 keys is reserved.
KEY_F(n) (KEY_F0+(n)) Formula for fn.
KEY_DL 0510 Delete line
KEY_IL 0511 Insert line
KEY_DC 0512 Delete character
KEY_IC 0513 Insert char or enter insert mode
KEY_EIC 0514 Exit insert char mode
KEY_CLEAR 0515 Clear screen
KEY_EOS 0516 Clear to end of screen
KEY_EOL 0517 Clear to end of line
KEY_SF 0520 Scroll 1 line forward
KEY_SR 0521 Scroll 1 line backwards (reverse)
KEY_NPAGE 0522 Next page
KEY_PPAGE 0523 Previous page
KEY_STAB 0524 Set tab
2/94 - Intergraph Corporation 35
curses(3) CLIX curses(3)
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
36 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
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
KEY_SUNDO 0626 shifted undo key
KEY_SUSPEND 0627
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 has the
A_ALTCHARSET bit turned ON. Otherwise, the default character listed below
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
ACS_S9 _ scan line 9
ACS_DIAMOND + diamond
ACS_CKBOARD : checker board (stipple)
2/94 - Intergraph Corporation 37
curses(3) CLIX curses(3)
ACS_DEGREE ' degree symbol
ACS_PLMINUS # plus/minus
ACS_BULLE 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
FILES
/usr/lib/terminfo/a/att4425
OME/myterms/a/att4425
CAUTIONS
Currently, typeahead checking is done using a nodelay read followed by an
ungetch() function for any character that may have been read. Typeahead
checking is done only if a wgetch() function is called at least once.
This may change when proper kernel support is available. Programs using a
mixture of their own input functions with curses() input functions may
wish to invoke typeahead (-1) to turn off typeahead checking.
The argument to napms() is rounded to the nearest second. The draino(ms)
function works when ms equals 0.
The 3.1 version of curses(), containing the new features, runs on UNIX
System V Release 3.1. All programs running with Release 2 or Release 3.0
curses() run on UNIX System V Release 3.1. Applications can be linked
with object files based on Release 2 or Release 3.0 curses()/ terminfo()
with the Release 3.1 <libcurses.a> library; however, applications can not
be linked with object files based on Release 3.1 curses()/terminfo() with
the Release 2 or Release 3.0 libcurses.a library.
The plotting library (plot()) and the curses() library (curses()) both use
the names erase() and move(). The curses() versions are macros. If you
need both libraries, put the plot() code in a different source file than
the curses() code, and/or put #undef move() and erase() in the plot()
code.
Between the time a call to initscr() and endwin() has been issued, use
only the curses() library functions to generate output. Using functions
or the standard I/O package (see stdio()) for output during that time can
cause unpredictable results.
If a pointer passed to a function as a window argument is NULL or out of
range, the results are undefined (core may be dumped).
The curses() functions do not place characters in the last position of the
38 Intergraph Corporation - 2/94
curses(3) CLIX curses(3)
last screen line unless the terminal being used has the ability to insert
charcters.
The halfdelay() mode is only in effect for the next read, and can be
affected by other mode settings. Use timeout() or wtimeout() for better
delay mode control.
RETURN VALUES
All functions return the integer OK upon successful completion and the
integer ERR upon failure, unless otherwise noted in the preceding function
descriptions. All macros return the value of their w version, except
getsyx(), getyx(), getbegyx(), and getmaxyx(). For these macros, no
useful value is returned. Functions that return pointers always return
(type *) NULL on error.
RELATED INFORMATION
Commands: cc(1), ld(1)
Files: varargs(0), profile(4), terminfo(4), termio(7), tty(7)
Functions: ioctl(2), plot(3), putc(3), scanf(3), stdio(3), system(3),
vprintf(3)
Miscellany: term(4)
AT&T UNIX System V Programmer's Guide.
An Enhanced curses and Terminfo Package, Tony L. Hansen, AT&T-IS
60545451-850726-TMS,
The New curses and Terminfo Package, Mark R. Horton, AT&T-BL TM 82-59473-
8,
Screen Updating and Cursor Movement Optimization: A Library Package, Ken
Arnold, Berkeley UNIX Programmers Manual, 4.1BSD, Volume 2C
2/94 - Intergraph Corporation 39