curses(3)curses(3)NAMEcurses - Terminal screen-handling and optimization package
SYNOPSIS
c89 [flag...] file -lcurses [library...]
cc [flag...] file -lcurses [-llibrary...]
#include <curses.h>
DESCRIPTION
The Curses library routines give the user a terminal-independent method
of updating character screens with reasonable optimization. A C program
using these routines must be compiled with the -lcurses operand. (The
cc command supports only -lcurses as an operand. The c89 command sup‐
ports -lcurses in addition to the space-separated format.) See NOTES
for information about compiling in the different definition environ‐
ments required for the standard and backward compatible subsets of
functions, macros, and other definitions that the library supports.
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 database
access; and access to low-level Curses routines.
Screen, Windows, and Terminals
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 (described later) is associated with a SCREEN.
The Curses library permits manipulation of data structures, called win‐
dows, which can be thought of as two-dimensional arrays of characters
and their renditions representing all or part of a terminal's physical
screen. Windows do not have to correspond to the entire screen. It is
possible to create smaller windows and also to indicate that a window
is only partially visible on the screen. It is possible to create win‐
dows larger than the terminal screen by using pads. A default window
called stdscr, which is the size of the terminal screen, is supplied.
Other windows may be created with the newterm or newwin function.
Windows are referred to by variables declared as WINDOW *. These data
structures are manipulated with routines described on Section 3 refer‐
ence pages whose names begin “curs_”. Among the most basic routines
are move and addch, which manipulate the default window stdscr, and
refresh, which tells Curses to update the user's terminal screen from
stdscr. More general versions of these routines enable specific windows
to be manipulated and refreshed.
Each window has a flag to indicate whether 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 (in
other words, touches the window). Refreshing the window clears this
flag.
A subwindow is a window, created within another window called the par‐
ent window, and positioned relative to the parent window. A subwindow
can be created by calling derwin, subpad, or subwin. Changes to either
the parent window or the subwindow affect both. Window clipping is not
a property of subwindows.
The term ancestor refers to a window's parent, or its parent, or so on.
Derived windows are subwindows whose position is defined by reference
to the parent window rather than in absolute screen coordinates. Oth‐
erwise, derived windows are no different from subwindows.
Special windows called pads may also be manipulated. Pads are windows
that are not necessarily associated with a viewable part of the screen.
Pads can be larger than the size of the screen. Use a pad whenever the
application requires a window that is larger than the terminal screen.
A subpad is a specialized case of a subwindow created within a pad. See
curs_pad(3) for more information.
A terminal is the logical input and output device through which charac‐
ter-based applications interact with the user. TERMINAL is an opaque
data type associated with a terminal. A TERMINAL data structure pri‐
marily contains information about the capabilities of the terminal, as
defined by the terminfo database. A TERMINAL data structure also con‐
tains information about the terminal modes and current state for input
and output operations. Each screen is associated with a TERMINAL data
structure.
In addition to drawing characters on the screen, applications can
include video attributes and colors, causing the characters to show up
in such modes as underlined, reverse video, or color on terminals that
support such display enhancements. Applications can also specify line-
drawing characters as output. On input, Curses can translate arrow and
function keys that transmit escape sequences into single values. The
video attributes, line-drawing characters, and input values use names,
such as A_REVERSE, WA_UNDERLINE, ACS_VLINE, ACS_HLINE, and KEY_LEFT,
that are defined in <curses.h>. If the environment variables LINES and
COLUMNS are set, or if the program is executing in a window environ‐
ment, line and column information in the environment overrides informa‐
tion read from the terminfo database. This would affect a program run‐
ning in a window environment, for example, where the size of a screen
is changeable.
If the environment variable TERMINFO is defined, Curses checks for a
local terminal definition before checking in the standard place. For
example, if TERM is set to wyse150, then the standard pathname of the
compiled terminal definition is /usr/share/lib/terminfo/w/wyse150. (The
w in this path is copied from the first letter of wyse150 to avoid cre‐
ation of huge directories.) However, if TERMINFO is set to
$HOME/myterms, Curses first checks for $HOME/myterms/w/wyse150 and, if
no definition is found, then checks for /usr/share/lib/ter‐
minfo/w/wyse150. The search path beginning with $HOME is useful for
developing and testing experimental definitions or when write permis‐
sion in /usr/share/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. The constants 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 variable can be used in only a
few routines.
Multicolumn Characters
Some character sets define multicolumn characters that occupy more than
one column position when displayed on the screen.
Writing a character whose width is greater than the width of the desti‐
nation window is an error.
Attributes
Each character can be displayed with attributes, such as underlining,
reverse video, or color on terminals that support such display enhance‐
ments. Current attributes of a window are applied to all characters
that are written into the window by waddch, wadd_wch, waddstr, waddch‐
str, waddwstr, waddwchstr, or wprintw. Attributes can be combined.
The <curses.h> file defines constants that applications use to specify
attributes. Names of these constants start with A_. The A_ constants
manipulate attributes in objects of type int. Additional attributes can
be specified using constants with the WA_ prefix. The WA_ constants
manipulate attributes in objects of type attr_t.
Two constants that begin with A_ and WA_ and that represent the same
terminal capability refer to the same attribute in the terminfo data‐
base and in the window data structure. The effect on a window does not
differ depending on whether the application specifies A_ or WA_ con‐
stants. For example, when an application updates window attributes
using the interfaces that support the A_ values, a query of the window
attribute using the function that returns WA_ values reflects this
update. When it updates window attributes using the interfaces that
support the WA_ values, for which corresponding A_ values exist, a
query of the window attribute using the function that returns A_ values
reflects this update.
Rendition
The rendition of a character displayed on the screen is its attributes
and a color pair.
The rendition of a character written to the screen becomes a property
of the character and moves with the character through any of the fol‐
lowing operations: Scrolling Line or character insertion Line or char‐
acter deletion
To the extent possible on a particular terminal, a character's rendi‐
tion corresponds to the graphic rendition of the character put on the
screen.
If a given terminal does not support a rendition that an application
program is trying to use, Curses may substitute a different rendition.
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).
Nonspacing Characters
Some character sets may contain nonspacing characters. Nonspacing
characters are those for which wcwidth returns a width of zero. The
application may write nonspacing characters to a window. Every non‐
spacing character in a window is associated with a spacing character
and modifies the spacing character. Nonspacing characters in a window
cannot be addressed separately. A nonspacing character is implicitly
addressed whenever a Curses operation affects the spacing character
with which the nonspacing character is associated.
Nonspacing characters do not support attributes. For interfaces that
use wide characters and attributes, the attributes are ignored if the
wide character is a nonspacing character. Multicolumn characters have
a single set of attributes for all columns. The association of non‐
spacing characters with spacing characters can be controlled by the
application using the wide character interfaces. The wide-character
string functions provide codeset-dependent association.
Two typical effects of a nonspacing character associated with a spacing
character called c, are as follows: The nonspacing character may modify
the appearance of c. For instance, there may be nonspacing characters
that add diacritical marks to characters. However, there may also be
spacing characters with built-in diacritical marks. The nonspacing
character may bridge c to the character following c. Examples of this
usage are the formation of ligatures and the conversion of characters
into compound display forms, words, or ideograms.
Complex Characters
A complex character is a set of associated characters, which may
include a spacing character, any nonspacing characters associated with
it, or both. A spacing complex character is a spacing character fol‐
lowed by its associated nonspacing characters. A nonspacing complex
character is one or more nonspacing characters without an associated
spacing character. An example of a coded character set that has complex
characters is ISO/IEC 10646-1:1993.
A complex character can be written to the screen. If the complex char‐
acter does not include a spacing character, any nonspacing characters
are associated with the spacing complex character that exists at the
specified screen position. When the application reads information back
from the screen, it obtains spacing complex characters.
The cchar_t data type represents a complex character and its rendition.
When cchar_t represents a complex character without a spacing charac‐
ter, then its rendition is not used; when it is written to the screen,
it uses the rendition specified by the spacing character already dis‐
played.
An object of type cchar_t can be initialized by using setcchar and the
object's contents can be extracted by using getcchar. The behavior of
functions that take a cchar_t input argument is undefined if the appli‐
cation provides a cchar_t value that was not initialized in this way.
Window Properties
Windows have the following properties that affect the placing of char‐
acters in the window: Each window has a rendition, which is combined
with the rendition component of the window's background property
(described next). Each window has a background property. The back‐
ground property specifies the following: A spacing complex character
(the background character) that will be used in a variety of situations
where visible information is deleted from the screen. A rendition to
use in displaying the background character in those situations, and in
other situations.
Screen Addressing
Many Curses functions use a coordinate pair for screen addressing. In
the DESCRIPTION, coordinate locations are represented as (y, x) since
the y argument always precedes the x argument in the function call.
These coordinates denote a line/column position, not a character posi‐
tion.
The coordinate y always refers to the row (of the window), and x always
refers to the column. The first row and the first column are numbered
0, not 1. The position (0, 0) is the window's origin.
For example, for terminals that display the ISO 8859-1 character set
(with left-to-right writing), (0, 0) represents the upper left-hand
corner of the screen.
Functions that start with mv take arguments that specify a (y, x) posi‐
tion and move the cursor (as though move were called) before performing
the requested action. As part of the requested action, further cursor
movement may occur as specified on the respective reference page.
Adding (Overwriting) Characters
The Curses functions that contain the word add, such as addch, specify
one or more characters to replace (overwrite) characters already in the
window. If these functions specify only nonspacing characters, they are
appended to a spacing character already in the window.
When replacing a multicolumn character with a character that requires
fewer columns, the new character is added starting at the specified or
implied column position. All columns that the former multicolumn char‐
acter occupied that the new character does not require are orphaned
columns, which are filled using the background character and window
rendition.
Replacing a character with a character that requires more columns also
replaces one or more subsequent characters on the line. This process
may also produce orphaned columns.
Truncation, Wrapping, and Scrolling
If the application specifies a character or a string of characters such
that writing them to a window would extend beyond the end of the line
(for example, if the application tries to deposit any multicolumn char‐
acter at the last column in a line), the behavior depends on whether
the function supports line wrapping: If the function does not wrap, it
fails. If the function wraps, then it places one or more characters in
the window at the start of the next line, beginning with the first
character that would not completely fit on the original line.
If the final character on the line is a multicolumn character
that does not completely fit on the line, the entire character
wraps to the next line, and columns at the end of the original
line may be orphaned.
If the original line was the last line in the window, the wrap
may cause a scroll to occur as follows: If scrolling is enabled,
a scroll occurs. The contents of the first line of the window
are lost. The contents of each remaining line in the window
move to the previous line. The last line of the window is
filled with any characters that wrapped. Any remaining space on
the last line is filled with the background character and rendi‐
tion. If scrolling is disabled, any characters that would
extend beyond the last column of the last line are truncated.
The scrollok function enables and disables scrolling.
Some add functions move the cursor just beyond the end of the last
character added. If this position is beyond the end of a line, wrap‐
ping and scrolling occur under the conditions specified in the preced‐
ing list.
Inserting Characters
Insertion functions (such as insch) insert characters immediately
before the character at the specified or current cursor position.
The insertion shifts all characters that were formerly at or beyond the
cursor position on the cursor line toward the end of that line. The
disposition of the characters that would thus extend beyond the end of
the line depends on whether the function supports wrapping: If the
function does not wrap, those characters are removed from the window.
This may produce orphaned columns. If the function supports wrapping,
the effect is as described earlier.
If multicolumn characters are displayed, some cursor positions are
within a multicolumn character but not at the beginning of a character.
Any request to insert data at a position that is not the beginning of a
multicolumn character will be adjusted so that the actual cursor posi‐
tion is at the beginning of the multicolumn character in which the
requested position occurs.
There are no warning indications relative to cursor relocation. The
application should not maintain an image of the cursor position, since
this constitutes placing terminal-specific information in the applica‐
tion and defeats the purpose of using Curses.
Portable applications cannot assume that a cursor position specified in
an insert function is a reusable indication of the actual cursor posi‐
tion.
Deleting Characters
Deletion functions (such as delch) delete the simple or complex charac‐
ter at the specified or implied cursor position. Regardless of which
column of the character on which the cursor is positioned, all column
positions are replaced by the background character and window rendi‐
tion. The cursor is not relocated. If a character-deletion operation
would cause a previous wrapping operation to be undone, then the
results are unspecified.
Window Operations
Overlapping a window (that is, placing one window on top of another)
and overwriting a window (that is, copying the contents of one window
into another) follows the operation of overwriting multicolumn glyphs
around its edge. Any orphaned columns are handled as described in the
preceding sections on character operations.
Characters that Straddle the Subwindow Border
A subwindow can be defined such that multicolumn characters straddle
the subwindow border. The character operations deal with these strad‐
dling characters as follows: Reading the subwindow with a function such
as in_wch reads the entire straddling character. Adding, inserting, or
deleting characters in the subwindow deletes the entire straddling
character before the requested operation begins and does not relocate
the cursor. Scrolling lines in the subwindow has the following
effects: A straddling character at the start of the line is completely
erased before the scroll operation begins. A straddling character at
the end of the line moves in the direction of the scroll and continues
to straddle the subwindow border. Column positions outside the subwin‐
dow at the straddling character's former position are orphaned unless
another straddling character scrolls into those positions.
If the application calls a function such as border, the preceding situ‐
ations do not occur because writing the border on the subwindow deletes
any straddling characters.
In the preceding cases involving multicolumn characters, operations
confined to a subwindow can modify the screen outside the subwindow.
Therefore, saving a subwindow, performing operations within the subwin‐
dow, and then restoring the subwindow may disturb the appearance of the
screen. To overcome these effects (for example, for pop-up windows),
the application should refresh the entire screen.
Special Characters
The following table describes cursor movement that results from pro‐
cessing of special characters.
In Curses functions that do not move the cursor based on the informa‐
tion placed in the window, special characters are used only within a
string to affect the placement of subsequent characters. In this case,
the cursor movement described in the table does not persist in the vis‐
ible cursor beyond the end of the operation.
In functions that do move the cursor, the special characters can be
used to affect the placement of subsequent characters and to achieve
movement of the visible cursor.
───────────────────────────────────────────────────────────────────────────
Special Character Effect on Cursor
───────────────────────────────────────────────────────────────────────────
backspace Unless the cursor was already in column 0, backspace
moves the cursor one column toward the start of the
current line; any characters after the backspace are
added or inserted starting there.
carriage return Unless the cursor was already in column 0, carriage
return moves the cursor to the start of the current
line. Any characters after the carriage return are
added or inserted starting there.
newline In an add operation, Curses adds the background char‐
acter into successive columns until reaching the end
of the line. Scrolling occurs as described earlier.
Any characters after the newline character are
inserted starting at the start of the new line.
In an insert operation, newline moves the cursor to
the start of a new line. Any characters after the
newline character are placed at the start of the new
line.
The filter function may inhibit this processing.
tab Tab characters in text move subsequent characters to
the next horizontal tab stop. By default, tab stops
are in column 0, 8, 16, and so on.
In an insert or add operation, Curses inserts or adds,
respectively, the background character into successive
columns until reaching the next tab stop. If there are
no more tab stops in the current line, wrapping and
scrolling occur as described earlier.
───────────────────────────────────────────────────────────────────────────
Control Characters
The Curses functions that perform special-character processing concep‐
tually convert control characters to the caret (^) character, followed
by a second character (which is an uppercase letter if it is alpha‐
betic), and write this string to the window in place of the control
character. The functions that retrieve text from the window do not
retrieve the original control character.
Rendition of Characters Placed into a Window
When the application adds or inserts characters into a window, assuming
the character is not the space character, then the window receives the
following: The character that the application specifies The color that
the application specifies or the window color if the application does
not specify a color The attributes specified
In this case, a logically inclusive OR operation combines the
specified attributes with the window attributes.
If the character that the application adds or inserts into a window is
the space character, then the window receives: The background character
The color that the application specifies, or the window color if the
application does not specify a color The attributes specified
In this case, a logically inclusive OR operation combines the
specified attributes with the window attributes.
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
the application must interpret the input.
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 specifies
the sequence of input characters from the terminal type that correspond
to each key code.
Curses 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 beginning
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.)
In addition, No Timeout Mode provides that in any case where Curses has
received part of a function key sequence, Curses waits indefinitely for
the complete key sequence. The “unspecified interval” in the previous
paragraph becomes infinite in No Timeout Mode. No Timeout Mode allows
the use of function keys over slow communication lines. No Timeout
Mode not only 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 the 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 are defined or redefined to be characters
that are members of a function key sequence, then Curses will be unable
to recognize and translate those function keys.
Several of the modes discussed in the next section are described in
terms of availability of input. If keypad translation is enabled, then
input is not available from the time Curses begins receiving a keypad
sequence until the sequence is completely received or until the inter‐
val has elapsed.
Input Modes
Four mutually-exclusive Curses input modes let the application control
the effect of certain characters. In the following table, the term
“special characters” represents flow-control characters, the interrupt
character, the erase character, and the kill character:
─────────────────────────────────────────────────────────────────────────
Input Mode Effect
─────────────────────────────────────────────────────────────────────────
Cooked Mode This mode achieves normal line-at-a-time processing
with all special characters handled outside the appli‐
cation. Cooked mode achieves the same effect as canon‐
ical-mode input processing as specified in the XBD
specification. The state of the ISIG and IXON options
are not changed upon entering this mode by calling
cbreak, and are set upon entering this mode by calling
noraw.
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 noncanonical mode, Case B input pro‐
cessing (with MIN set to 1 and ICRNL cleared) as spec‐
ified in the XBD specification. The state of the ISIG
and IXON options are not changed upon entering this
mode.
Half-Delay Mode The effect is the same as cbreak Mode, except that
input functions wait until a character is available or
an interval defined by the application elapses, which‐
ever comes first. This mode achieves the same effect
as noncanonical mode, Case C input processing (with
TIME set to the value specified by the application) as
specified in the XBD specification. The state of the
ISIG and IXON options 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 processing as specified
in the XBD specification. The ISIG and IXON options
are cleared upon entering this mode.
─────────────────────────────────────────────────────────────────────────
The terminal interface settings are recorded when the process calls
initscr or newterm to initialize Curses and restores these settings
when endwin is called. The initial input mode for Curses operations is
cbreak mode.
The behavior of the Break key depends on other bits in the display
driver that are not set by Curses.
Delay Modes
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:
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, the application waits until after one
character is passed. Otherwise, the application waits
until after the first newline, end-of-line, 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 while it is operating, 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 position,
as though addch were called, with all consequent effects such as cursor
movement and wrapping.
If not in Echo mode, the application must perform any echoing of input.
Applications usually disable Echo Mode because they often perform their
own echoing in a controlled area of the screen or do not echo at all.
Initializing the Curses Environment
To initialize the Curses environment, the application must call the
initscr or newterm routine before using any of the other routines that
deal with windows and screens. The application must call the endwin
routine before exiting. To get character-at-a-time input without echo‐
ing (most interactive, screen-oriented programs want this), applica‐
tions should use the following sequence:
initscr(); cbreak(); noecho();
Most applications also use the following 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. Appli‐
cations can do this by executing the tput init command after exporting
the shell environment variable TERM. (See terminfo(4) for further
details.)
Function Name Conventions
The reference pages often present families of Curses functions. The
names of different functions in each family include a basic name, which
is combined with prefixes and infixes to indicate specific programming
options. The following list explains the naming conventions for Curses
functions: A function with the basic name operates on the window std‐
scr. A function with the same name plus the w prefix operates on a
window specified by the win argument.
When the reference page for a function family refers to the
“current or specified window,” this means stdscr for the func‐
tions whose names begin with the basic name and the window spec‐
ified by win for the functions whose names begin with w.
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 prefix moves the cursor to a position specified
by the y and x arguments before performing the specified opera‐
tion.
When the reference page for a function family refers to the
“current or specified position,” this means the cursor position
for the functions whose names begin with the basic name and the
position (y, x) for functions whose names begin with mv.
The mvw prefix also exists and combines the mv semantics dis‐
cussed here with the w semantics discussed in the preceding list
item. In the function argument list, the window argument is
always specified before the arguments for coordinates. A func‐
tion with the basic name is often provided for historical com‐
patibility and operates only on single-byte characters. A func‐
tion with the same name plus the w infix operates on wide
(multibyte) characters. A function with the same name plus the
_w infix operates on complex characters and their renditions. A
particular reference page discusses functions in only one of
these three categories. When a function with the basic name
operates on a single character or a null-terminated string,
there is sometimes a function with the same name plus the n
infix that operates on a specific number of characters. In this
case, the function includes an n argument that specifies the
number of characters to process. The respective reference page
specifies the outcome if the value of n is inappropriate.
Function Families
The following table lists each family of Curses functions. The “s”,
“w”, and “c” columns, whose entries are more fully explained in the
Legend following the table, indicate whether the function processes
special characters, performs wrapping, and advances the cursor.
Function families include most, but not all, the functions in the
Curses library. See the section titled Index of Routine Names for a
complete and alphabetically ordered list of Curses functions, along
with the reference pages where they are described.
───────────────────────────────────────────────────────────────────────────
Function Names Description s w c
───────────────────────────────────────────────────────────────────────────
Add (Overwrite) Family
[mv][w]addch Add a character Y Y Y
[mv][w]addch[n]str Add a character string N N N
[mv][w]add[n]str Add a string Y Y Y
[mv][w]add[n]wstr Add a wide character string Y Y Y
[mv][w]add_wch Add a wide character and rendi‐ Y Y Y
tion
[mv][w]add_wch[n]str Add an array of wide characters ? N N
and renditions
Change Renditions Family
[mv][w]chgat Change renditions of characters - N N
in a window
Delete Family
[mv][w]delch Delete a character - - N
Get Family (Get Input from Key‐
board to Window)
[mv][w]getch Get a character Y Y Y
[mv][w]get[n]str Get a character string Y Y Y
[mv][w]get_wch Get a wide character Y Y Y
[mv][w]get[n]_wstr Get an array of wide characters Y Y Y
and key codes
Explicit Cursor Movement Family
[w]move Move the cursor - - -
Input Family (Read Back From Win‐
dow)
[mv][w]inch Input a character - - -
[mv][w]inch[n]str Input an array of characters and - - -
attributes
[mv][w]in[n]str Input a string - - -
[mv][w]in[n]wstr Input a string of wide characters - - -
[mv][w]in_wch Input a wide character and rendi‐ - - -
tion
[mv][w]in_wch[n]str Input an array of wide characters - - -
and renditions
Insert Family
[mv][w]insch Insert a character Y N N
[mv][w]ins[n]str Insert a character string Y N N
[mv][w]ins_[n]wstr Insert a wide-character string Y N N
[mv][w]ins_wch Insert a wide character Y N N
Print and Scan Family
[mv][w]printw Print formatted output - - -
[mv][w]scanw Convert formatted output - - -
───────────────────────────────────────────────────────────────────────────
Legend
The following notation indicates the effect when characters are moved
to the screen. (For functions in the Get family, this effect applies
only when echoing is enabled.)
s Y means these functions perform special-character process‐
ing.
N means they do not.
? means the results are unspecified when these functions
are applied to special characters.
- means this attribute does not apply to these functions.
w Y means these functions perform wrapping.
N means they do not.
- means this attribute does not apply to these functions.
c Y means these functions advance the cursor.
N means they do not.
- means this attribute does not apply to these functions.
Index of Routine Names
The following index lists each Curses routine and the name of the ref‐
erence page on which the routine is described. An asterisk following
the routine name indicates that it conforms to the X/Open UNIX standard
(Version 4.2 of the X/Open Curses CAE specification). curs_add_wch(3)curs_add_wchstr(3)curs_add_wchstr(3)curs_addch(3)curs_addchstr(3)curs_addchstr(3)curs_addstr(3)curs_addwstr(3)curs_addstr(3)curs_addwch(3)curs_addwchstr(3)curs_addwchstr(3)curs_addwstr(3)curs_attr_get(3)curs_attr_get(3)curs_attr_get(3)curs_attr_get(3)curs_attr(3)curs_attr(3)curs_attr(3)curs_termattrs(3)curs_beep(3)curs_bkgd(3)curs_bkgd(3)curs_bkgrnd(3)curs_bkgrnd(3)curs_border(3)curs_border_set(3)curs_border(3)curs_border_set(3)curs_color(3)curs_inopts(3)curs_chgat(3)curs_clear(3)curs_outopts(3)curs_clear(3)curs_clear(3)curs_color(3)curs_color(3)curs_attr_get(3)curs_overlay(3)curs_kernel(3)curs_kernel(3)curs_kernel(3)curs_terminfo(3)curs_util(3)curs_delch(3)curs_deleteln(3)curs_initscr(3)curs_window(3)curs_window(3)curs_refresh(3)curs_util(3)curs_window(3)curs_inopts(3)curs_add_wch(3)curs_addch(3)curs_addwch(3)curs_initscr(3)curs_clear(3)curs_termattrs(3)curs_termattrs(3)curs_util(3)curs_beep(3)curs_util(3)curs_get_wch(3)curs_get_wstr(3)curs_getyx(3)curs_bkgrnd(3)curs_getch(3)curs_getcchar(3)curs_getyx(3)curs_get_wstr(3)curs_getstr(3)curs_getwstr(3)curs_getyx(3)curs_getstr(3)curs_getwch(3)curs_util(3) curs_getw‐
str(3)curs_getyx(3)curs_inopts(3)curs_color(3)curs_termattrs(3)curs_termattrs(3)curs_border(3)curs_border_set(3)curs_outopts(3)curs_outopts(3)curs_outopts(3)curs_in_wch(3)curs_in_wchstr(3)curs_in_wchstr(3)curs_inch(3)curs_inchstr(3)curs_inchstr(3)curs_color(3)curs_color(3)curs_initscr(3)curs_instr(3) curs_inw‐
str(3)curs_ins_wstr(3)curs_ins_wch(3)curs_ins_wstr(3)curs_insch(3)curs_deleteln(3)curs_deleteln(3)curs_insstr(3)curs_inswstr(3)curs_insstr(3)curs_instr(3)curs_inswch(3)curs_inswstr(3)curs_inopts(3)curs_inwch(3)curs_inwchstr(3)curs_inwchstr(3)curs_inwstr(3)curs_touch(3)curs_touch(3)curs_initscr(3)curs_util(3)curs_util(3)curs_inopts(3)curs_termattrs(3)curs_outopts(3) curs_ter‐
mattrs(3)curs_inopts(3)curs_move(3)curs_add_wch(3) curs_add_wch‐
str(3)curs_add_wchstr(3)curs_addch(3)curs_addchstr(3) curs_addch‐
str(3)curs_addstr(3)curs_addwstr(3)curs_addstr(3)curs_addwch(3)curs_addwchstr(3)curs_addwchstr(3)curs_addwstr(3)curs_chgat(3)curs_terminfo(3)curs_delch(3)curs_window(3)curs_get_wch(3)curs_get_wstr(3)curs_getch(3)curs_get_wstr(3)curs_getstr(3)curs_getwstr(3)curs_getstr(3)curs_getwch(3)curs_getwstr(3) curs_bor‐
der(3)curs_border_set(3)curs_in_wch(3)curs_in_wchstr(3) curs_in_wch‐
str(3)curs_inch(3)curs_inchstr(3)curs_inchstr(3)curs_instr(3)curs_inwstr(3)curs_ins_wstr(3)curs_ins_wch(3)curs_insch(3)curs_insstr(3)curs_inswstr(3)curs_insstr(3)curs_instr(3)curs_inswch(3)curs_inswstr(3)curs_inwch(3)curs_inwchstr(3)curs_inwchstr(3)curs_inwstr(3)curs_printw(3)curs_scanw(3) curs_bor‐
der(3)curs_border_set(3)curs_add_wch(3)curs_add_wchstr(3)curs_add_wchstr(3)curs_addch(3)curs_addchstr(3)curs_addchstr(3)curs_addstr(3)curs_addwstr(3)curs_addstr(3)curs_addwch(3)curs_addwchstr(3)curs_addwchstr(3)curs_addwstr(3)curs_chgat(3)curs_delch(3)curs_get_wch(3)curs_get_wstr(3)curs_getch(3)curs_get_wstr(3)curs_getstr(3)curs_getwstr(3)curs_getstr(3)curs_getwch(3)curs_getwstr(3)curs_border(3)curs_border_set(3)curs_window(3)curs_in_wch(3)curs_in_wchstr(3)curs_in_wchstr(3)curs_inch(3)curs_inchstr(3)curs_inchstr(3)curs_instr(3) curs_inw‐
str(3)curs_ins_wstr(3)curs_ins_wch(3)curs_ins_wstr(3)curs_insch(3)curs_insstr(3)curs_insstr(3)curs_instr(3)curs_inswch(3) curs_insw‐
str(3)curs_inwch(3)curs_inwchstr(3)curs_in_wchstr(3)curs_inwstr(3)curs_printw(3)curs_scanw(3)curs_border(3)curs_border_set(3)curs_kernel(3)curs_pad(3)curs_initscr(3)curs_window(3) curs_out‐
opts(3)curs_inopts(3)curs_inopts(3)curs_inopts(3)curs_outopts(3)curs_inopts(3)curs_inopts(3)curs_inopts(3)curs_overlay(3) curs_over‐
lay(3)curs_color(3)curs_color(3)curs_pad(3)curs_pad(3)curs_pad(3)curs_pad(3)curs_pad(3)curs_printw(3)curs_terminfo(3)curs_util(3)curs_inopts(3)curs_inopts(3)curs_refresh(3)curs_refresh(3) curs_ker‐
nel(3)curs_kernel(3)curs_kernel(3)curs_terminfo(3)curs_kernel(3)curs_kernel(3)curs_scanw(3)curs_scr_dump(3)curs_scr_dump(3)curs_scr_dump(3)curs_scr_dump(3)curs_scroll(3)curs_scroll(3)curs_outopts(3)curs_getcchar(3)curs_terminfo(3)curs_initscr(3)curs_outopts(3)curs_terminfo(3)curs_slk(3)curs_slk(3)curs_slk(3)curs_slk(3)curs_slk(3)curs_slk(3)curs_slk(3)curs_slk(3)curs_slk(3)curs_slk(3)curs_slk(3)curs_slk(3)curs_slk(3)curs_slk(3)curs_slk(3)curs_slk(3)curs_attr(3)curs_attr(3)curs_color(3)curs_pad(3)curs_window(3)curs_window(3)curs_termattrs(3)curs_termattrs(3)curs_termattrs(3)curs_termcap(3)curs_termcap(3)curs_termcap(3)curs_termcap(3)curs_termcap(3)curs_terminfo(3)curs_terminfo(3)curs_terminfo(3)curs_inopts(3)curs_touch(3)curs_touch(3) curs_ter‐
minfo(3)curs_termcap(3)curs_terminfo(3)curs_inopts(3)curs_util(3)curs_get_wch(3)curs_getch(3)curs_getwch(3)curs_touch(3)curs_util(3)curs_terminfo(3)curs_terminfo(3)curs_border(3)curs_border_set(3)curs_printw(3)curs_printw(3)curs_scanw(3)curs_scanw(3)curs_add_wch(3)curs_add_wchstr(3)curs_add_wchstr(3)curs_addch(3)curs_addchstr(3)curs_addchstr(3)curs_addstr(3)curs_addwstr(3)curs_addstr(3)curs_addwch(3)curs_addwchstr(3)curs_addwchstr(3)curs_addwstr(3)curs_attr_get(3)curs_attr_get(3)curs_attr_get(3)curs_attr_get(3)curs_attr(3)curs_attr(3)curs_attr(3)curs_bkgd(3)curs_bkgd(3)curs_bkgrnd(3)curs_bkgrnd(3)curs_border(3) curs_bor‐
der_set(3)curs_chgat(3)curs_clear(3)curs_clear(3)curs_clear(3)curs_attr_get(3)curs_window(3)curs_delch(3)curs_deleteln(3)curs_addch(3)curs_addwch(3)curs_add_wch(3)curs_clear(3)curs_get_wstr(3)curs_get_wch(3)curs_get_wstr(3)curs_getch(3)curs_getstr(3)curs_getwstr(3)curs_bkgrnd(3)curs_getstr(3)curs_getwch(3)curs_getwstr(3)curs_border(3)curs_border_set(3)curs_in_wch(3)curs_in_wchstr(3)curs_in_wchstr(3)curs_inch(3)curs_inchstr(3)curs_inchstr(3)curs_instr(3)curs_inwstr(3)curs_ins_wstr(3)curs_ins_wch(3)curs_ins_wstr(3)curs_insch(3)curs_deleteln(3)curs_deleteln(3)curs_insstr(3)curs_inswstr(3)curs_insstr(3)curs_instr(3)curs_inswch(3)curs_inswstr(3)curs_inwch(3)curs_inwchstr(3)curs_inwchstr(3)curs_inwstr(3)curs_move(3)curs_refresh(3)curs_printw(3)curs_refresh(3)curs_refresh(3)curs_scanw(3)curs_scroll(3)curs_outopts(3)curs_attr(3)curs_attr(3)curs_window(3)curs_window(3)curs_inopts(3)curs_touch(3)curs_util(3)curs_border(3)curs_border_set(3)NOTES
The header file <curses.h> automatically includes the header file
<stdio.h>.
The header files that supply function prototypes and other definitions
for the Curses library support different definition environments for
either X/Open UNIX standard conformance or compatibility with versions
of DIGITAL UNIX earlier than Version 4.0.
The following list names and describes the macros that select these
definition environments: Selects APIs that conform to Version 4.2 of
the X/Open Curses CAE specification and automatically defines
_XOPEN_SOURCE.
These APIs were not available in the Curses library provided by
versions of DIGITAL UNIX earlier than Version 4.0. The
_XOPEN_SOURCE_EXTENDED macro defines the recommended compilation
environment for all new Curses applications. Note that the c89
command defines _XOPEN_SOURCE_EXTENDED by default but the cc
command does not.
There is no difference between _XOPEN_SOURCE_EXTENDED and
_XOPEN_SOURCE=500 with respect to the Curses library. Selects
the APIs that conform to Version 3 of the X/Open Curses CAE
specification.
These APIs were not available in the Curses library provided by
versions of DIGITAL UNIX earlier than Version 4.0. However, as
of Version 4.0, these APIs are defined within the _XOPEN_SOURCE
definition environment to meet the requirements of the X/Open
Curses CAE specification. Selects the System V Multi-National
Language Standard (MNLS) APIs, which are Curses library exten‐
sions for handling multibyte characters.
These APIs were not available in the Curses library provided by
versions of DIGITAL UNIX earlier than Version 4.0. MNLS APIs are
supported only for backward compatibility and are not recom‐
mended for use in new Curses applications. The _OSF_SOURCE def‐
inition environment should be used along with the _XOPEN_SOURCE
environment, so applications can access MNLS extensions along
with generic Curses functions. Do not use the MNLS extensions
with the _XOPEN_SOURCE_EXTENDED definition environment, which
contains a different set of functions for handling multibyte
characters. Selects the BSD Curses APIs.
These APIs were not available in the Curses library provided by
versions of DIGITAL UNIX earlier than Version 4.0. BSD APIs are
supported only for backward compatibility and are not recom‐
mended for use in new Curses applications. The BSD definition
environment is incompatible with all other definition environ‐
ments. Selects the Minicurses APIs.
These APIs were not available in the Curses library provided by
versions of DIGITAL UNIX earlier than Version 4.0. Minicurses
APIs are supported only for backward compatibility and are not
recommended for use in new Curses applications.
Refer to the standards(5) reference page for more information about the
relationship between compilation definition environments and industry
standards.
RETURN VALUES
Unless otherwise noted in the routine descriptions, routines that
return an integer return ERR upon failure and an integer value other
than ERR upon successful completion.
Routines that return pointers return NULL on error.
SEE ALSO
See terminfo(4) and the Section 3 reference pages whose names begin
with “curs_” for detailed routine descriptions.
curses(3)