svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
curses(3xcurses)
X/Open Curses Library Functions curses(3XCURSES)
NAME
curses - introduction and overview of X/Open Curses
DESCRIPTION
The Curses screen management package conforms fully with Issue 4, Ver‐
sion 2 of the X/Open Curses specification. It provides a set of inter‐
nationalized functions and macros for creating and modifying input and
output to a terminal screen. This includes functions for creating win‐
dows, highlighting text, writing to the screen, reading from user
input, and moving the cursor.
X/Open Curses is a terminal-independent package, providing a common
user interface to a variety of terminal types. Its portability is
facilitated by the Terminfo database which contains a compiled defini‐
tion of each terminal type. By referring to the database information
X/Open Curses gains access to low-level details about individual termi‐
nals.
X/Open Curses tailors its activities to the terminal type specified by
the TERM environment variable. The TERM environment variable may be set
in the Korn Shell (see ksh(1)) by typing:
export TERM=terminal_name
To set environment variables using other command line interfaces or
shells, see the environ(7) manual page.
Three additional environment variables are useful, and can be set in
the Korn Shell:
1. If you have an alternate Terminfo database containing termi‐
nal types that are not available in the system default data‐
base /usr/share/lib/terminfo, you can specify the TERMINFO
environment variable to point to this alternate database:
export TERMINFO=path
This path specifies the location of the alternate compiled
Terminfo database whose structure consists of directory
names 0 to 9 and a to z (which represent the first letter of
the compiled terminal definition file name).
The alternate database specified by TERMINFO is examined
before the system default database. If the terminal type
specified by TERM cannot be found in either database, the
default terminal type dumb is assumed.
2. To specify a window width smaller than your screen width
(for example, in situations where your communications line
is slow), set the COLUMNS environment variable to the number
of vertical columns you want between the left and right mar‐
gins:
export COLUMNS=number
The number of columns may be set to a number smaller than
the screen size; however, if set larger than the screen or
window width, the results are undefined.
The value set using this environment variable takes prece‐
dence over the value normally used for the terminal.
3. To specify a window height smaller than your current screen
height (for example, in situations where your communications
line is slow), override the LINES environment variable by
setting it to a smaller number of horizontal lines:
export LINES=number
The number of lines may be set to a number smaller than the
screen height; however, if set larger than the screen or
window height, the results are undefined.
The value set using this environment variable takes prece‐
dence over the value normally used for the terminal.
Data Types
X/Open Curses defines the following data types:
attr_t An integral type that holds an OR-ed set of attributes. The
attributes acceptable are those which begin with the WA_
prefix.
bool Boolean data type.
cchar_t A type that refers to a string consisting of a spacing wide
character, up to 5 non-spacing wide characters, and zero or
more attributes of any type. See Attributes, Color Pairs,
and Renditions(). A null cchar_t object terminates arrays
of cchar_t objects.
chtype An integral type whose values are formed by OR-ing an
"unsigned char" with a color pair. and with zero or more
attributes. The attributes acceptable are those which begin
with the A_ prefix and COLOR_PAIR(3XCURSES)
SCREEN An opaque data type associated with a terminal's display
screen.
TERMINAL An opaque data type associated with a terminal. It contains
information about the terminal's capabilities (as defined
by terminfo), the terminal modes, and current state of
input/output operations.
wchar_t An integral data type whose values represent wide charac‐
ters.
WINDOW An opaque data type associated with a window.
Screens, Windows, and Terminals
The X/Open Curses manual pages refer at various points to screens, win‐
dows (also subwindows, derived windows, and pads), and terminals. The
following list defines each of these terms.
Screen A screen is a terminal's physical output device. The SCREEN
data type is associated with a terminal.
Window Window objects are two-dimensional arrays of characters and
their renditions. X/Open Curses provides stdscr, a default
window which is the size of of the terminal screen. You can
use the newwin(3XCURSES) function to create others.
To refer to a window, use a variable declared as WINDOW *. X/Open
Curses includes both functions that modify stdscr, and more general
versions that let you specify a window.
There are three sub-types of windows:
Subwindow A window which has been created within another window
(the parent window) and whose position has been spec‐
ified with absolute screen coordinates. The der‐
win(3XCURSES) and subwin(3XCURSES) functions can be
used to create subwindows.
Derived Window A subwindow whose position is defined relative to the
parent window's coordinates rather than in absolute
terms.
Pad A special type of window that can be larger than the
screen. For more information, see the new‐
pad(3XCURSES) man page.
Terminal A terminal is the input and output device which char‐
acter-based applications use to interact with the
user. The TERMINAL data type is associated with such
a device.
Attributes, Color Pairs, and Renditions
A character's rendition consists of its attributes (such as underlining
or reverse video) and its color pair (the foreground and background
colors). When using waddstr(3XCURSES), waddchstr(3XCURSES),
wprintw(3XCURSES), winsch(3XCURSES), and so on, the window's rendition
is combined with that character's renditions. The window rendition is
the attributes and color set using the attroff(3XCURSES) and
attr_off(3XCURSES) sets of functions. The window's background character
and rendition are set with the bkgdset(3XCURSES) and bkgrnd‐
set(3XCURSES) sets of functions.
When spaces are written to the screen, the background character and
window rendition replace the space. For example, if the background ren‐
dition and character is A_UNDERLINE|'*', text written to the window
appears underlined and the spaces appear as underlined asterisks.
Each character written retains the rendition that it has obtained. This
allows the character to be copied "as is" to or from a window with the
addchstr(3XCURSES) or inch(3XCURSES) functions.
A_ Constant Values for Attributes
You can specify Attributes, Color Pairs, and Renditions() attributes
using the constants listed in the tables below. The following constants
modify objects of type chtype:
tab() box; lw(2.75i) lw(2.75i) lw(2.75i) lw(2.75i) ConstantDescription
_ A_ALTCHARSETAlternate character set A_ATTRIBUTESBit-mask to extract
attributes A_BLINKBlinking A_BOLDBold A_CHARTEXTBit-mask to extract a
character A_COLORT{ Bit-mask to extract color-pair information T}
A_DIMHalf-bright A_INVISInvisible A_PROTECTProtected A_REVERSEReverse
video A_STANDOUTHighlights specific to terminal A_UNDERLINEUnderline
WA_ Constant Values for Attributes
The following constants modify objects of type attr_t:
tab() box; lw(2.75i) lw(2.75i) lw(2.75i) lw(2.75i) ConstantDescription
_ WA_ALTCHARSETAlternate character set WA_ATTRIBUTESAttribute mask
WA_BLINKBlinking WA_BOLDBold WA_DIMHalf-bright WA_HORIZONTALHorizontal
highlight WA_INVISInvisible WA_LEFTLeft highlist WA_LOWLow highlist
WA_PROTECTProtected WA_REVERSEReverse video WA_RIGHTRight highlight
WA_STANDOUTHighlights specific to terminal WA_TOPTop highlight
WA_UNDERLINEUnderline WA_VERTICALVertical highlight
Color Macros
Colors always appear in pairs; the foreground color of the character
itself and the background color of the field on which it is displayed.
The following color macros are defined:
tab() box; lw(2.75i) lw(2.75i) lw(2.75i) lw(2.75i) MacroDescription _
COLOR_BLACKBlack COLOR_BLUEBlue COLOR_GREENGreen COLOR_CYANCyan
COLOR_REDRed COLOR_MAGENTAMagenta COLOR_YELLOWYellow COLOR_WHITEWhite
Together, a character's attributes and its color pair form the charac‐
ter's rendition. A character's rendition moves with the character dur‐
ing any scrolling or insert/delete operations. If your terminal lacks
support for the specified rendition, X/Open Curses may substitute a
different rendition.
The COLOR_PAIR(3XCURSES) function modifies a chtype object. The
PAIR_NUMBER(3XCURSES) function extracts the color pair from a chtype
object.
Functions for Modifying a Window's Color
The following functions modify a window's color:
tab() box; lw(2.75i) lw(2.75i) lw(2.75i) lw(2.75i) FunctionDescription
_ attr_set(), wattr_set()Change the window's rendition. color_set(),
wcolor_set()Set the window's color
Non-Spacing Characters
When the wcwidth(3C) function returns a width of zero for a character,
that character is called a non-spacing character. Non-spacing charac‐
ters can be written to a window. Each non-spacing character is associ‐
ated with a spacing character (that is, one which does not have a width
of zero) and modifies that character. You cannot address a non-spacing
character directly. Whenever you perform an X/Open Curses operation on
the associated character, you are implicitly addressing the non-spacing
character.
Non-spacing characters do not have a rendition. For functions that use
wide characters and a rendition, X/Open Curses ignores any rendition
specified for non-spacing characters. Multi-column characters have one
rendition that applies to all columns spanned.
Complex Characters
The cchar_t date type represents a complex character. A complex charac‐
ter may contain a spacing character, its associated non-spacing charac‐
ters, and its rendition. This implementation of complex characters sup‐
ports up to 5 non-spacing characters for each spacing character.
When a cchar_t object representing a non-spacing complex character is
written to the screen, its rendition is not used, but rather it becomes
associated with the rendition of the existing character at that loca‐
tion. The setcchar(3XCURSES) function initializes an object of type
cchar_t. The getcchar(3XCURSES) function extracts the contents of a
cchar_t object.
Display Operations
In adding internationalization support to X/Open Curses, every attempt
was made to minimize the number of changes to the historical CURSES
package. This enables programs written to use the historical implemen‐
tation of CURSES to use the internationalized version with little or no
modification. The following rules apply to the internationalized X/Open
Curses package:
o The cursor can be placed anywhere in the window. Window and
screen origins are (0,0).
o A multi-column character cannot be displayed in the last
column, because the character would appear truncated.
Instead, the background character is displayed in the last
column and the multi-column character appears at the begin‐
ning of the next line. This is called wrapping.
If the original line is the last line in the scroll region
and scrolling is enabled, X/Open Curses moves the contents
of each line in the region to the previous line. The first
line of the region is lost. The last line of the scrolling
region contains any wrapped characters. The remainder of
that line is filled with the background character. If
scrolling is disabled, X/Open Curses truncates any character
that would extend past the last column of the screen.
o Overwrites operate on screen columns. If displaying a sin‐
gle-column or multi-column character results in overwriting
only a portion of a multi-column character or characters,
background characters are displayed in place of the non-
overwritten portions.
o Insertions and deletions operate on whole characters. The
cursor is moved to the first column of the character prior
to performing the operation.
Overlapping Windows
When windows overlap, it may be necessary to overwrite only part of a
multi-column character. As mentioned earlier, the non-overwritten por‐
tions are replaced with the background character. This results in
issues concerning the overwrite(3XCURSES), overlay(3XCURSES), copy‐
win(3XCURSES), wnoutrefresh(3XCURSES), and wrefresh(3XCURSES) func‐
tions.
Special Characters
Some functions assign special meanings to certain special characters:
Backspace Moves the cursor one column toward the beginning
of the line. If the cursor was already at the
beginning of the line, it remains there. All sub‐
sequent characters are added or inserted at this
point.
Carriage Return Moves the cursor to the beginning of the current
line. If the cursor was already at the beginning
of the line, it remains there. All subsequent
characters are added or inserted at this point.
Newline When adding characters, X/Open Curses fills the
remainder of the line with the background charac‐
ter (effectively truncating the newline) and
scrolls the window as described earlier. All sub‐
sequent characters are inserted at the start of
the new line.
When inserting characters, X/Open Curses fills
the remainder of the line with the background
character (effectively truncating the line),
moves the cursor to the beginning of a new line,
and scrolls the window as described earlier. All
subsequent characters are placed at the start of
the new line.
Tab moves subsequent characters to next horizontal
tab strop. Default tab stops are set at 0, 8, 16,
and so on.
When adding or inserting characters, X/Open
Curses inserts or adds the background character
into each column until the next tab stop is
reached. If there are no remaining tab stops on
the current line, wrapping and scrolling occur as
described earlier.
Control Characters When X/Open Curses functions perform special
character processing, they convert control char‐
acters to the ^X notation, where X is a single-
column character (uppercase, if it is a letter)
and writes that notation to the window. Functions
that retrieve text from the window will retrieve
the converted notation not the original.
X/Open Curses displays non-printable bytes, that have their high bit
set, using the M-X meta notation where X is the non-printable byte with
its high bit turned off.
Input Processing
There are four input modes possible with X/Open Curses that affect the
behavior of input functions like getch(3XCURSES) and getnstr(3XCURSES).
Line Canonical (Cooked) In line input mode, the terminal driver han‐
dles the input of line units as well as SIG‐
ERASE and SIGKILL character processing. See
termio(4I) for more information.
In this mode, the getch() and getnstr()
functions will not return until a complete
line has been read by the terminal driver,
at which point only the requested number of
bytes/characters are returned. The rest of
the line unit remains unread until subse‐
quent call to the getch() or getnstr() func‐
tions.
The functions nocbreak(3XCURSES) and
noraw(3XCURSES) are used to enter this mode.
These functions are described on the
cbreak(3XCURSES) man page which also details
which termios flags are enabled.
Of the modes available, this one gives
applications the least amount of control
over input. However, it is the only input
mode possible on a block mode terminal.
cbreak Mode Byte/character input provides a finer degree
of control. The terminal driver passes each
byte read to the application without inter‐
preting erase and kill characters. It is the
application's responsibility to handle line
editing. It is unknown whether the signal
characters (SIGINTR, SIGQUIT, SIGSUSP) and
flow control characters (SIGSTART, SIGSTOP)
are enabled. To ensure that they are, call
the noraw() function first, then call the
cbreak() function.
halfdelay Mode This is the same as the cbreak() mode with a
timeout. The terminal driver waits for a
byte to be received or for a timer to
expire, in which case the getch() function
either returns a byte or ERR respectively.
This mode overrides timeouts set for an
individual window with the wtimeout() func‐
tion.
raw Mode This mode provides byte/character input with
the most control for an application. It is
similar to cbreak() mode, but also disables
signal character processing (SIGINTR, SIG‐
SUSP, SIGQUIT) and flow control processing
(SIGSTART, SIGSTOP) so that the application
can process them as it wants.
These modes affect all X/Open Curses input. The default input mode is
inherited from the parent process when the application starts up.
A timeout similar to halfdelay(3XCURSES) can be applied to individual
windows (see timeout(3XCURSES)). The nodelay(3XCURSES) function is
equivalent to setting wtimeout(3XCURSES) for a window with a zero time‐
out (non-blocking) or infinite delay (blocking).
To handle function keys, keypad(3XCURSES) must be enabled. When it is
enabled, the getch() function returns a KEY_ constant for a uniquely
encoded key defined for that terminal. When keypad() is disabled, the
getch() function returns the individual bytes composing the function
key (see getch(3XCURSES) and wget_wch(3XCURSES)). By default, keypad()
is disabled.
When processing function keys, once the first byte is recognized, a
timer is set for each subsequent byte in the sequence. If any byte in
the function key sequence is not received before the timer expires, the
bytes already received are pushed into a buffer and the original first
byte is returned. Subsequent X/Open Curses input would take bytes from
the buffer until exhausted, after which new input from the terminal
will be requested. Enabling and disabling of the function key interbyte
timer is handled by the notimeout(3XCURSES) function. By default,
notimeout() is disabled (that is, the timer is used).
X/Open Curses always disables the terminal driver's echo processing.
The echo(3XCURSES) and noecho(3XCURSES) functions control X/Open Curses
software echoing. When software echoing is enabled, X/Open Curses input
functions echo printable characters, control keys, and meta keys in the
input window at the last cursor position. Functions keys are never
echoed. When software echoing is disabled, it is the application's
responsibility to handle echoing.
EXAMPLES
Example 1 Copying Single-Column Characters Over Single-Column Charac‐
ters
In the upcoming examples, some characters have special meanings:
o {, [, and ( represent the left halves of multi-column char‐
acters. }, ], and ) represent the corresponding right halves
of the same multi-column characters.
o Alphanumeric characters and periods (.) represent single-
column characters.
o The number sign (#) represents the background character.
copywin(s, t, 0, 1, 0, 1, 1, 3, 0)
s t → t
abcdef ...... .bcd..
ghijkl ...... .hij..
There are no special problems with this situation.
Example 2 Copying Multi-column Characters Over Single-Column Characters
copywin(s, t, 0, 1, 0, 1, 1, 3, 0)
s t → t
a[]def ...... .[]d..
gh()kl ...... .h()..
There are no special problems with this situation.
Example 3 Copying Single-Column Characters From Source Overlaps Multi-
column Characters In Target
copywin(s, t, 0, 1, 0, 1, 1, 3, 0)
s t → t
abcdef [].... #bcd..
ghijk tol ...(). .hij#.
Overwriting multi-column characters in t has resulted in the # back‐
ground characters being required to erase the remaining halves of the
target's multi-column characters.
Example 4 Copy Incomplete Multi-column Characters From Source To Tar‐
get.
copywin(s, t, 0, 1, 0, 1, 1, 3, 0)
s t → t
[]cdef 123456 []cd56
ghi()l 789012 7hi()2
The ] and ( halves of the multi-column characters have been copied from
the source and expanded in the target outside of the specified target
region.
Consider a pop-up dialog box that contains single-column characters and
a base window that contains multi-column characters and you do the fol‐
lowing:
save=dupwin(dialog); /* create backing store */
overwrite(cursor, save); /* save region to be overlayed */
wrefresh(dialog); /* display dialog */
wrefresh(save); /* restore screen image */
delwin(save); /* release backing store */
You can use code similar to this to implement generic popup() and pop‐
down() routines in a variety of CURSES implementations (including BSD
UNIX, and UNIX System V). In the simple case where the base window con‐
tains single-column characters only, it would correctly restore the
image that appeared on the screen before the dialog box was displayed.
However, with multi-column characters, the overwrite() function might
save a region with incomplete multi-column characters. The wre‐
fresh(dialog) statement results in the behavior described in example 3
above. The behavior described in this example (that is, example 4)
allows the wrefresh(save) statement to restore the window correctly.
Example 5 Copying An Incomplete Multi-column Character To Region Next
To Screen Margin (Not A Window Edge)
Two cases of copying an incomplete multi-column character to a region
next to a screen margin follow:
copywin(s, t, 0, 1, 0, 0, 1, 2, 0)
s t → t
[]cdef 123456 #cd456
ghijkl 789012 hij012
The background character (#) replaces the ] character that would have
been copied from the source, because it is not possible to expand the
multi-column character to its complete form.
copywin(s, t, 0, 1, 0, 3, 1, 5, 0)
s t → t
abcdef 123456 123bcd
ghi()l 789012 789hi#
This second example is the same as the first, but with the right mar‐
gin.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelUnsafe _ Stan‐
dardSee standards(7).
SEE ALSO
cbreak(3XCURSES), wprintw(3XCURSES), ksh(1), wcwidth(3C), key‐
pad(3XCURSES), overlay(3XCURSES), COLOR_PAIR(3XCURSES), PAIR_NUM‐
BER(3XCURSES), addchstr(3XCURSES), attr_off(3XCURSES),
attroff(3XCURSES), bkgdset(3XCURSES), bkgrndset(3XCURSES), copy‐
win(3XCURSES), derwin(3XCURSES), echo(3XCURSES), getcchar(3XCURSES),
getch(3XCURSES), getnstr(3XCURSES), halfdelay(3XCURSES),
inch(3XCURSES), libcurses(3XCURSES), newpad(3XCURSES),
newwin(3XCURSES), nocbreak(3XCURSES), nodelay(3XCURSES), noe‐
cho(3XCURSES), noraw(3XCURSES), notimeout(3XCURSES), over‐
write(3XCURSES), setcchar(3XCURSES), subwin(3XCURSES), time‐
out(3XCURSES), waddchstr(3XCURSES), waddstr(3XCURSES),
wget_wch(3XCURSES), winsch(3XCURSES), wnoutrefresh(3XCURSES), wre‐
fresh(3XCURSES), wtimeout(3XCURSES), termio(4I), attributes(7), envi‐
ron(7), standards(7)
Oracle Solaris 11.4 11 May 2021 curses(3XCURSES)