curses(3X) DG/UX 4.30 curses(3X)
NAME
curses - terminal screen handling and optimization package
INTRODUCTION
Curses is a library of routines that allows high-level,
hardware-independent management of terminals, both for
output (screen images) and for input (characters entered at
a keyboard). Curses allows a programmer to treat a terminal
screen as an abstraction. The screen is a two-dimensional
array of characters, each cell of which may have special
display attributes such as underlining or reverse video.
The keyboard generates a single unique code for each key,
including special keys such as function keys.
Curses provides a simple and regular, yet powerful and
comprehensive, programmatic interface to these abstractions
and to the actual terminal. Programmers need never deal
with the inconsistencies between different terminal types,
nor with the details of the operating system's interface to
terminals (the line disciplines).
The curses routines also optimize the process of updating a
screen. That is, they take into account what already
appears on the screen to minimize the amount of information
sent to the terminal. Optimization reduces the time needed
to update a screen image and also reduces the system I/O
load.
Curses uses terminfo(4) as its terminal information
database.
An overview of how to organize and compile a curses program
appears in the SYNOPSIS section. An overview of the use of
curses routines appears in the DESCRIPTION section. The
section named ROUTINES groups detailed descriptions of
curses routines by their complexity and their function.
SYNOPSIS
You must explicitly name the curses library in the command
line that creates a program, as follows:
cc [flag ...] file ... -lcurses [library ...]
where flag specifies whatever compiler option you need to
invoke, file specifies the source program you want to
compile, and library specifies whatever additional library
you want to include.
A program that uses curses should have the following basic
structure:
Licensed material--property of copyright holder(s) Page 1
curses(3X) DG/UX 4.30 curses(3X)
#include <curses.h>
main()
{
initscr();
/* rest of program */
endwin();
exit(0);
}
initscr() and endwin() are described in ROUTINES.
When you include curses.h, you automatically include
<stdio.h>, <termio.h>, and <unctrl.h> as well.
DESCRIPTION
To initialize the curses routines, a program calls either
initscr() or newterm() before calling any of the other
routines. (Three exceptions are noted where they apply.) A
program using the curses library calls the routine endwin()
before exiting to reset the terminal.
To get character-at-a-time input without echoing (as most
interactive, screen oriented programs require), a program
should call cbreak () and noecho () after calling initscr().
Most programs would also call the following routines, which
are described in ROUTINES.
nonl();
intrflush(stdscr, FALSE);
keypad(stdscr, TRUE);
Before you run a curses program, your terminal's tab stops
should be set and its initialization strings, if defined,
must be output. To do this, execute the tput init command
after the shell environment variable TERM has been exported.
For more information about setting tab stops and outputting
initialization strings, see profile(4), tput(1), and the
"Tabs and Initialization" subsection of terminfo(4).
Your program controls what appears on terminal screens by
creating and using terminal-independent data structures
called windows. Windows are essentially two-dimensional
arrays of characters that represent all or part of a
physical screen. Curses supplies a default window called
stdscr, which is the size of the terminal screen. Other
windows may be created with the newwin() routine. A program
refers to a window through variables declared as type WINDOW
*; the type WINDOW is defined in <curses.h> as a structure.
A program manipulates window data structures with routines
Licensed material--property of copyright holder(s) Page 2
curses(3X) DG/UX 4.30 curses(3X)
such as move() and addch(). It then calls refresh() to
update the terminal screen to match the manipulated
structure. (More general versions of these routines are
included with names beginning with w, allowing you to
control a window. A routine not beginning with w usually
affects stdscr.) The characters in a window are actually of
type chtype, so that other information about the character
may also be stored with each character.
A program may also manipulate special windows called pads,
which are not constrained to the size of the screen and
whose contents need not be displayed completely. See the
description of newpad( ) under "Creating Windows and Pads"
for more information.
In addition to drawing characters on the screen, curses
routines can specify video attributes that cause characters
to show up in modes such as underlined or reverse video, as
long as the terminals support such display features. The
routines also allow line drawing characters to be output.
On input, curses is also able to translate escape sequences
from arrow and function keys into single values. The video
attributes, line drawing characters, and input values use
names defined in <curses.h>, such as AREVERSE, ACSHLINE,
and KEYLEFT.
Routines that manipulate color on color alphanumeric
terminals were introduced in System V Release 3.2 (DG/UX
Revision 4.20). To use these routines startcolor() must be
called, usually right after initscr(). Colors are always
used in pairs (referred to as color-pairs). A color-pair
consists of a foreground color (for characters) and a
background color (for the field on which the characters are
displayed). A program sets up a color-pair with the routine
initpair(). After the color-pair has been set up,
COLORPAIR(n), a macro defined in <curses.h>, can be used in
the same ways other video attributes can be used. If a
terminal is capable of redefining colors, the programmer can
use the routine initcolor() to change the definition of a
color. The routines hascolor() and canchangecolor()
return TRUE or FALSE, depending on whether the terminal has
color capabilities and whether a program can change the
colors, respectively. The routine colorcontent() allows a
program to determine the amounts of red, green, and blue
components in an initialized color. The routine
paircontent() allows a program to determine how a given
color-pair is currently defined.
Curses also defines the WINDOW * variable, curscr, which is
used only for certain low-level operations like clearing and
redrawing a garbaged screen. curscr can be used in only a
few curses routines. For example, if the window argument to
Licensed material--property of copyright holder(s) Page 3
curses(3X) DG/UX 4.30 curses(3X)
clearok() is curscr, the next call to wrefresh() with any
window causes the screen to be cleared and repainted from
scratch. If the window argument to wrefresh() is curscr,
the screen is immediately cleared and repainted from
scratch. This is how most programs would implement a
``repaint-screen'' function. More information on using
curscr is provided where its use is appropriate.
Before running a curses program, you may set the environment
variables LINES and COLUMNS to override terminfo(4)'s idea
of how large a screen is. These may be used in a DG/UX X
Windows xterm window, for example, where the size of a
screen can be changed.
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
/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, then 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 section
"Terminfo-Level Access".) The integer variables COLORS and
COLORPAIRS are also defined in <curses.h> and contain,
respectively, the maximum number of colors and color-pairs
the terminal can support. They are filled in by
startcolor().
The constants TRUE and FALSE have the values 1 and 0,
respectively. The constants ERR and OK are returned by
routines to indicate whether the routine successfully
completed. These constants are also defined in <curses.h>.
ROUTINES
Many of the following routines have two or more versions.
The routines prefixed with w require a window argument. The
routines prefixed with p require a pad argument. Those
without a prefix generally use stdscr.
The routines prefixed with mv require y and x coordinates to
which the cursor is moved before performing the appropriate
action. The mv() routines imply a call to move() before the
call to the other routine. y always refers to the row (of
the window), and x always refers to the column. The upper
Licensed material--property of copyright holder(s) Page 4
curses(3X) DG/UX 4.30 curses(3X)
left corner is always (0,0), not (1,1). The routines
prefixed with mvw take both a window argument and y and x
coordinates. The window argument is always specified before
the coordinates.
In each case, win is the window affected and pad is the pad
affected. (win and pad are always of type WINDOW *.)
Option-setting routines require a boolean flag bf with the
value TRUE or FALSE. (bf is always of type bool.) The
types WINDOW, bool, and chtype are defined in <curses.h>.
Beginning Curses Routines
All curses users should know about the routines described in
this section. Every curses program will use some of these
routines. They deal with the essential operations of
curses. The routines are presented in groups in the order
that a typical curses program would use them.
Entering Curses Mode
WINDOW *initscr() The first routine called should always
be initscr(), except when you use
slkinit(), filter(), or ripoffline().
initscr() determines the terminal type
and initializes all curses data
structures. initscr() also arranges
that the first call to wrefresh() clears
the screen. If an error occurs,
initscr() writes an appropriate error
message to standard error and exits;
otherwise, it returns a pointer to
stdscr. If the program requires an
indication of error conditions,
newterm() should be used instead of
initscr(). initscr() should only be
called once per application.
SCREEN *newterm(type, outfd, infd)
char *type;
FILE *outfd, *infd;
A program that manages more than one
terminal must use newterm() instead of
initscr(). A program that requires an
indication of error conditions (so that
it may continue to run in a line-
oriented mode when the terminal cannot
support a screen-oriented program) must
also use this routine. newterm() should
be called once for each terminal. It
returns a variable of type SCREEN* that
should be saved as a reference to that
terminal. The arguments are the type of
the terminal to be used in place of the
Licensed material--property of copyright holder(s) Page 5
curses(3X) DG/UX 4.30 curses(3X)
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
finished running, a program must also
call endwin() for each terminal being
used. If newterm() is called more than
once for the same terminal, the first
terminal referred to must be the last
one for which endwin() is called.
SCREEN *setterm(new)
SCREEN *new; This routine is used to switch between
different terminals. The screen
reference new becomes the new current
terminal. A pointer to the screen
structure of the previous terminal is
returned by the routine. This is the
only routine which manipulates SCREEN
pointers; all other routines affect only
the current terminal.
Controlling Input Options
These routines set input options within curses routines.
The options mostly involve using ioctl(2) and therefore
interact with the line discipline. It is not necessary to
turn these options off before calling endwin().
cbreak()
nocbreak() These two routines put the terminal into
and out of CBREAK mode, respectively.
In CBREAK mode, characters typed by the
user are immediately available to the
program and erase/kill character
processing is not performed. When in
NOCBREAK mode, the terminal driver
buffers typed characters until a newline
or carriage return is typed. Interrupt
and flow-control characters are
unaffected by this mode (see termio(7)
and tty(7)). Initially the terminal may
or may not be in CBREAK mode, as the
mode is inherited from the terminal
driver settings. Therefore, a program
should call cbreak() or nocbreak()
explicitly. Most interactive programs
using curses set CBREAK mode.
Note that cbreak() performs a subset of
the functionality of raw(). See
wgetch() under "Getting Input" for a
discussion of how these routines
Licensed material--property of copyright holder(s) Page 6
curses(3X) DG/UX 4.30 curses(3X)
interact with echo() and noecho().
echo()
noecho() These routines control whether
characters typed by the user are echoed
by the curses routine wgetch() as they
are typed. Echoing by the terminal
driver is always disabled, but initially
wgetch() is in ECHO mode so characters
typed are echoed. Most interactive
programs do their own echoing in a
controlled area of the screen, or do not
echo at all, so they disable echoing by
calling noecho(). See wgetch() under
"Input" for a discussion of how these
routines interact with cbreak() and
nocbreak().
nl()
nonl() These routines control whether carriage
return is translated into newline on
input by wgetch(). Initially, this
translation is done; nonl() turns the
translation off. Note that translation
by the tty(7) driver is disabled in
CBREAK mode.
halfdelay(tenths)
int tenths; Half-delay mode is similar to CBREAK
mode in that characters typed by the
user are immediately available to the
program. However, after blocking for
tenths tenths of seconds, ERR is
returned if nothing has been typed.
tenths must be a number between 1 and
255. Use nocbreak() to leave half-delay
mode.
intrflush(win, bf)
WINDOW *win;
bool bf; If this option is enabled, all output in
the terminal driver queue is flushed
when an interrupt key (interrupt, break,
or quit) is pressed on the keyboard.
This gives the effect of faster response
to the interrupt, but it causes 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 terminal driver
settings. The window argument is
ignored, and is included solely to make
Licensed material--property of copyright holder(s) Page 7
curses(3X) DG/UX 4.30 curses(3X)
the calling interface identical to that
of most of the other I/O options
routines, for example, keypad(win, bf);
meta(win, bf); nodelay(win, bf);
idlok(win, bf); and so on.
keypad(win, bf)
WINDOW *win;
bool bf; This option enables curses to obtain
information from the special keys of the
user's terminal. If enabled, wgetch()
returns a single value representing a
function key (e.g., KEYLEFT) when the
user presses it (the left arrow key).
(See "Getting Input" for a discussion of
wgetch().) If disabled, curses does not
treat function keys specially and the
program must interpret the escape
sequences itself. If the keypad in the
terminal can be turned on (made to
transmit) and off (made to work
locally), calling keypad(win, TRUE) will
turn it on.
meta(win, bf)
WINDOW *win;
bool bf; Initially, whether the terminal returns
7 or 8 significant bits on input depends
on the control mode of the tty driver
(see termio(7)). To force 8 bits to be
returned, invoke meta (win, TRUE). To
force 7 bits to be returned, invoke meta
(win, FALSE). The window argument, win,
is always ignored. If the terminfo(4)
capabilities smm (meta_on) and rmm
(meta_off) are defined for the
terminal, smm will be sent to the
terminal when meta (win, TRUE) is called
and rmm will be sent when meta (win,
FALSE) is called.
nodelay(win, bf)
WINDOW *win;
bool 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)
WINDOW *win;
bool bf; Ordinarily, wgetch() sets a timer while
Licensed material--property of copyright holder(s) Page 8
curses(3X) DG/UX 4.30 curses(3X)
waiting for the next character while it
interprets an input escape sequence. If
notimeout(win, TRUE) is called, then
wgetch() does 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() The terminal is placed into or out of
RAW mode. RAW mode is similar to CBREAK
mode in that characters typed are
immediately passed through to the user
program. The differences are that in
RAW mode, the interrupt, quit, suspend,
and flow control characters are passed
through uninterpreted, instead of
generating signals as they do in CBREAK
mode. The behavior of the BREAK key
depends on other modes in the terminal
driver that are not set by curses.
typeahead(fildes)
int fildes; curses does ``line-breakout
optimization'' by looking for typeahead
periodically while updating the screen.
If input is found and it is coming from
a terminal, 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 when initscr() is called, is
used to do this typeahead checking. The
typeahead() routine specifies that the
file descriptor fildes is to be used to
check for typeahead instead. If fildes
is -1, then no typeahead checking is
done.
Note that fildes is a file descriptor,
not a <stdio.h> FILE pointer.
Controlling Output Options
These routines set output options within curses routines.
All options are initially FALSE, unless otherwise stated.
It is not necessary to turn these options off before calling
endwin().
Licensed material--property of copyright holder(s) Page 9
curses(3X) DG/UX 4.30 curses(3X)
clearok(win, bf)
WINDOW *win;
bool bf; If enabled (bf is TRUE), the next call
to wrefresh() with this window clears
the screen completely and redraws the
entire screen from scratch. This is
useful when the contents of the screen
are uncertain, or in some cases for a
more pleasing visual effect.
idlok(win, bf)
WINDOW *win;
bool bf; If bf is TRUE, curses can use the
hardware ``insert/delete-line'' feature
of terminals so equipped. If bf is
FALSE, curses will avoid using this
feature. (The ``insert/delete-
character'' feature is always
considered.) This option should be
enabled only if your application needs
``insert/delete-line'', for example, for
scrolling or for a screen editor. This
option is disabled by default because
``insert/delete-line'' tends to be
visually annoying when it isn't really
needed. If ``insert/delete-line''
cannot be used, curses redraws the
changed portions of all lines.
Not calling idlok() saves approximately
5000 bytes of memory.
leaveok(win, bf)
WINDOW *win;
bool bf; Normally, the hardware cursor is left at
the location of the cursor for the
window 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)
int top, bot;
WINDOW *win; These routines set a software scrolling
region in a window. top and bot are the
line numbers of the top and bottom
margin of the scrolling region. (Line 0
Licensed material--property of copyright holder(s) Page 10
curses(3X) DG/UX 4.30 curses(3X)
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; only the
text in the scrolling region is
affected. (This does not require a
physical scrolling region capability in
the terminal, like that in the DEC
VT100. However, if idlok() is enabled
and the terminal has either a scrolling
region or ``insert/delete-line''
capability, the output routines will
take advantage of it.)
Note that setscrreg() is a macro.
scrollok(win, bf)
WINDOW *win;
bool bf; This option controls what happens when
the cursor of a window is moved off the
edge of the window or scrolling region,
either from a newline on the bottom
line, or from printing the last
character of the last line. If disabled
(bf is FALSE), the cursor is left on the
bottom line at the location where the
offending character was entered. If
enabled (bf is TRUE), wrefresh() is
called on the window, and then the
physical terminal and window are
scrolled up one line. (To get the
physical scrolling effect on the
terminal, it is also necessary to call
idlok().)
Note that scrollok() will always return
OK.
Performing Output
These routines are used to ``draw'' text on windows.
addch(ch)
waddch(win, ch)
mvaddch(y, x, ch)
mvwaddch(win, y, x, ch)
chtype ch;
WINDOW *win;
int x, y; The character ch is put into the window
at the current cursor position of the
window, and the position of the window
cursor is advanced. The functions are
Licensed material--property of copyright holder(s) Page 11
curses(3X) DG/UX 4.30 curses(3X)
similar to putchar (see putc(3S)). At
the right margin, an automatic newline
is performed. At the bottom of the
scrolling region, if scrollok() is
enabled, the scrolling region is
scrolled up one line.
If ch is a tab, newline, or backspace,
the cursor is moved appropriately within
the window. A newline also does a
wclrtoeol() before moving the cursor.
Tabs are considered to be at every
eighth column. If ch is any other
control character, it is drawn in the ^X
notation. (Calling winch() on a
position in the window containing a
control character does not return the
control character, but instead returns
one character of the representation of
the control character.)
Video attributes can be specified and
set for a character by combining them
with the parameter using the C logical
OR (|) operator. (The intent here is
that text, including attributes, can be
copied from one place to another using
winch() and waddch().) See "Output
Attributes" below for details.
Note that ch is actually of type chtype,
not a character.
Note that addch(), mvaddch(), and
mvwaddch() are macros.
addstr(str)
waddstr(win, str)
mvaddstr(y, x, str)
mvwaddstr(win, y, x, str)
char *str;
WINDOW *win;
int x, y; These routines write all the characters
of the null-terminated character string
str on the given window. This is
equivalent to calling waddch() once for
each character in the string.
Note that addstr(), mvaddstr(), and
mvwaddstr() are macros.
Licensed material--property of copyright holder(s) Page 12
curses(3X) DG/UX 4.30 curses(3X)
erase()
werase(win)
WINDOW *win; These routines copy blanks to every
position in the window.
Note that erase() is a macro.
clear()
wclear(win)
WINDOW *win; These routines are like erase() and
werase(), but they also call clearok(),
arranging that the screen is cleared
completely on the next call to
wrefresh() for that window, and
repainted from scratch.
Note that clear() is a macro.
clrtobot()
wclrtobot(win)
WINDOW *win; All lines below the cursor in this
window are erased. Also, the current
line to the right of the cursor,
inclusive, is erased.
Note that clrtobot() is a macro.
clrtoeol()
wclrtoeol(win)
WINDOW *win; The current line to the right of the
cursor, inclusive, is erased.
Note that clrtoeol() is a macro.
delch()
wdelch(win)
mvdelch(y, x)
mvwdelch(win, y, x)
WINDOW *win;
int x, y; The character under the cursor in the
window is deleted. All characters to
the right on the same line are moved to
the left one position and the last
position on the line is filled with a
blank. The cursor position does not
change (after moving to (y, x), if
specified). (This does not necessarily
imply use of the hardware ``delete-
character'' feature.)
Note that delch(), mvdelch(), and
mvwdelch() are macros.
Licensed material--property of copyright holder(s) Page 13
curses(3X) DG/UX 4.30 curses(3X)
deleteln()
wdeleteln(win)
WINDOW *win; The line under the cursor in the window
is deleted. All lines below the current
line are moved up one line. The bottom
line of the window is cleared. The
cursor position does not change. (This
does not necessarily imply use of the
hardware ``delete-line'' feature.)
Note that deleteln() is a macro.
insch(ch)
winsch(win, ch)
mvinsch(y, x, ch)
mvwinsch(win, y, x, ch)
chtype ch;
WINDOW *win;
int x, y; The character ch is inserted before the
character under the cursor in the
window. All characters to the right are
moved one space to the right, losing the
rightmost character of the line. The
cursor position does not change (after
moving to (y, x), if specified). (This
does not necessarily imply use of the
hardware ``insert-character'' feature.)
Note that ch is actually of type chtype,
not a character.
Note that insch(), mvinsch(), and
mvwinsch() are macros.
insertln()
winsertln(win)
WINDOW *win; A blank line is inserted above the
current line and the bottom line of the
window is lost. (This does not
necessarily imply use of the hardware
``insert-line'' feature.)
Note that insertln() is a macro.
move(y, x)
wmove(win, y, x)
int x, y;
WINDOW *win; The cursor associated with the window is
moved to line (row) y, column x. This
does not move the physical cursor of the
terminal until wrefresh() is called.
The position specified is relative to
Licensed material--property of copyright holder(s) Page 14
curses(3X) DG/UX 4.30 curses(3X)
the upper left corner of the window,
which is (0, 0).
Note that move() is a macro.
printw(fmt [, arg...])
wprintw(win, fmt [, arg...])
mvprintw(y, x, fmt [, arg...])
mvwprintw(win, y, x, fmt [, arg...])
char *fmt;
WINDOW *win;
int x, y; These routines are analogous to
printf(3S). The string that would be
output by printf(3S) is instead output
using waddstr() on the given window.
vwprintw(win, fmt, varglist)
WINDOW *win;
char *fmt;
valist varglist; This routine corresponds to
vfprintf(3S). It performs a wprintw()
using a variable argument list. The
third argument is a va_list, which is a
pointer to a list of arguments as
defined in <varargs.h>. See the
vprintf(3S) and varargs(5) manual pages
for a detailed description on how to use
variable argument lists.
scroll(win)
WINDOW *win; The window is scrolled up one line.
This involves moving the lines in the
window data structure. As an
optimization, if the window is stdscr
and the scrolling region is the entire
window, the physical screen is scrolled
at the same time.
Updating the Screen
refresh()
wrefresh(win)
WINDOW *win; These routines (or prefresh() or
doupdate(), see "Updating Windows and
Pads") must be called to write output to
the terminal, as most other routines
merely manipulate window data
structures. wrefresh() copies the named
window to the physical terminal screen,
taking into account what is already
there to minimize the amount of
information that is sent to the
terminal. (This is called optimization.)
Licensed material--property of copyright holder(s) Page 15
curses(3X) DG/UX 4.30 curses(3X)
refresh() does the same thing, except it
uses stdscr as a default window. Unless
leaveok() has been enabled, the physical
cursor of the terminal is left at the
location of the window's cursor. The
number of characters output to the
terminal is returned.
Note that refresh() is a macro.
Getting Input
getch()
wgetch(win)
mvgetch(y, x)
mvwgetch(win, y, x)
WINDOW *win;
int x, y; A character is read from the terminal
associated with the window. In NODELAY
mode, if there is no input waiting, the
value ERR is returned. In DELAY mode,
the program hangs until the system
passes text through to the program.
Depending on the setting of cbreak(),
this is 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 the specified timeout has been
reached. Unless noecho() has been set,
the character is also echoed into the
designated window.
When wgetch() is called, before getting
a character, it will call wrefresh() if
anything in the window has changed (for
example, the cursor has moved or text
changed).
When using getch(), wgetch(), mvgetch(),
or mvwgetch(), do not set both NOCBREAK
mode (nocbreak()) and ECHO mode (echo())
at the same time.
If wgetch() encounters a ^D, it is
returned (unlike stdio routines, which
would return a null string and have a
return code of -1).
Because of the way curses must do
echoing, your program may perform
poorly.
Licensed material--property of copyright holder(s) Page 16
curses(3X) DG/UX 4.30 curses(3X)
If keypad(win, TRUE) has been called,
and a special key is pressed, the token
for that special key is returned instead
of the raw characters. (See keypad()
under "Controlling Input Options.")
Possible special keys are defined in
<curses.h> as integers beginning with
0401, whose names begin with KEY. If a
character is received that could be the
beginning of a special key sequence
(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 special key value is returned. For
this reason, on many terminals, there is
a delay after a user presses the escape
key before the escape is returned to the
program. (Use of the escape key for a
single character read is discouraged.
Also see notimeout() above.)
Note that getch(), mvgetch(), and
mvwgetch() are macros.
getstr(str)
wgetstr(win, str)
mvgetstr(y, x, str)
mvwgetstr(win, y, x, str)
char *str;
WINDOW *win;
int x, y; A series of calls to wgetch() is made
until a newline, carriage return, or
enter sequence is received. The
resulting null-terminated string is
placed in the area pointed to by the
character pointer str. The user's erase
and kill characters are interpreted.
Note that getstr(), mvgetstr(), and
mvwgetstr() are macros.
See wgetch() for how it handles
characters differently from stdio
routines (especially ^D).
inch()
winch(win)
mvinch(y, x)
mvwinch(win, y, x)
WINDOW *win;
int x, y; The character, of type chtype, at the
Licensed material--property of copyright holder(s) Page 17
curses(3X) DG/UX 4.30 curses(3X)
current cursor position in the specified
window is returned. If any attributes
are set for that position, their values
are logically OR'ed into the value
returned. The predefined constants
ACHARTEXT and AATTRIBUTES, defined in
<curses.h>, can be used with the C
logical AND (&) operator to extract the
character or attributes alone.
Note that inch(), winch(), mvinch(), and
mvwinch() are macros.
scanw(fmt [, arg...])
wscanw(win, fmt [, arg...])
mvscanw(y, x, fmt [, arg...])
mvwscanw(win, y, x, fmt [, arg...])
char *fmt;
WINDOW *win;
int x, y; These routines correspond to scanf(3S),
as do their arguments and return values.
wgetstr() is called on the window, and
the resulting line is used as input for
the scan. The return value for these
routines is the number of arg values
that are converted by fmt. arg values
that are not converted are lost. See
wgetstr() for how it handles strings
(especially ^D) differently from the
stdio routines.
vwscanw(win, fmt, varglist)
WINDOW *win;
char *fmt;
valist varglist; This routine is similar to vwprintw()
above in that it performs a wscanw()
using a variable argument list. The
third argument is a va_list, a pointer
to a list of arguments, as defined in
<varargs.h>. See the vprintf(3S) and
varargs(5) manual pages for a detailed
description on how to use variable
argument lists.
getyx(win, y, x)
WINDOW *win;
int x, y; The cursor position of the window is
placed in the two integer variables y
and x. Because getyx() is a macro, no
``&'' is necessary before the variables.
Licensed material--property of copyright holder(s) Page 18
curses(3X) DG/UX 4.30 curses(3X)
getbegyx(win, y, x)
getmaxyx(win, y, x)
WINDOW *win;
int x, y; These routines retrieve the current
beginning coordinates and size of the
specified window, respectively. They
place the values in the integer
variables y and x.
Note that getbegyx() and getmaxyx() are
macros.
Leaving Curses Mode
endwin() A program should always call endwin()
before exiting from or temporarily
escaping from curses mode, for example,
to do a shell escape or system(3S) call.
This routine restores terminal driver
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().
isendwin() This routine returns TRUE if endwin()
has been called without any subsequent
calls to wrefresh().
Intermediate Curses Routines
The following curses routines are of intermediate
complexity. They deal with important but not essential
operations of curses. Every programmer using curses should
be familiar with them, however, because they are often
useful.
Creating Windows and Pads
WINDOW *newwin(nlines, ncols, begin_y, begin_x)
int nlines, ncols, begin_y, begin_x;
Create and return a pointer to a new
window with the given number of lines
(or rows), nlines, and columns, ncols.
The upper left corner of the window is
at line begin_y, column begin_x. If
either nlines or ncols is 0, they 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).
WINDOW *subwin(orig, nlines, ncols, begin_y, begin_x)
WINDOW *orig;
int nlines, ncols, begin_y, begin_x;
Create and return a pointer to a new
Licensed material--property of copyright holder(s) Page 19
curses(3X) DG/UX 4.30 curses(3X)
window with the given number of lines
(or rows), nlines, and columns, ncols.
The window is at position (begin_y,
begin_x) on the screen. (This position
is relative to the screen, and not to
the window orig.) The window is made in
the middle of the window orig, so that
changes made to one window will affect
the character image of both windows.
When changing the image of a subwindow,
it is necessary to call touchwin() or
touchline() on orig before calling
wrefresh() on orig.
WINDOW *newpad(nlines, ncols)
int nlines, ncols;
Create and return a pointer to a new pad
data structure with the given number of
lines (or rows), nlines, and columns,
ncols. A pad is a window that is not
restricted by the screen size and is not
necessarily associated with a particular
part of the screen. Pads can be used
when a large window is needed, and only
a part of the window is on the screen at
one time. Automatic refreshes of pads
(e.g. from scrolling or echoing of
input) do not occur. It is not legal to
call wrefresh() with a pad as an
argument; the routines prefresh() or
pnoutrefresh() should be called instead.
Note that these routines require
additional parameters to specify the
part of the pad to be displayed and the
location on the screen to be used.
WINDOW *subpad(orig, nlines, ncols, begin_y, begin_x)
WINDOW *orig;
int nlines, ncols, begin_y, begin_x;
Create and return a pointer to a
subwindow within a pad with the given
number of lines (or rows), nlines, and
columns, ncols. Unlike subwin(), which
uses screen coordinates, the window is
at position (begin_y, begin_x) on the
pad. The window is made in the middle
of the pad orig, so that changes made to
one window affect the character images
of both windows. When changing the
image of a subwindow, you should call
touchwin() or touchline() on orig before
calling prefresh() on orig.
Licensed material--property of copyright holder(s) Page 20
curses(3X) DG/UX 4.30 curses(3X)
Manipulating Windows and Pads
mvwin(win, y, x)
WINDOW *win;
int x, y; Move the window so that the upper left
corner is at position (y, x). If the
move would cause any part of the window
to be off the screen, it is an error and
the window is not moved.
overlay(srcwin, dstwin)
overwrite(srcwin, dstwin)
WINDOW *scrwin, *dstwin;
These routines overlay text from srcwin
on top of text from dstwin wherever the
two windows overlap. The difference is
that overlay() is non-destructive
(blanks are not copied), while
overwrite() is destructive. scrwin and
dstwin need not be the same size; only
text where the two windows overlap is
copied.
copywin(srcwin, dstwin, sminrow, smincol,
dminrow, dmincol, dmaxrow, dmaxcol, overlay)
WINDOW *scrwin, *dstwin;
int sminrow, smincol;
int dminrow, dmincol, dmaxrow, dmaxcol, overlay;
This routine provides finer control over
the overlay() and overwrite() routines.
In the source window, the arguments
sminrow and smincol specify the upper
left corner of the rectangle to be
copied. In the destination window,
dminrow, dmincol, dmaxrow, and dmaxcol
specify the edges of the rectangle to be
copied into. The lower right corner in
the source window of the rectangle to be
copied is calculated from the
destination coordinates, since the
rectangles must be the same size. If
the argument overlay is TRUE, then
copying is non-destructive, as in
overlay().
Licensed material--property of copyright holder(s) Page 21
curses(3X) DG/UX 4.30 curses(3X)
Updating Windows and Pads
prefresh(pad, pminrow, pmincol, sminrow, smincol
smaxrow, smaxcol)
pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol
smaxrow, smaxcol)
WINDOW *pad;
int pminrow, pmincol, sminrow, smincol;
int smaxrow, smaxcol;
These routines are analogous to
wrefresh() and wnoutrefresh() except
that pads, instead of windows, are
involved. The additional parameters are
needed to indicate what part of the pad
and screen are involved. pminrow and
pmincol specify the upper left corner,
in the pad, of the rectangle to be
displayed. sminrow, smincol, smaxrow,
and smaxcol specify the edges, on the
screen, of the rectangle to be displayed
in. The lower right corner in the pad
of the rectangle to be displayed is
calculated from the screen coordinates,
since the rectangles must be the same
size. Both rectangles must be entirely
contained within their respective
structures. Negative values of pminrow,
pmincol, sminrow, or smincol are treated
as if they were zero.
wnoutrefresh(win)
doupdate()
WINDOW *win; These two routines allow multiple
updates to the physical terminal screen
with more efficiency than wrefresh()
alone. Curses keeps two data structures
representing the terminal screen: a
physical terminal screen, describing
what is actually on the screen, and a
virtual terminal screen, describing what
the programmer wants to have on the
screen. wrefresh() works by first
calling wnoutrefresh(), which copies the
named window to the virtual screen, and
then by calling doupdate(), which
compares the virtual screen to the
physical screen and does the actual
update. If the programmer wishes to
update 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
Licensed material--property of copyright holder(s) Page 22
curses(3X) DG/UX 4.30 curses(3X)
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.
touchwin(win)
touchline(win, start, count)
WINDOW *win;
int start, count;
Throw away all optimization information
about which parts of the window have
been touched, by pretending that the
entire window has been drawn on. This
is sometimes necessary when using
overlapping windows, since a change to
one window affects the other window, but
the records of which lines have been
changed in the other window does not
reflect the change. touchline() only
pretends that count lines have been
changed, beginning with line start .
Deleting Windows and Pads
delwin(win)
WINDOW *win; Delete the specified window or pad,
freeing up all memory associated with
it. In the case of overlapping windows,
subwindows should be deleted before the
main window.
Output Attributes
attroff(attrs)
wattroff(win, attrs)
attron(attrs)
wattron(win, attrs)
attrset(attrs)
wattrset(win, attrs)
standend()
wstandend(win)
standout()
wstandout(win)
chtype attrs;
WINDOW *win; These routines manipulate the current
attributes of the named window. These
attributes can be any combination of
ASTANDOUT, AREVERSE, ABOLD, ADIM,
ABLINK, AUNDERLINE, and AALTCHARSET,
as well as the macro COLORPAIR(n).
These constants are defined in
<curses.h> and can be combined with the
Licensed material--property of copyright holder(s) Page 23
curses(3X) DG/UX 4.30 curses(3X)
C logical OR ( | ) operator.
The current attributes of a window are
applied to all characters that are
written into the window with waddch().
Attributes are a property of the
character, and move with the character
through any scrolling and insert/delete
line/character operations. To the
extent possible on the particular
terminal, they are displayed as
appropriate graphic embellishments to
the rendition of the characters put on
the screen.
wattrset(win, attrs) sets the current
attributes of the given window to attrs.
wattroff(win, attrs) turns off the named
attributes without turning on or off any
other attributes. wattron(win, attrs)
turns on the named attributes without
affecting any others.
wstandout(win,attrs) is the same as
wattron(win,ASTANDOUT). wstandend(win,
attrs) is the same as wattrset(win, 0),
that is, it turns off all attributes.
Note that wattroff(), wattron(),
wattrset(), wstandend(), and wstandout()
return 1 at all times.
Note that attrs is actually of type
chtype, not a character.
Note that attroff(), attron(),
attrset(), standend(), and standout()
are macros.
Advanced Input and Output Routines
beep()
flash() These routines are used to signal the
terminal user. beep() sounds the
audible alarm on the terminal, if
possible, and if not, it flashes the
screen (visible bell), if that is
possible. flash() flashes the screen,
and if that is not possible, sounds the
audible signal. If neither signal is
possible, nothing happens. Nearly all
terminals have an audible signal (bell
or beep), but only some can flash the
screen.
Licensed material--property of copyright holder(s) Page 24
curses(3X) DG/UX 4.30 curses(3X)
box(win, vertch, horch)
WINDOW *win;
chtype vertch, horch;
A box is drawn around the edge of the
window, win. vertch and horch are the
characters the box is to be drawn with.
If vertch and horch are 0, then
appropriate default characters,
ACSVLINE and ACSHLINE, are used.
Note that vertch and horch are actually
of type chtype, not characters.
echochar(ch)
wechochar(win, ch)
pechochar(pad, ch)
chtype ch;
WINDOW *win;
WINDOW *pad; These routines are functionally
equivalent to a call to addch(ch)
followed by a call to refresh(), a call
to waddch(win, ch) followed by a call to
wrefresh(win), or a call to waddch(pad,
ch) followed by a call to prefresh(pad).
The knowledge that only a single
character is being output is taken into
consideration and, for non-control
characters, a considerable performance
gain can be seen by using these routines
instead of their equivalents. In the
case of pechochar(), the last location
of the pad on the screen is reused for
the arguments to prefresh().
Note that ch is actually of type chtype,
not a character.
Note that echochar() is a macro.
delayoutput(ms)
int ms; Insert a ms millisecond pause in the
output. It is not recommended that this
routine be used extensively, because
padding characters are used rather than
a processor pause.
ungetch(c)
int c; Place c back onto the input queue to be
returned by the next call to wgetch().
flushinp() Throws away any typeahead that has been
typed by the user and has not yet been
Licensed material--property of copyright holder(s) Page 25
curses(3X) DG/UX 4.30 curses(3X)
read by the program. Note that
flushinp() will not throw away any
characters supplied by ungetch().
Queries about the Terminal and Line
baudrate() Returns an integer value expressing the
output speed of the terminal in bits per
second, for example, 9600.
char erasechar() The user's current erase character is
returned.
hasic() Returns TRUE if the terminal has insert-
and delete-character capabilities.
hasil() Returns TRUE if the terminal has insert-
and delete-line capabilities, or can
simulate them using scrolling regions.
This might be used to check to see if it
would be appropriate to turn on physical
scrolling using scrollok() or idlok().
char killchar() The user's current line-kill character
is returned.
char *longname() This routine returns a pointer to a
static area containing a verbose
description of the current terminal.
The maximum length of a verbose
description is 128 characters. It is
defined only after the call to initscr()
or newterm(). The area is overwritten
by each call to newterm() and is not
restored by setterm(), so the value
should be saved between calls to
newterm() if longname() is going to be
used with multiple terminals.
Advanced Curses Routines
The following curses routines are relatively complex. They
can be used in special circumstances to meet specialized
programming requirements.
Color Manipulation
This section describes the color manipulation routines
introduced in DG/UX Revision 4.20, based upon System V
Release 3.2.
startcolor() Call this routine before calling any
other color manipulation routine.
startcolor() sets up eight basic colors
(black, blue, green, cyan, red, magenta,
Licensed material--property of copyright holder(s) Page 26
curses(3X) DG/UX 4.30 curses(3X)
yellow, and white), and two global
variables that define the maximum number
of colors and color-pairs the terminal
can support (COLORS and COLORPAIRS,
respectively). It also restores the
terminal's colors to the values they had
when the terminal was just turned on.
It is good practice to call this routine
right after initscr().
bool hascolors() Returns TRUE if the terminal can
manipulate colors, and FALSE otherwise.
This routine facilitates writing
terminal-independent programs. For
example, a programmer can use it to
decide whether to use color or some
other video attribute.
bool canchangecolor()
Return TRUE if the terminal supports
colors and can change their definitions,
and FALSE otherwise. This routine
facilitates writing terminal-independent
programs.
initcolor(color, red, green, blue)
short color, red, green, blue;
Change the definition of color number
color to represent the three RGB values
red, green, and blue (for the amounts of
red, green, and blue components). If
the color was already in use, all
occurrences of that color on the screen
will immediately change to the new
definition. The value of color must be
between 0 and COLORS-1. (See the COLORS
section for the default color indices.)
The values of red, green, and blue must
each be between 0 and 1000.
initpair(pair, fore, back)
short pair, fore, back;
Change the definition of color-pair pair
to represent foreground color number
fore and background color number back.
If the color-pair was already in use,
the screen will be refreshed and all
occurrences of that color-pair will be
changed to the new definition. The
value of pair must be between 1 and
COLORPAIRS-1. The values of fore and
back must be between 0 and COLORS-1.
Licensed material--property of copyright holder(s) Page 27
curses(3X) DG/UX 4.30 curses(3X)
colorcontent(color, red_p, green_p, blue_p)
short color;
short *red_p, *green_p, *blue_p;
Return the intensity of the red, green,
and blue (RGB) components associated
with color number color. The
information about the amounts of red,
green, and blue components will be
placed into the three short variables
pointed to by red_p, green_p, and
blue_p, respectively. The value of
color must be between 0 and COLORS-1.
The values stored into the variables
pointed to by red_p, green_p, and blue_p
will be between 0 (no component) and
1000 (maximum amount of component).
paircontent(pair, fore_p, back_p)
short pair;
short *fore_p, *back_p;
Return the colors associated with
color-pair number pair. The foreground
and background color numbers will be
placed into the two short variables
pointed to by back_p, and fore_p,
respectively. The value of pair must be
between 1 and COLORPAIRS-1. The values
stored into the variables pointed to by
back_p and fore_p will be between 0 and
COLORS-1.
Soft Labels
If a program requests it, curses manipulates the set of soft
function-key labels that exist on many terminals. If your
terminal does not have soft labels and you want to simulate
them, curses can take over the bottom line of stdscr,
reducing the size of stdscr and the length of the variable
LINES. curses standardizes on 8 labels of 8 characters
each. If a curses program changes the values of the soft
labels, it can restore them only to the default settings for
that terminal. Therefore, if before calling a curses
program a user changes the values of the soft labels, those
values cannot be reset when the curses program terminates.
slkinit(labfmt)
int labfmt; To use soft labels, this routine must be
called before initscr() or newterm() is
called. If initscr() winds up using a
line from stdscr to emulate the soft
labels, then labfmt determines how the
labels are arranged on the screen.
Setting labfmt to 0 indicates that the
Licensed material--property of copyright holder(s) Page 28
curses(3X) DG/UX 4.30 curses(3X)
labels are to be arranged in a 3-2-3
arrangement; 1 asks for a 4-4
arrangement.
slkset(labnum, label, labfmt)
int labnum;
char *label;
int labfmt; This routine sets the text and display
format for a soft label. labnum is the
label number, from 1 to 8. label is the
null-terminated string to put on the
label, up to 8 characters in length. A
NULL string or a NULL pointer puts up a
blank label. labfmt is one of 0, 1, or
2, to indicate whether the label text is
to be left-justified, centered, or
right-justified within the label.
slkrefresh()
slknoutrefresh() These routines correspond to the
routines wrefresh() and wnoutrefresh().
Most applications would use
slknoutrefresh() because a wrefresh()
is likely to follow.
char *slklabel(labnum)
int labnum; The current label text for label number
labnum is returned, in the same format
as when it was passed to slkset(); that
is, how it looked prior to being
justified according to the labfmt
argument of slkset().
slkclear() The soft labels are cleared from the
screen.
slkrestore() The soft labels are restored to the
screen after a slkclear().
slktouch() All of the soft labels are redrawn to be
output the next time a slkrefresh() or
slknoutrefresh() is performed.
Low-Level curses Access
The following routines give low-level access to various
curses functionality. These routines typically would be
used inside of library routines.
defprogmode()
defshellmode() Save the current terminal modes as the
``program'' (in curses) or ``shell''
(not in curses) state for use by the
Licensed material--property of copyright holder(s) Page 29
curses(3X) DG/UX 4.30 curses(3X)
resetprogmode() and resetshellmode()
routines. This is done automatically by
initscr().
resetprogmode()
resetshellmode() Restore the terminal to ``program'' (in
curses) or ``shell'' (out of curses)
state. These are done automatically by
endwin() and doupdate() after an
endwin(), so they normally would not be
called.
resetty()
savetty() These routines save and restore the
state of the terminal modes. savetty()
saves the current state of the terminal
in a buffer and resetty() restores the
state to what it was at the last call to
savetty().
getsyx(y, x)
int x, y; The current coordinates of the virtual
screen cursor are returned in y and x.
If leaveok() is currently TRUE, then
-1,-1 is returned. If lines have been
removed from the top of the screen using
ripoffline(), y and x include these
lines; therefore, y and x should be used
only as arguments for setsyx().
Note that getsyx() is a macro, so no
``&'' is necessary before the variables
y and x.
setsyx(y, x)
int x, y; The virtual screen cursor is set to y,
x. If y and x are both -1, then
leaveok() is set. The two routines
getsyx() and setsyx() are designed to be
used by a library routine which
manipulates curses windows but does not
want to change the current position of
the program's cursor. The library
routine would call getsyx() at the
beginning, do its manipulation of its
own windows, do a wnoutrefresh() on its
windows, call setsyx(), and then call
doupdate().
ripoffline(line, init)
int line;
int (*init)(); This routine provides access to the same
Licensed material--property of copyright holder(s) Page 30
curses(3X) DG/UX 4.30 curses(3X)
facility that slkinit() uses to reduce
the size of the screen. ripoffline()
must be called before initscr() or
newterm() is called. If line is
positive, a line is removed from the top
of stdscr; if negative, a line is
removed from the bottom. Later, inside
initscr(), the routine init() is called
with two arguments: a WINDOW pointer to
the 1-line window that has been
allocated, and an integer that gives the
number of columns in the window. Inside
this initialization routine, the integer
variables LINES and COLS (defined in
<curses.h>) are not guaranteed to be
accurate and wrefresh() or doupdate()
must not be called. It is allowable to
call wnoutrefresh() during the
initialization routine.
ripoffline() can be called up to five
times before calling initscr() or
newterm().
scrdump(filename)
char *filename; The current contents of the virtual
screen are written to the file filename.
scrrestore(filename)
char *filename; The virtual screen is set to the
contents of filename, which must have
been written using scrdump(). ERR is
returned if the contents of filename are
not compatible with the current release
of curses software. The next call to
doupdate() restores the screen to the
image saved in the dump file.
scrinit(filename)
char *filename; The contents of filename are read in and
used to initialize the curses data
structures about what the terminal
currently has on its screen. If the
data is determined to be valid, curses
bases its next update of the screen on
this information rather than clearing
the screen and starting from scratch.
scrinit() would be used after initscr()
or a system(3S) call to share the screen
with another process which has done a
scrdump() after its endwin() call. The
data is declared invalid if the time-
Licensed material--property of copyright holder(s) Page 31
curses(3X) DG/UX 4.30 curses(3X)
stamp of the tty is old or the
terminfo(4) capability nrrmc is true.
Note that keypad(), meta(), slkclear(),
cursset(), flash(), and beep() do not
affect the contents of the screen but
will make the tty's time-stamp old.
cursset(visibility)
int visibility; The cursor state is set to invisible,
normal, or very visible for visibility
equal to 0, 1, or 2. If the terminal
supports the visibility requested, the
previous cursor state is returned;
otherwise, ERR is returned.
draino(ms)
int ms; Wait until the output has drained enough
so that it takes only ms more
milliseconds to drain completely.
garbagedlines(win, begline, numlines)
WINDOW *win;
int begline, numlines;
This routine tells curses that a screen
line is garbaged and should be thrown
away before anything is written to it.
It could be used for programs such as
editors which want a command to redraw
just a single line. Such a command
could be used in cases where there is a
noisy communications line and redrawing
the entire screen would be subject to
even more communication noise.
Redrawing just 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)
int ms; Sleep for ms milliseconds.
mvcur(oldrow, oldcol, newrow, newcol)
int oldrow, oldcol, newrow, newcol;
Low-level cursor motion. Outputs an
optimized string to move the cursor from
line oldrow, column oldcol, to line
newrow, column newcol.
Terminfo-Level Access
These low-level routines must be called by programs that
need to deal directly with the terminfo(4) database to
Licensed material--property of copyright holder(s) Page 32
curses(3X) DG/UX 4.30 curses(3X)
handle certain terminal capabilities, such as programming
function keys. For all other functionality, curses routines
are more suitable and their use is recommended.
Initially, setupterm() should be called. (Note that
setupterm() is automatically called by initscr() and
newterm().) This assigns values to the set of terminal-
dependent variables defined in the terminfo(4) database.
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 specified in the
terminfo(4) database are used.
The header files <curses.h> and <term.h> should be included,
in this order, to get the definitions for these strings,
numbers, and flags. Parameterized strings should be passed
through tparm() to instantiate them. All terminfo(4)
strings (including the output of tparm()) should be printed
with tputs() or putp(). Before exiting, resetshellmode()
should be called to restore the tty modes. Programs that
use cursor addressing should output entercamode upon
startup and should output exitcamode before exiting (see
terminfo(4)). Programs desiring shell escapes should call
resetshellmode() and output exitcamode before the shell
is invoked. After returning from the shell, such programs
should output entercamode and call resetprogmode().
Note that this is different from the curses routines (see
endwin()).
setupterm(term, fildes, errret)
char *term;
int fildes;
int *errret; Read in the terminfo(4) database,
initializing the terminfo(4) structures,
but do not set up the screen and window
data structures used by curses. The
terminal type is specified by the
character string term; if term is NULL,
the contents of the environment variable
TERM are used instead. All output is
directed to the file descriptor fildes.
If errret is not NULL, then setupterm()
returns OK or ERR and stores a status
value in the integer pointed to by
errret. A status of 1 in errret is
normal, 0 means that the terminal could
not be found, and -1 means that the
terminfo(4) database could not be found.
If errret is NULL, setupterm() prints an
error message upon finding an error and
exits. Thus, the simplest call uses all
Licensed material--property of copyright holder(s) Page 33
curses(3X) DG/UX 4.30 curses(3X)
the defaults, and is as follows:
setupterm((char *)0, 1, (int *)0);
The terminfo(4) boolean, numeric, and
string variables are stored in a
structure of type TERMINAL. After
setupterm() returns successfully, the
variable curterm (of type TERMINAL *)
is initialized with all of the
information that the terminfo(4)
boolean, numeric, and string variables
refer to. The pointer may be saved
before calling setupterm() again.
Further calls to setupterm() allocate
new space rather than reuse the space
pointed to by curterm.
setcurterm(nterm)
TERMINAL *nterm; Set the variable curterm to nterm, and
make all of the terminfo(4) boolean,
numeric, and string variables use the
values from nterm.
delcurterm(oterm)
TERMINAL *oterm; Free the space pointed to by oterm and
make it available for further use. If
oterm is the same as curterm, then
references to any of the terminfo(4)
boolean, numeric, and string variables
may access invalid memory locations
until setupterm() is called again.
restartterm(term, fildes, errret)
char *term;
int fildes;
int *errret; Similar to setupterm() except that it is
called after restoring memory to a
previous state; for example, after a
call to scrrestore(). It assumes that
the windows and the input and output
options are the same as when memory was
saved, but the terminal type and baud
rate may be different.
char *tparm(str, p1, p2, ..., p9)
char *str;
int p1, p2, ... p9;
Instantiate the string str with parms
pi. A pointer is returned to the result
of str with the parameters applied.
Licensed material--property of copyright holder(s) Page 34
curses(3X) DG/UX 4.30 curses(3X)
tputs(str, count, putc)
char *str;
int count;
int (*putc)(); Apply padding to the string str and
output it. str must be a terminfo(4)
string variable or the return value from
tparm(), tgetstr(), tigetstr(), or
tgoto(). count is the number of lines
affected, or 1 if not applicable. putc
is a putchar(3S)-like routine to which
the characters are passed, one at a
time.
putp(str)
char *str; A routine that calls
tputs(str, 1, putchar).
vidputs(attrs, putc)
chtype attrs;
int (*putc)(); Output a string that puts the terminal
in the video attribute mode attrs, which
is any combination of the attributes
listed in the ATTRIBUTES section below.
The characters are passed to the
putchar(3S)-like routine putc().
vidattr(attrs)
chtype attrs; Like vidputs(), except that it outputs
through putchar(3S).
The following three routines return the value of the
capability corresponding to the character string containing
the terminfo(4) capname passed to them. For example,
rc = tigetstr("acsc")
causes the value of acsc to be returned in rc.
tigetflag(capname)
char *capname; Return the value of a boolean
capability, either TRUE or FALSE. The
value -1 is returned if capname is not a
boolean capability. The value 0 is
returned if capname is not defined for
this terminal.
tigetnum(capname)
char *capname; Return the value of a numeric
capability. The value -1 is returned if
capname is undefined. The value -2 is
returned if capname is not a numeric
capability. The value -1 is returned if
Licensed material--property of copyright holder(s) Page 35
curses(3X) DG/UX 4.30 curses(3X)
capname is not defined for this
terminal.
tigetstr(capname)
char *capname; Return the value of a string capability.
NULL is returned if capname is
undefined. The value (char *) -1 is
returned if capname is not a string
capability.
char *boolnames[], *boolcodes[], *boolfnames[]
char *numnames[], *numcodes[], *numfnames[]
char *strnames[], *strcodes[], *strfnames[]
These null-terminated arrays contain the
capnames, the termcap codes, and the
full C names, for each of the
terminfo(4) boolean, numeric, and string
capabilities.
Termcap Emulation
These routines are included as a conversion aid for programs
that use the termcap(3X) library. Their parameters are the
same and the routines are emulated using the terminfo(4)
database.
tgetent(bp, name)
char *bp, *name; Look up the terminfo(4) entry for name.
Also place the terminal driver in a
state consistent with termcap(5). The
emulation ignores the buffer pointer bp.
tgetflag(codename)
char codename[2];
Get the boolean entry for codename.
tgetnum(codename)
char codename[2];
Get the numeric entry for codename.
char *tgetstr(codename, area)
char codename[2];
char **area; Return the string entry for codename.
If area is not NULL, then also store the
entry in the buffer pointed to by area
and advance *area. tputs() should be
used to output the returned string.
char *tgoto(cap, col, row)
char *cap;
int col, row; Instantiate the parameters into the
given capability. The output from this
routine is to be passed to tputs().
Licensed material--property of copyright holder(s) Page 36
curses(3X) DG/UX 4.30 curses(3X)
tputs(str, count, putc)
char *str;
int count;
int (*putc)(); See tputs() above, under "Terminfo-Level
Manipulations".
Miscellaneous
traceoff()
traceon() Turn off and on debugging trace output
when using the debug version of the
curses library, /usr/lib/libdcurses.a.
This facility is available only to
customers with a source license.
unctrl(c)
int c; This macro expands to a character string
which is a printable representation of
the character c. Control characters are
displayed in "^X" notation. Printing
characters are displayed as is.
Note that unctrl() is a macro, defined
in <unctrl.h>, which is automatically
included by <curses.h>.
char *keyname(c)
int c; A character string representing the key
c is returned.
filter() This routine is one of the few that may
be called before initscr() or newterm()
is called. It makes curses operate as
though the screen is 1 line long.
Curses does not use any terminal
capabilities that require the cursor to
be on a known line of the screen.
Use of curscr
The special window curscr can be used in only a few
routines. If the window argument to clearok() is curscr,
the next call to wrefresh() with any window causes the
screen to be cleared and repainted from scratch. If the
window argument to wrefresh() is curscr, the screen is
immediately cleared and repainted from scratch. (This is
how most programs would implement a ``repaint-screen''
routine.) The source window argument to overlay(),
overwrite(), and copywin() may be curscr, in which case the
current contents of the virtual terminal screen are
accessed.
Obsolete Calls
Various routines are provided to maintain compatibility in
Licensed material--property of copyright holder(s) Page 37
curses(3X) DG/UX 4.30 curses(3X)
programs written for older versions of the curses library.
These routines are all emulated as indicated below.
crmode() Replaced by cbreak().
fixterm() Replaced by resetprogmode().
gettmode() A no-op.
nocrmode() Replaced by nocbreak().
resetterm() Replaced by resetshellmode().
saveterm() Replaced by defprogmode().
setterm() Replaced by setupterm().
ATTRIBUTES
The following video attributes, defined in <curses.h>, can
be passed to the routines wattron(), wattroff(), and
wattrset(), or combined with the characters passed to
waddch() using the C logical OR (|) operator.
ASTANDOUT Terminal's best highlighting mode;
often dim reverse video
AUNDERLINE Underlining
AREVERSE Reverse video
ABLINK Blinking
ADIM Half bright
ABOLD Extra bright or bold
AALTCHARSET Alternate character set
ACHARTEXT Bit-mask to extract character
(described under winch())
AATTRIBUTES Bit-mask to extract attributes
(described under winch())
ANORMAL Bit mask to reset all attributes
(for example: wattrset(win, ANORMAL))
COLORPAIR(n) Color attribute corresponding to color-pair
number n (note that this is a macro)
ACOLOR Bit-mask to extract color-pair from attributes
The following macro is the reverse of COLORPAIR(n).
PAIRNUMBER(attrs) Color-pair number corresponding to
the color attribute in attrs
(note that this is a macro)
COLORS
In <curses.h> the following macros are defined to have the
numeric values shown. These are the default colors. Curses
also assumes that color 0 (zero) is the default background
color for all terminals.
Licensed material--property of copyright holder(s) Page 38
curses(3X) DG/UX 4.30 curses(3X)
COLORBLACK 0
COLORBLUE 1
COLORGREEN 2
COLORCYAN 3
COLORRED 4
COLORMAGENTA 5
COLORYELLOW 6
COLORWHITE 7
FUNCTION KEYS
The following function keys, defined in <curses.h>, might be
returned by wgetch() if keypad() mode has been enabled.
Note that not all of these may be supported on a particular
terminal if the terminal does not transmit a unique code
when the key is pressed or the definition for the key is not
present in the terminfo(4) database.
Name Value Key name
KEYBREAK 0401 Break (unreliable)
KEYDOWN 0402 Down arrow key
KEYUP 0403 Up arrow key
KEYLEFT 0404 Left arrow key
KEYRIGHT 0405 Right arrow key
KEYHOME 0406 Home key
KEYBACKSPACE 0407 Backspace (unreliable)
KEYF0 0410 Function keys (a maximum of 64)
KEYF(n) (KEYF0+(n)) Formula for fn.
KEYDL 0510 Delete line
KEYIL 0511 Insert line
KEYDC 0512 Delete character
KEYIC 0513 Insert character or enter insert mode
KEYEIC 0514 Exit insert character mode
KEYCLEAR 0515 Clear screen
KEYEOS 0516 Clear to end of screen
KEYEOL 0517 Clear to end of line
KEYSF 0520 Scroll 1 line forward
KEYSR 0521 Scroll 1 line backwards (reverse)
KEYNPAGE 0522 Next page
KEYPPAGE 0523 Previous page
KEYSTAB 0524 Set tab
KEYCTAB 0525 Clear tab
KEYCATAB 0526 Clear all tabs
KEYENTER 0527 Enter or Send
KEYSRESET 0530 Soft (partial) reset
KEYRESET 0531 Reset or Hard reset
KEYPRINT 0532 Print or Copy
Licensed material--property of copyright holder(s) Page 39
curses(3X) DG/UX 4.30 curses(3X)
KEYLL 0533 Home down or Bottom (lower left)
Note: the keypad is arranged like this:
A1 up A3
left B2 right
C1 down C3
KEYA1 0534 Upper left of keypad
KEYA3 0535 Upper right of keypad
KEYB2 0536 Center of keypad
KEYC1 0537 Lower left of keypad
KEYC3 0540 Lower right of keypad
KEYBTAB 0541 Back tab
KEYBEG 0542 Beg or Beginning
KEYCANCEL 0543 Cancel
KEYCLOSE 0544 Close
KEYCOMMAND 0545 Cmd or Command
KEYCOPY 0546 Copy
KEYCREATE 0547 Create
KEYEND 0550 End
KEYEXIT 0551 Exit
KEYFIND 0552 Find
KEYHELP 0553 Help
KEYMARK 0554 Mark
KEYMESSAGE 0555 Message
KEYMOVE 0556 Move
KEYNEXT 0557 Next object
KEYOPEN 0560 Open
KEYOPTIONS 0561 Options
KEYPREVIOUS 0562 Previous object
KEYREDO 0563 Redo
KEYREFERENCE 0564 Ref or Reference
KEYREFRESH 0565 Refresh
KEYREPLACE 0566 Replace
KEYRESTART 0567 Restart
KEYRESUME 0570 Resume
KEYSAVE 0571 Save
KEYSBEG 0572 shifted Beginning
KEYSCANCEL 0573 shifted Cancel
KEYSCOMMAND 0574 shifted Command
KEYSCOPY 0575 shifted Copy
KEYSCREATE 0576 shifted Create
KEYSDC 0577 shifted Delete character
KEYSDL 0600 shifted Delete line
KEYSELECT 0601 Select
KEYSEND 0602 shifted End
KEYSEOL 0603 shifted Clear line
KEYSEXIT 0604 shifted Exit
KEYSFIND 0605 shifted Find
KEYSHELP 0606 shifted Help
Licensed material--property of copyright holder(s) Page 40
curses(3X) DG/UX 4.30 curses(3X)
KEYSHOME 0607 shifted Home
KEYSIC 0610 shifted Input
KEYSLEFT 0611 shifted Left arrow
KEYSMESSAGE 0612 shifted Message
KEYSMOVE 0613 shifted Move
KEYSNEXT 0614 shifted Next
KEYSOPTIONS 0615 shifted Options
KEYSPREVIOUS 0616 shifted Previous
KEYSPRINT 0617 shifted Print
KEYSREDO 0620 shifted Redo
KEYSREPLACE 0621 shifted Replace
KEYSRIGHT 0622 shifted Right arrow
KEYSRSUME 0623 shifted Resume
KEYSSAVE 0624 shifted Save
KEYSSUSPEND 0625 shifted Suspend
KEYSUNDO 0626 shifted Undo
KEYSUSPEND 0627 Suspend
KEYUNDO 0630 Undo
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 AALTCHARSET 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
ACSULCORNER + upper left corner
ACSLLCORNER + lower left corner
ACSURCORNER + upper right corner
ACSLRCORNER + lower right corner
ACSRTEE + right tee (-|)
ACSLTEE + left tee (†)
ACSBTEE + bottom tee (|)
|) ACSTTEE + top tee (
ACSHLINE - horizontal line
ACSVLINE | vertical line
ACSPLUS + plus
ACSS1 - scan line 1
ACSS9 _ scan line 9
ACSDIAMOND + diamond
ACSCKBOARD : checker board (stipple)
ACSDEGREE ' degree symbol
ACSPLMINUS # plus/minus
ACSBULLET o bullet
ACSLARROW < arrow pointing left
Licensed material--property of copyright holder(s) Page 41
curses(3X) DG/UX 4.30 curses(3X)
ACSRARROW > arrow pointing right
ACSDARROW v arrow pointing down
ACSUARROW ^ arrow pointing up
ACSBOARD # board of squares
ACSLANTERN # lantern symbol
ACSBLOCK # solid square block
DIAGNOSTICS
Unless otherwise noted in the preceding routine
descriptions, all routines return the integer ERR upon
failure; the integer OK upon successful completion, if the
routine did not refresh the screen; and the number of
characters that were written to the device during the course
of the update, upon a successful refresh of the screen.
Note that when an output routine such as waddch() causes a
window to scroll, the screen is immediately updated and the
routine will return the number of output characters instead
of OK, its typical return value.
All macros return the value of their w version, except
getsyx(), getyx(), getbegyx(), and getmaxyx(). For these
macros, no useful value is returned.
Routines that return pointers always return NULL on error.
BUGS
Echoing in cbreak mode is very inefficient; ioctl(2) is
called twice for each character echoed.
WARNINGS
While in curses mode (i.e., during the time between calls to
initscr() and endwin()), use only the routines in the curses
library to generate output. Using system calls or the
"standard I/O package" (see stdio(3S)) for output during
that time can cause unpredictable results.
If a pointer passed to a routine as a window argument is
NULL or out of range, the results are undefined (core may be
dumped).
SEE ALSO
cc(1), ld(1), ioctl(2), putc(3S), scanf(3S), stdio(3S),
system(3S), termcap(3X), vprintf(3S), profile(4),
terminfo(4), term(5), termcap(5), varargs(5).
termio(7), tty(7).
Chapter 5 of the Using DG/UX System Programming Tools.
Licensed material--property of copyright holder(s) Page 42