curses(3X) (Enhanced Curses) curses(3X)
NAME
curses - character-oriented screen handling and optimization package
SYNOPSIS
cc [flag ...] file ... -lcurses [library ...]
#include <curses.h>
DESCRIPTION
The curses library routines give the user a terminal-independent method
of updating character screens with reasonable optimization. A program
using these routines must be compiled with the -lcurses option of cc.
The curses package allows: overall screen, window and pad manipula-
tion; output to windows and pads; reading terminal input; control over
terminal and curses input and output options; environment query rou-
tines; color manipulation; use of soft label keys; terminfo access;
and access to low-level curses routines.
To initialize the routines, the routine initscr() or newterm() must be
called before any of the other routines that deal with windows and
screens are used. The routine endwin() must be called before exiting.
To get character-at-a-time input without echoing (most interactive,
screen oriented programs want this), the following sequence should be
used:
initscr,cbreak,noecho;
Most programs would additionally use the sequence:
nonl,intrflush(stdscr,FALSE),keypad(stdscr,TRUE);
Before a curses program is run, the tab stops of the terminal 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. See terminfo(4) for
further details.
Screens, Windows and Terminals
Screen
A screen is the physical output device of the terminal. In curses, a
SCREEN data type is an opaque data type associated with a terminal.
Each window (see below) is associated with a SCREEN.
Windows
The curses functions permit manipulation of window objects, which can
be thought of as two-dimensional arrays of characters and their rendi-
tions. A default window called stdscr, which is the size of the termi-
nal screen, is supplied. Others may be created with newwin().
Page 1 Reliant UNIX 5.44 Printed 11/98
curses(3X) (Enhanced Curses) curses(3X)
Variables declared as WINDOW * refer to windows (and to subwindows,
derived windows, and pads, as described below). These data structures
are manipulated with functions described on the 3X reference manual
pages. Among the most basic functions are move() and addch(). More
general versions of these functions are included that allow a process
to specify a window.
After using functions to manipulate a window, refresh() is called,
telling curses to make the character-oriented screen look like stdscr.
Line drawing characters may be specified to be output. On input,
curses is also able to translate arrow and function keys that transmit
escape sequences into single values. The line drawing characters and
input values use names defined in <curses.h> [see curses(5)].
Each window has a flag that indicates that the information in the win-
dow could differ from the information displayed on the terminal
device. Making any change to the contents of the window, moving or
modifying the window, or setting the window's cursor position, sets
this flag (touches the window). Refreshing the window clears this
flag. For further information, see islinetouched(3X).
Subwindows
A subwindow is a window, created within another window (called the
parent window), and positioned relative to the parent window. A
subwindow can be created by calling derwin(), newpad() or subwin().
Changes made to a subwindow do not affect its parent window.
Subwindows can be created from a parent window by calling subwin().
The position and size of subwindows on the screen must be identical to
or totally within the parent window. Changes to a parent window will
affect both subwindows and derived windows. Window clipping is not a
property of subwindows.
Ancestors
The term ancestor refers to a window's parent, or its parent, and so
on.
Derived Windows
Derived windows are subwindows whose position is defined by reference
to the parent window rather than in absolute screen coordinates.
Derived windows are otherwise no different from subwindows.
Pads
A pad is a specialised case of subwindow that is not necessarily asso-
ciated with a viewable part of a screen. Functions that deal with pads
are all discussed in newpad(3X).
Page 2 Reliant UNIX 5.44 Printed 11/98
curses(3X) (Enhanced Curses) curses(3X)
Terminal
A terminal is the logical input and output device through which
character-based applications interact with the user. TERMINAL is an
opaque data type associated with a terminal. A TERMINAL data structure
primarily contains information about the capabilities of the terminal,
as defined by terminfo. A TERMINAL also contains information about the
terminal modes and current state for input and output operations. Each
screen (see above) is associated with a TERMINAL.
Input Processing
The curses input model provides a variety of ways to obtain input from
the keyboard.
Keypad Processing
The application can enable or disable "keypad translation" by calling
keypad(). When translation is enabled, curses attempts to translate a
sequence of terminal input that represents the pressing of a function
key into a single key code. When translation is disabled, curses
passes terminal input to the application without such translation, and
any interpretation of the input as representing the pressing of a
keypad key must be done by the application.
The complete set of key codes for keypad keys that curses can process
is specified by the constants defined in <curses.h>. whose names begin
with KEY. Each terminal type described in the terminfo database may
support some or all of these key codes. The terminfo database speci-
fies the sequence of input characters from the terminal type that cor-
respond to each key code [see keypad(3X)].
The curses implementation cannot translate keypad keys on terminals
where pressing the keys does not transmit a unique sequence.
When translation is enabled and a character that could be the begin-
ning of a function key (such as escape) is received, curses notes the
time and begins accumulating characters. If curses receives additional
characters that represent the pressing of a keypad key, within an
unspecified interval from the time the first character was received,
then curses converts this input to a key code for presentation to the
application. If such characters are not received during this interval,
translation of this input does not occur and the individual characters
are presented to the application separately. (Because curses waits for
this interval to accumulate a key code, many terminals experience a
delay between the time a user presses the escape key and the time the
escape is returned to the application.)
Page 3 Reliant UNIX 5.44 Printed 11/98
curses(3X) (Enhanced Curses) curses(3X)
In addition, No Timeout Mode provides that in any case where curses
has received part of a function key sequence, it waits indefinitely
for the complete key sequence. The "unspecified interval" in the pre-
vious paragraph becomes infinite in No Timeout Mode. No Timeout Mode
allows the use of function keys over slow communication lines. No
Timeout Mode lets the user type the individual characters of a func-
tion key sequence, but also delays application response when the user
types a character (not a function key) that begins a function key
sequence. For this reason, in No Timeout Mode many terminals will
appear to hang between the time a user presses the escape key and the
time another key is pressed. No Timeout Mode is switchable by calling
notimeout().
If any special characters (<backspace>, <carriage return>, <newline>,
<tab>) are defined or redefined to be characters that are members of a
function key sequence, then curses will be unable to recognise and
translate those function keys.
Several of the modes discussed below are described in terms of availa-
bility of input. If keypad translation is enabled, then input is not
available once curses has begun receiving a keypad sequence until the
sequence is completely received or the interval has elapsed.
Input Mode
The XBD ("Special Characters") defines flow-control characters, the
interrupt character, the erase character, and the kill character. Four
mutually-exclusive curses modes let the application control the effect
of these input characters:
________________________________________________________________________
| Input Mode | Effect |
|__________________|____________________________________________________|
| Cooked Mode | This achieves normal line-at-a-time processing |
| | with all special characters handled outside the |
| | application. This achieves the same effect as |
| | canonical-mode input processing as specified in |
| | the XBD. The state of the ISIG and IXON flags are |
| | not changed upon entering this mode by calling |
| | nocbreak(), and are set upon entering this mode by|
| | calling noraw(). |
| | |
| | The implementation supports erase and kill charac-|
| | ters from any supported locale, no matter what the|
| | width of the character is. |
|__________________|____________________________________________________|
Page 4 Reliant UNIX 5.44 Printed 11/98
curses(3X) (Enhanced Curses) curses(3X)
________________________________________________________________________
| Input Mode | Effect |
|__________________|____________________________________________________|
| cbreak Mode | Characters typed by the user are immediately |
| | available to the application and curses does not |
| | perform special processing on either the erase |
| | character or the kill character. An application |
| | can select cbreak mode to do its own line editing |
| | but to let the abort character be used to abort |
| | the task. This mode achieves the same effect as |
| | non-canonical-mode, Case B input processing (with |
| | MIN set to 1 and ICRNL cleared) as specified in |
| | the XBD. The state of the ISIG and IXON flags are |
| | not changed upon entering this mode. |
| | |
| Half-Delay Mode | The effect is the same as cbreak, except that |
| | input functions wait until a character is avail- |
| | able or an interval defined by the application |
| | elapses, whichever comes first. This mode achieves|
| | the same effect as non-canonical-mode, Case C |
| | input processing (with TIME set to the value |
| | specified by the application) as specified in the |
| | XBD. The state of the ISIG and IXON flags are not |
| | changed upon entering this mode. |
| | |
| Raw Mode | Raw mode gives the application maximum control |
| | over terminal input. The application sees each |
| | character as it is typed. This achieves the same |
| | effect as non-canonical mode, Case D input pro- |
| | cessing as specified in the XBD. The ISIG and IXON|
| | flags are cleared upon entering this mode. |
|__________________|____________________________________________________|
The terminal interface settings are recorded when the process calls
initscr() or newterm() to initialise curses and restores these set-
tings when endwin() is called. The initial input mode for curses
operations is unspecified unless the implementation supports Enhanced
Curses compliance, in which the initial input mode is cbreak mode.
The behaviour of the BREAK key depends on other bits in the display
driver that are not set by curses.
Delay Mode
Two mutually-exclusive delay modes specify how quickly certain curses
functions return to the application when there is no terminal input
waiting when the function is called:
Page 5 Reliant UNIX 5.44 Printed 11/98
curses(3X) (Enhanced Curses) curses(3X)
No Delay The function fails.
Delay The application waits until the implementation passes text
through to the application. If cbreak or Raw Mode is set,
this is after one character. Otherwise, this is after the
first <newline> character, end-of-line character, or end-
of-file character.
The effect of No Delay Mode on function key processing is unspecified.
Echo Processing
Echo mode determines whether curses echoes typed characters to the
screen. The effect of Echo mode is analogous to the effect of the ECHO
flag in the local mode field of the termios structure associated with
the terminal device connected to the window. However, curses always
clears the ECHO flag when invoked, to inhibit the operating system
from performing echoing. The method of echoing characters is not
identical to the operating system's method of echoing characters,
because curses performs additional processing of terminal input.
If in Echo mode, curses performs its own echoing: Any visible input
character is stored in the current or specified window by the input
function that the application called, at that window's cursor posi-
tion, as though addch() were called, with all consequent effects such
as cursor movement and wrapping.
If not in Echo mode, any echoing of input must be performed by the
application. Applications often perform their own echoing in a con-
trolled area of the screen, or do not echo at all, so they disable
Echo mode.
It may not be possible to turn off echo processing for synchronous and
networked asynchronous terminals because echo processing is done
directly by the terminals. Applications running on such terminals
should be aware that any characters typed will appear on the screen at
wherever the cursor is positioned.
Environment Variables
If the environment variables LINES and COLUMNS are set, or if the pro-
gram is executing in a window environment, line and column information
in the environment will override information read by terminfo. This
would effect a program running in an AT&T 630 layer, for example,
where the size of a screen is changeable.
If the environment variable TERMINFO is defined, any program using
curses checks for a local terminal definition before checking in the
standard place. For example, if TERM is set to att4424, then the com-
piled terminal definition is found in
/usr/share/lib/terminfo/a/att4424.
Page 6 Reliant UNIX 5.44 Printed 11/98
curses(3X) (Enhanced Curses) curses(3X)
(The a is copied from the first letter of att4424 to avoid creation of
huge directories.) However, if TERMINFO is set to $HOME/myterms,
curses first checks
$HOME/myterms/a/att4424,
and if that fails, it then checks
/usr/share/lib/terminfo/a/att4424.
This is useful for developing experimental definitions or when write
permission in /usr/share/lib/terminfo is not available.
The integer variables LINES and COLS are defined in <curses.h> and
will be filled in by initscr with the size of the screen. The con-
stants TRUE and FALSE have the values 1 and 0, respectively.
The curses routines also define the WINDOW * variable curscr which is
used for certain low-level operations like clearing and redrawing a
screen containing garbage. The curscr can be used in only a few rou-
tines.
Function Name Conventions
The 3X reference manual pages present families of multiple curses
functions. Most function families have different functions that give
the programmer the following options:
- A function with the basic name operates on the window stdscr. A
function with the same name plus the w prefix [see w(3X)] operates
on a window specified by the win argument.
When the reference manual page for a function family refers to the
current or specified window, it means stdscr for the basic func-
tions and the window specified by win for any w function.
Functions whose names have the p prefix require an argument that is
a pad instead of a window.
- A function with the basic name operates based on the current cursor
position (of the current or specified window, as described above).
A function with the same name plus the mv [see mv(3X)] prefix moves
the cursor to a position specified by the y and x arguments before
performing the specified operation.
When the reference manual page for a function family refers to the
current or specified position, it means the cursor position for the
basic functions and the position (y, x) for any mv function.
The mvw prefix exists and combines the mv semantics discussed here
with the w semantics discussed above. The window argument is always
specified before the coordinates.
Page 7 Reliant UNIX 5.44 Printed 11/98
curses(3X) (Enhanced Curses) curses(3X)
- A function with the basic name is often provided for historical
compatibility and operates only on single-byte characters. A func-
tion with the same name plus the w infix operates on wide (multi-
byte) characters. A function with the same name plus the w infix
operates on complex characters and their renditions.
- When a function with the basic name operates on a single character,
there is sometimes a function with the same name plus the n infix
that operates on multiple characters. An n argument specifies the
number of characters to process. The respective manual page speci-
fies the outcome if the value of n is inappropriate.
Function Families Provided
____________________________________________________________________________
| Function Names Description | s | w | c | Refer to |
|____________________________________________|___|___|___|_________________|
| Add (Overwrite) | | | | |
|[mv][w]addch add a character | Y | Y | Y | addch(3X) |
|[mv][w]addch[n]str add a character string | N | N | N | addchstr(3X) |
|[mv][w]add[n]str add a string | Y | Y | Y | addnstr(3X) |
|[mv][w]add[n]wstr add a wide character | Y | Y | Y | addnwstr(3X) |
| string | | | | |
|[mv][w]addwch add a wide character | Y | Y | Y | addwch(3X) |
| and rendition | | | | |
|[mv][w]addwch[n]str add an array of wide | ? | N | N | addwchnstr(3X) |
| characters and rendi- | | | | |
| tions | | | | |
|____________________________________________|___|___|___|_________________|
| Change Renditions | | | | |
|[mv][w]chgat change renditions of | - | N | N | chgat(3X) |
| characters in a window | | | | |
|____________________________________________|___|___|___|_________________|
| Delete | | | | |
|[mv][w]delch delete a character | - | - | N | delch(3X) |
|____________________________________________|___|___|___|_________________|
Page 8 Reliant UNIX 5.44 Printed 11/98
curses(3X) (Enhanced Curses) curses(3X)
____________________________________________________________________________
| Function Names Description | s | w | c | Refer to |
|____________________________________________|___|___|___|_________________|
| Get (Input from Key- | | | | |
| board to Window) | | | | |
|[mv][w]getch get a character | Y | Y | Y | getch(3X) |
|[mv][w]get[n]str get a character string | Y | Y | Y | getnstr(3X) |
|[mv][w]getwch get a wide character | Y | Y | Y | getwch(3X) |
|[mv][w]get[n]wstr get an array of wide | Y | Y | Y | getwstr(3X) |
| characters and key | | | | |
| codes | | | | |
|____________________________________________|___|___|___|_________________|
| Explicit Cursor Move- | | | | |
| ment | | | | |
|[w]move move the cursor | - | - | - | move(3X) |
|____________________________________________|___|___|___|_________________|
| Input (Read Back from | | | | |
| Window) | | | | |
|[mv][w]inch input a character | - | - | - | inch(3X) |
|[mv][w]inch[n]str input an array of char-| - | - | - | inchnstr(3X) |
| acters and attributes | | | | |
|[mv][w]in[n]str input a string | - | - | - | innstr(3X) |
|[mv][w]in[n]wstr input a string of wide | - | - | - | innwstr(3X) |
| characters | | | | |
|[mv][w]inwch input a wide character | - | - | - | inwch(3X) |
| and rendition | | | | |
|[mv][w]inwch[n]str input an array of wide | - | - | - | inwchnstr(3X) |
| characters and rendi- | | | | |
| tions | | | | |
|____________________________________________|___|___|___|_________________|
| Insert | | | | |
|[mv][w]insch insert a character | Y | N | N | insch(3X) |
|[mv][w]ins[n]str insert a character | Y | N | N | insnstr(3X) |
| string | | | | |
|[mv][w]ins[n]wstr insert a wide character| Y | N | N | insnwstr(3X) |
| string | | | | |
|[mv][w]inswch insert a wide character| Y | N | N | inswch(3X) |
|____________________________________________|___|___|___|_________________|
| Print and Scan | | | | |
|[mv][w]printw print formatted output | - | - | - | mvprintw(3X) |
|[mv][w]scanw convert formatted input| - | - | - | mvscanw(3X) |
|____________________________________________|___|___|___|_________________|
Legend:
The following notation indicates the effect when characters are moved
to the screen. (For the Get functions, this applies only when echoing
is enabled.)
Page 9 Reliant UNIX 5.44 Printed 11/98
curses(3X) (Enhanced Curses) curses(3X)
s "Y" means these functions perform special-character processing.
"N" means they do not. "?" means the results are unspecified when
these functions are applied to special characters.
w "Y" means these functions perform wrapping. "N" means they do not.
c "Y" means these functions advance the cursor. "N" means they do
not.
- The attribute specified by this column does not apply to these
functions.
NOTES
The header file <curses.h> automatically includes the header files
<stdio.h> and <unctrl.h>.
SEE ALSO
mv(3X), no(3X), w(3X), terminfo(4), curses(5), term(5), unctrl(5).
Page 10 Reliant UNIX 5.44 Printed 11/98