 |
Index for
Section 3 |
|
 |
Alphabetical
listing for C |
|
 |
Bottom of
page |
|
curses(3)
NAME
curses - Terminal screen-handling and optimization package
SYNOPSIS
c89 [flag...] file -l curses [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 -l curses operand. (The cc command
supports only -lcurses as an operand. The c89 command supports -lcurses in
addition to the space-separated format.) See NOTES for information about
compiling in the different definition environments 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 manipulation;
output to windows and pads; reading terminal input; control over terminal
and Curses input and output options; environment query routines; 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 windows,
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 windows 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 reference
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 window
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 parent
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. Otherwise,
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 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 the
terminfo database. A TERMINAL data structure also contains 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 environment, line and column
information in the environment overrides information read from the terminfo
database. This would affect a program running 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 creation 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/terminfo/w/wyse150. The search path beginning
with $HOME is useful for developing and testing 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 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
destination 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
enhancements. Current attributes of a window are applied to all characters
that are written into the window by waddch, wadd_wch, waddstr, waddchstr,
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 database
and in the window data structure. The effect on a window does not differ
depending on whether the application specifies A_ or WA_ constants. 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 following
operations:
· Scrolling
· Line or character insertion
· Line or character deletion
To the extent possible on a particular terminal, a character's rendition
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 nonspacing
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 nonspacing
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 followed 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 character
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 character,
then its rendition is not used; when it is written to the screen, it uses
the rendition specified by the spacing character already displayed.
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
application provides a cchar_t value that was not initialized in this way.
Window Properties
Windows have the following properties that affect the placing of characters
in the window:
Window Rendition
Each window has a rendition, which is combined with the rendition
component of the window's background property (described next).
Window Background
Each window has a background property. The background 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 position.
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) position
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 character
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 character 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 rendition.
-- 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, wrapping
and scrolling occur under the conditions specified in the preceding 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 position 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 application 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 position.
Deleting Characters
Deletion functions (such as delch) delete the simple or complex character
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 rendition. 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 straddling
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 subwindow 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
situations 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 subwindow,
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 processing
of special characters.
In Curses functions that do not move the cursor based on the information
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 visible 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
character 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 conceptually
convert control characters to the caret (^) character, followed by a second
character (which is an uppercase letter if it is alphabetic), 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 function 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 interval 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
application. Cooked mode achieves the same effect as
canonical-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
processing (with MIN set to 1 and ICRNL cleared) as
specified 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,
whichever 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
noncanonical 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 echoing (most
interactive, screen-oriented programs want this), applications 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. Applications
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 stdscr. 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 functions whose names
begin with the basic name and the window specified 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 operation.
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 discussed
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 function with the basic name is often provided for historical
compatibility and operates only on single-byte characters. A function
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 Y Y Y
Add a wide character and
rendition
[mv][w]add_wch[n]str ? N N
Add an array of wide characters
and renditions
Change Renditions Family
[mv][w]chgat - N N
Change renditions of characters
in a window
Delete Family
[mv][w]delch Delete a character - - N
Get Family (Get Input from
Keyboard 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 Y Y Y
Get an array of wide characters
and key codes
Explicit Cursor Movement Family
[w]move Move the cursor - - -
Input Family (Read Back From
Window)
[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
rendition
[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
processing.
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 reference
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).
add_wch *
curs_add_wch(3)
add_wchnstr *
curs_add_wchstr(3)
add_wchstr *
curs_add_wchstr(3)
addch *
curs_addch(3)
addchnstr *
curs_addchstr(3)
addchstr *
curs_addchstr(3)
addnstr *
curs_addstr(3)
addnwstr *
curs_addwstr(3)
addstr *
curs_addstr(3)
addwch
curs_addwch(3)
addwchnstr
curs_addwchstr(3)
addwchstr
curs_addwchstr(3)
addwstr *
curs_addwstr(3)
attr_get *
curs_attr_get(3)
attr_off *
curs_attr_get(3)
attr_on *
curs_attr_get(3)
attr_set *
curs_attr_get(3)
attroff *
curs_attr(3)
attron *
curs_attr(3)
attrset *
curs_attr(3)
baudrate *
curs_termattrs(3)
beep *
curs_beep(3)
bkgd *
curs_bkgd(3)
bkgdset *
curs_bkgd(3)
bkgrnd *
curs_bkgrnd(3)
bkgrndset *
curs_bkgrnd(3)
border *
curs_border(3)
border_set *
curs_border_set(3)
box *
curs_border(3)
box_set *
curs_border_set(3)
can_change_color *
curs_color(3)
cbreak *
curs_inopts(3)
chgat *
curs_chgat(3)
clear *
curs_clear(3)
clearok *
curs_outopts(3)
clrtobot *
curs_clear(3)
clrtoeol *
curs_clear(3)
color_content *
curs_color(3)
COLOR_PAIR *
curs_color(3)
color_set
curs_attr_get(3)
copywin *
curs_overlay(3)
curs_set *
curs_kernel(3)
def_prog_mode *
curs_kernel(3)
def_shell_mode *
curs_kernel(3)
del_curterm
curs_terminfo(3)
delay_output *
curs_util(3)
delch *
curs_delch(3)
deleteln *
curs_deleteln(3)
delscreen *
curs_initscr(3)
delwin *
curs_window(3)
derwin *
curs_window(3)
doupdate *
curs_refresh(3)
draino
curs_util(3)
dupwin *
curs_window(3)
echo *
curs_inopts(3)
echo_wchar *
curs_add_wch(3)
echochar *
curs_addch(3)
echowchar
curs_addwch(3)
endwin *
curs_initscr(3)
erase *
curs_clear(3)
erasechar *
curs_termattrs(3)
erasewchar *
curs_termattrs(3)
filter *
curs_util(3)
flash *
curs_beep(3)
flushinp *
curs_util(3)
get_wch *
curs_get_wch(3)
get_wstr *
curs_get_wstr(3)
getbegyx *
curs_getyx(3)
getbkgrnd *
curs_bkgrnd(3)
getch *
curs_getch(3)
getcchar *
curs_getcchar(3)
getmaxyx *
curs_getyx(3)
getn_wstr *
curs_get_wstr(3)
getnstr *
curs_getstr(3)
getnwstr
curs_getwstr(3)
getparyx *
curs_getyx(3)
getstr *
curs_getstr(3)
getwch
curs_getwch(3)
getwin *
curs_util(3)
getwstr
curs_getwstr(3)
getyx *
curs_getyx(3)
halfdelay *
curs_inopts(3)
has_colors *
curs_color(3)
has_ic *
curs_termattrs(3)
has_il *
curs_termattrs(3)
hline *
curs_border(3)
hline_set *
curs_border_set(3)
idcok *
curs_outopts(3)
idlok *
curs_outopts(3)
immedok *
curs_outopts(3)
in_wch *
curs_in_wch(3)
in_wchnstr *
curs_in_wchstr(3)
in_wchstr *
curs_in_wchstr(3)
inch *
curs_inch(3)
inchnstr *
curs_inchstr(3)
inchstr *
curs_inchstr(3)
init_color *
curs_color(3)
init_pair *
curs_color(3)
initscr *
curs_initscr(3)
innstr *
curs_instr(3)
innwstr *
curs_inwstr(3)
ins_nwstr *
curs_ins_wstr(3)
ins_wch *
curs_ins_wch(3)
ins_wstr *
curs_ins_wstr(3)
insch *
curs_insch(3)
insdelln *
curs_deleteln(3)
insertln *
curs_deleteln(3)
insnstr *
curs_insstr(3)
insnwstr
curs_inswstr(3)
insstr
curs_insstr(3)
instr
curs_instr(3)
inswch
curs_inswch(3)
inswstr
curs_inswstr(3)
intrflush *
curs_inopts(3)
inwch
curs_inwch(3)
inwchnstr
curs_inwchstr(3)
inwchstr
curs_inwchstr(3)
inwstr *
curs_inwstr(3)
is_linetouched *
curs_touch(3)
is_wintouched *
curs_touch(3)
isendwin *
curs_initscr(3)
key_name *
curs_util(3)
keyname *
curs_util(3)
keypad *
curs_inopts(3)
killchar *
curs_termattrs(3)
leaveok *
curs_outopts(3)
longname *
curs_termattrs(3)
meta *
curs_inopts(3)
move *
curs_move(3)
mvadd_wch *
curs_add_wch(3)
mvadd_wchnstr *
curs_add_wchstr(3)
mvadd_wchstr *
curs_add_wchstr(3)
mvaddch *
curs_addch(3)
mvaddchnstr *
curs_addchstr(3)
mvaddchstr *
curs_addchstr(3)
mvaddnstr *
curs_addstr(3)
mvaddnwstr *
curs_addwstr(3)
mvaddstr *
curs_addstr(3)
mvaddwch
curs_addwch(3)
mvaddwchnstr
curs_addwchstr(3)
mvaddwchstr
curs_addwchstr(3)
mvaddwstr *
curs_addwstr(3)
mvchgat *
curs_chgat(3)
mvcur *
curs_terminfo(3)
mvdelch *
curs_delch(3)
mvderwin *
curs_window(3)
mvget_wch *
curs_get_wch(3)
mvget_wstr *
curs_get_wstr(3)
mvgetch *
curs_getch(3)
mvgetn_wstr *
curs_get_wstr(3)
mvgetnstr *
curs_getstr(3)
mvgetnwstr
curs_getwstr(3)
mvgetstr *
curs_getstr(3)
mvgetwch
curs_getwch(3)
mvgetwstr
curs_getwstr(3)
mvhline *
curs_border(3)
mvhline_set *
curs_border_set(3)
mvin_wch *
curs_in_wch(3)
mvin_wchnstr *
curs_in_wchstr(3)
mvin_wchstr *
curs_in_wchstr(3)
mvinch *
curs_inch(3)
mvinchnstr *
curs_inchstr(3)
mvinchstr *
curs_inchstr(3)
mvinnstr *
curs_instr(3)
mvinnwstr *
curs_inwstr(3)
mvins_nwstr *
curs_ins_wstr(3)
mvins_wch *
curs_ins_wch(3)
mvinsch *
curs_insch(3)
mvinsnstr *
curs_insstr(3)
mvinsnwstr
curs_inswstr(3)
mvinsstr *
curs_insstr(3)
mvinstr *
curs_instr(3)
mvinswch
curs_inswch(3)
mvinswstr
curs_inswstr(3)
mvinwch
curs_inwch(3)
mvinwchnstr
curs_inwchstr(3)
mvinwchstr
curs_inwchstr(3)
mvinwstr *
curs_inwstr(3)
mvprintw *
curs_printw(3)
mvscanw *
curs_scanw(3)
mvvline *
curs_border(3)
mvvline_set *
curs_border_set(3)
mvwadd_wch *
curs_add_wch(3)
mvwadd_wchnstr *
curs_add_wchstr(3)
mvwadd_wchstr *
curs_add_wchstr(3)
mvwaddch *
curs_addch(3)
mvwaddchnstr *
curs_addchstr(3)
mvwaddchstr *
curs_addchstr(3)
mvwaddnstr *
curs_addstr(3)
mvwaddnwstr *
curs_addwstr(3)
mvwaddstr *
curs_addstr(3)
mvwaddwch
curs_addwch(3)
mvwaddwchnstr
curs_addwchstr(3)
mvwaddwchstr
curs_addwchstr(3)
mvwaddwstr
curs_addwstr(3)
mvwchgat *
curs_chgat(3)
mvwdelch *
curs_delch(3)
mvwget_wch *
curs_get_wch(3)
mvwget_wstr *
curs_get_wstr(3)
mvwgetch *
curs_getch(3)
mvwgetn_wstr *
curs_get_wstr(3)
mvwgetnstr *
curs_getstr(3)
mvwgetnwstr
curs_getwstr(3)
mvwgetstr *
curs_getstr(3)
mvwgetwch
curs_getwch(3)
mvwgetwstr
curs_getwstr(3)
mvwhline *
curs_border(3)
mvwhline_set *
curs_border_set(3)
mvwin *
curs_window(3)
mvwin_wch *
curs_in_wch(3)
mvwin_wchnstr *
curs_in_wchstr(3)
mvwin_wchstr *
curs_in_wchstr(3)
mvwinch *
curs_inch(3)
mvwinchnstr *
curs_inchstr(3)
mvwinchstr *
curs_inchstr(3)
mvwinnstr *
curs_instr(3)
mvwinnwstr *
curs_inwstr(3)
mvwins_nwstr *
curs_ins_wstr(3)
mvwins_wch *
curs_ins_wch(3)
mvwins_wstr *
curs_ins_wstr(3)
mvwinsch *
curs_insch(3)
mvwinsnstr *
curs_insstr(3)
mvwinsstr *
curs_insstr(3)
mvwinstr *
curs_instr(3)
mvwinswch
curs_inswch(3)
mvwinswstr
curs_inswstr(3)
mvwinwch
curs_inwch(3)
mvwinwchnstr
curs_inwchstr(3)
mvwinwchstr
curs_in_wchstr(3)
mvwinwstr *
curs_inwstr(3)
mvwprintw *
curs_printw(3)
mvwscanw *
curs_scanw(3)
mvwvline *
curs_border(3)
mvwvline_set *
curs_border_set(3)
napms *
curs_kernel(3)
newpad *
curs_pad(3)
newterm *
curs_initscr(3)
newwin *
curs_window(3)
nl *
curs_outopts(3)
nocbreak *
curs_inopts(3)
nodelay *
curs_inopts(3)
noecho *
curs_inopts(3)
nonl *
curs_outopts(3)
noqiflush *
curs_inopts(3)
noraw *
curs_inopts(3)
notimeout *
curs_inopts(3)
overlay *
curs_overlay(3)
overwrite *
curs_overlay(3)
pair_content *
curs_color(3)
PAIR_NUMBER *
curs_color(3)
pechochar *
curs_pad(3)
pecho_wchar *
curs_pad(3)
pechowchar
curs_pad(3)
pnoutrefresh *
curs_pad(3)
prefresh *
curs_pad(3)
printw *
curs_printw(3)
putp *
curs_terminfo(3)
putwin *
curs_util(3)
qiflush *
curs_inopts(3)
raw *
curs_inopts(3)
redrawwin *
curs_refresh(3)
refresh *
curs_refresh(3)
reset_prog_mode *
curs_kernel(3)
reset_shell_mode *
curs_kernel(3)
resetty *
curs_kernel(3)
restartterm *
curs_terminfo(3)
ripoffline *
curs_kernel(3)
savetty *
curs_kernel(3)
scanw *
curs_scanw(3)
scr_dump *
curs_scr_dump(3)
scr_init *
curs_scr_dump(3)
scr_restore *
curs_scr_dump(3)
scr_set *
curs_scr_dump(3)
scrl *
curs_scroll(3)
scroll *
curs_scroll(3)
scrollok *
curs_outopts(3)
setcchar *
curs_getcchar(3)
set_curterm *
curs_terminfo(3)
set_term *
curs_initscr(3)
setscrreg *
curs_outopts(3)
setupterm *
curs_terminfo(3)
slk_attroff *
curs_slk(3)
slk_attr_off *
curs_slk(3)
slk_attron *
curs_slk(3)
slk_attr_on *
curs_slk(3)
slk_attrset *
curs_slk(3)
slk_attr_set *
curs_slk(3)
slk_clear *
curs_slk(3)
slk_color
curs_slk(3)
slk_init *
curs_slk(3)
slk_label *
curs_slk(3)
slk_noutrefresh *
curs_slk(3)
slk_refresh *
curs_slk(3)
slk_restore *
curs_slk(3)
slk_set *
curs_slk(3)
slk_touch *
curs_slk(3)
slk_wset *
curs_slk(3)
standend *
curs_attr(3)
standout *
curs_attr(3)
start_color *
curs_color(3)
subpad *
curs_pad(3)
subwin *
curs_window(3)
syncok *
curs_window(3)
term_attrs
curs_termattrs(3)
termattrs *
curs_termattrs(3)
termname *
curs_termattrs(3)
tgetent *
curs_termcap(3)
tgetflag *
curs_termcap(3)
tgetnum *
curs_termcap(3)
tgetstr *
curs_termcap(3)
tgoto *
curs_termcap(3)
tigetflag *
curs_terminfo(3)
tigetnum *
curs_terminfo(3)
tigetstr *
curs_terminfo(3)
timeout *
curs_inopts(3)
touchline *
curs_touch(3)
touchwin *
curs_touch(3)
tparm *
curs_terminfo(3)
tputs *
curs_termcap(3)
tputs *
curs_terminfo(3)
typeahead *
curs_inopts(3)
unctrl *
curs_util(3)
unget_wch *
curs_get_wch(3)
ungetch *
curs_getch(3)
ungetwch
curs_getwch(3)
untouchwin *
curs_touch(3)
use_env *
curs_util(3)
vidattr *
curs_terminfo(3)
vidputs *
curs_terminfo(3)
vline *
curs_border(3)
vline_set *
curs_border_set(3)
vw_printw *
curs_printw(3)
vwprintw *
curs_printw(3)
vw_scanw *
curs_scanw(3)
vwscanw *
curs_scanw(3)
wadd_wch *
curs_add_wch(3)
wadd_wchnstr *
curs_add_wchstr(3)
wadd_wchstr *
curs_add_wchstr(3)
waddch *
curs_addch(3)
waddchnstr *
curs_addchstr(3)
waddchstr *
curs_addchstr(3)
waddnstr *
curs_addstr(3)
waddnwstr
curs_addwstr(3)
waddstr *
curs_addstr(3)
waddwch
curs_addwch(3)
waddwchnstr
curs_addwchstr(3)
waddwchstr
curs_addwchstr(3)
waddwstr
curs_addwstr(3)
wattr_get *
curs_attr_get(3)
wattr_off *
curs_attr_get(3)
wattr_on *
curs_attr_get(3)
wattr_set *
curs_attr_get(3)
wattroff *
curs_attr(3)
wattron *
curs_attr(3)
wattrset *
curs_attr(3)
wbkgd *
curs_bkgd(3)
wbkgdset *
curs_bkgd(3)
wbkgrnd *
curs_bkgrnd(3)
wbkgrndset *
curs_bkgrnd(3)
wborder *
curs_border(3)
wborder_set *
curs_border_set(3)
wchgat *
curs_chgat(3)
wclear *
curs_clear(3)
wclrtobot *
curs_clear(3)
wclrtoeol *
curs_clear(3)
wcolor_set
curs_attr_get(3)
wcursyncup *
curs_window(3)
wdelch *
curs_delch(3)
wdeleteln *
curs_deleteln(3)
wechochar *
curs_addch(3)
wechowchar
curs_addwch(3)
wecho_wchar *
curs_add_wch(3)
werase *
curs_clear(3)
wgetn_wstr *
curs_get_wstr(3)
wget_wch *
curs_get_wch(3)
wget_wstr *
curs_get_wstr(3)
wgetch *
curs_getch(3)
wgetnstr *
curs_getstr(3)
wgetnwstr
curs_getwstr(3)
wgetbkgrnd *
curs_bkgrnd(3)
wgetstr *
curs_getstr(3)
wgetwch
curs_getwch(3)
wgetwstr
curs_getwstr(3)
whline *
curs_border(3)
whline_set *
curs_border_set(3)
win_wch *
curs_in_wch(3)
win_wchnstr *
curs_in_wchstr(3)
win_wchstr *
curs_in_wchstr(3)
winch *
curs_inch(3)
winchnstr *
curs_inchstr(3)
winchstr *
curs_inchstr(3)
winnstr *
curs_instr(3)
winnwstr *
curs_inwstr(3)
wins_nwstr *
curs_ins_wstr(3)
wins_wch *
curs_ins_wch(3)
wins_wstr *
curs_ins_wstr(3)
winsch *
curs_insch(3)
winsdelln *
curs_deleteln(3)
winsertln *
curs_deleteln(3)
winsnstr *
curs_insstr(3)
winsnwstr
curs_inswstr(3)
winsstr *
curs_insstr(3)
winstr *
curs_instr(3)
winswch
curs_inswch(3)
winswstr
curs_inswstr(3)
winwch
curs_inwch(3)
winwchnstr
curs_inwchstr(3)
winwchstr
curs_inwchstr(3)
winwstr *
curs_inwstr(3)
wmove *
curs_move(3)
wnoutrefresh *
curs_refresh(3)
wprintw *
curs_printw(3)
wredrawln *
curs_refresh(3)
wrefresh *
curs_refresh(3)
wscanw *
curs_scanw(3)
wscrl *
curs_scroll(3)
wsetscrreg *
curs_outopts(3)
wstandend *
curs_attr(3)
wstandout *
curs_attr(3)
wsyncdown *
curs_window(3)
wsyncup *
curs_window(3)
wtimeout *
curs_inopts(3)
wtouchln *
curs_touch(3)
wunctrl *
curs_util(3)
wvline *
curs_border(3)
wvline_set *
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:
_XOPEN_SOURCE_EXTENDED
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.
_XOPEN_SOURCE
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.
_OSF_SOURCE
Selects the System V Multi-National Language Standard (MNLS) APIs,
which are Curses library extensions 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 recommended for
use in new Curses applications. The _OSF_SOURCE definition 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.
_BSD
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 recommended for
use in new Curses applications. The BSD definition environment is
incompatible with all other definition environments.
MINICURSES
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.
|
Index for
Section 3 |
|
|
Alphabetical
listing for C |
|
 |
Top of
page |
|