curses
- CRT screen handling and optimization package
Synopsis
cc [ flag... ] file.. .–lcurses [ library... ]
#include <curses.h>
Description
The curses library routines give the user a terminal-independent method of updating
character screens with reasonable optimization.
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 access; and access to low-level curses routines.
To initialize the routines, the routine initscr() or newterm() must be called
before any of the other routines that deal with windows and screens
are used. The routine endwin() must be called before exiting. To get
character-at-a-time input without echoing (most interactive, screen oriented programs want this), the following
sequence should be used:
initscr,cbreak,noecho;
Most programs would additionally use the sequence:
nonl,intrflush(stdscr,FALSE),keypad(stdscr,TRUE);
Before a curses program is run, the tab stops of the terminal
should be set and its initialization strings, if defined, must be output.
This can be done by executing the tput init command after the shell
environment variable TERM has been exported. (See terminfo(4) for further details.)
The curses library permits manipulation of data structures, called windows, which can
be thought of as two-dimensional arrays of characters representing all or part
of a CRT screen. A default window called stdscr, which is the
size of the terminal screen, is supplied. Others may be created with
newwin(3CURSES).
Windows are referred to by variables declared as WINDOW *. These data structures
are manipulated with routines described on 3CURSES pages (whose names begin "curs_").
Among which the most basic routines are move(3CURSES) and addch(3CURSES). More general
versions of these routines are included with names beginning with w, allowing
the user to specify a window. The routines not beginning with w affect
stdscr.
After using routines to manipulate a window, refresh(3CURSES) is called, telling curses
to make the user's CRT screen look like stdscr. The characters in
a window are actually of type chtype, (character and attribute data) so
that other information about the character may also be stored with each
character.
Special windows called pads may also be manipulated. These are windows which
are not constrained to the size of the screen and whose contents
need not be completely displayed. See curs_pad(3CURSES) for more information.
In addition to drawing characters on the screen, video attributes and colors
may be included, causing the characters to show up in such modes
as underlined, in reverse video, or in color on terminals that support
such display enhancements. Line drawing characters may be specified to be output.
On input, curses is also able to translate arrow and function keys that
transmit escape sequences into single values. The video attributes, line drawing characters,
and input values use names, defined in <curses.h>, such as A_REVERSE,
ACS_HLINE, and KEY_LEFT.
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 will override information read by terminfo. This would effect a
program running in an AT&T 630 layer, for example, where the size
of a screen is changeable.
If the environment variable TERMINFO is defined, any program using curses checks
for a local terminal definition before checking in the standard place. For
example, if TERM is set to att4424, then the compiled terminal definition is
found in
/usr/share/lib/terminfo/a/att4424.
(The `a' is copied from the first letter of att4424 to avoid
creation of huge directories.) However, if TERMINFO is set to $HOME/myterms, curses
first checks
$HOME/myterms/a/att4424,
and if that fails, it then checks
/usr/share/lib/terminfo/a/att4424.
This is useful for developing experimental definitions or when write permission in
/usr/share/lib/terminfo is not available.
The integer variables LINES and COLS are defined in <curses.h> and will
be filled in by initscr with the size of the screen. The
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 can be used in only a few routines.
International Functions
The number of bytes and the number of columns to hold a
character from the supplementary character set is locale-specific (locale category LC_CTYPE) and
can be specified in the character class table.
For editing, operating at the character level is entirely appropriate. For screen
formatting, arbitrary movement of characters on screen is not desirable.
Overwriting characters (addch, for example) operates on a screen level. Overwriting a
character by a character that requires a different number of columns may
produce orphaned columns. These orphaned columns are filled with background characters.
Inserting characters (insch, for example) operates on a character level (that is,
at the character boundaries). The specified character is inserted right before the
character, regardless of which column of a character the cursor points to.
Before insertion, the cursor position is adjusted to the first column of the
character.
As with inserting characters, deleting characters (delch, for example) operates on a
character level (that is, at the character boundaries). The character at the
cursor is deleted whichever column of the character the cursor points to.
Before deletion, the cursor position is adjusted to the first column of the
character.
A multi-column character cannot be put on the last column of a
line. When such attempts are made, the last column is set to
the background character. In addition, when such an operation creates orphaned columns,
the orphaned columns are filled with background characters.
Overlapping and overwriting a window follows the operation of overwriting characters around
its edge. The orphaned columns, if any, are handled as in the
character operations.
The cursor is allowed to be placed anywhere in a window. If
the insertion or deletion is made when the cursor points to the
second or later column position of a character that holds multiple columns,
the cursor is adjusted to the first column of the character before
the insertion or deletion.
Routine and Argument Names
Many curses routines have two or more versions. The routines prefixed with
w require a window argument. The routines prefixed with p require a
pad argument. Those without a prefix generally use stdscr.
The routines prefixed with mv require an x and y coordinate to
move to before performing the appropriate action. The mv routines imply a
call to move(3CURSES) before the call to the other routine. The coordinate
y always refers to the row (of the window), and x always
refers to the column. The upper left-hand corner is always (0,0), not (1,1).
The routines prefixed with mvw take both a window argument and x
and y coordinates. The window argument is always specified before the coordinates.
In each case, win is the window affected, and pad is the
pad affected; win and pad are always pointers to type WINDOW
Option setting routines require a Boolean flag bf with the value TRUE
or FALSE; bf is always of type bool. The variables ch and
attrs below are always of type chtype. The types WINDOW, SCREEN, bool,
and chtype are defined in <curses.h>. The type TERMINAL is defined in <term.h>.
All other arguments are integers.
Routine Name Index
The following table lists each curses routine and the name of the
manual page on which it is described.
- curses Routine Name
Manual Page Name
- addch
curs_addch(3CURSES)
- addchnstr
curs_addchstr(3CURSES)
- addchstr
curs_addchstr(3CURSES)
- addnstr
curs_addstr(3CURSES)
- addnwstr
curs_addwstr(3CURSES)
- addstr
curs_addstr(3CURSES)
- addwch
curs_addwch(3CURSES)
- addwchnstr
curs_addwchstr(3CURSES)
- addwchstr
curs_addwchstr(3CURSES)
- addwstr
curs_addwstr(3CURSES)
- adjcurspos
curs_alecompat(3CURSES)
- attroff
curs_attr(3CURSES)
- attron
curs_attr(3CURSES)
- attrset
curs_attr(3CURSES)
- baudrate
curs_termattrs(3CURSES)
- beep
curs_beep(3CURSES)
- bkgd
curs_bkgd(3CURSES)
- bkgdset
curs_bkgd(3CURSES)
- border
curs_border(3CURSES)
- box
curs_border(3CURSES)
- can_change_color
curs_color(3CURSES)
- cbreak
curs_inopts(3CURSES)
- clear
curs_clear(3CURSES)
- clearok
curs_outopts(3CURSES)
- clrtobot
curs_clear(3CURSES)
- clrtoeol
curs_clear(3CURSES)
- color_content
curs_color(3CURSES)
- copywin
curs_overlay(3CURSES)
- curs_set
curs_kernel(3CURSES)
- def_prog_mode
curs_kernel(3CURSES)
- def_shell_mode
curs_kernel(3CURSES)
- del_curterm
curs_terminfo(3CURSES)
- delay_output
curs_util(3CURSES)
- delch
curs_delch(3CURSES)
- deleteln
curs_deleteln(3CURSES)
- delscreen
curs_initscr(3CURSES)
- delwin
curs_window(3CURSES)
- derwin
curs_window(3CURSES)
- doupdate
curs_refresh(3CURSES)
- dupwin
curs_window(3CURSES)
- echo
curs_inopts(3CURSES)
- echochar
curs_addch(3CURSES)
- echowchar
curs_addwch(3CURSES)
- endwin
curs_initscr(3CURSES)
- erase
curs_clear(3CURSES)
- erasechar
curs_termattrs(3CURSES)
- filter
curs_util(3CURSES)
- flash
curs_beep(3CURSES)
- flushinp
curs_util(3CURSES)
- getbegyx
curs_getyx(3CURSES)
- getch
curs_getch(3CURSES)
- getmaxyx
curs_getyx(3CURSES)
- getnwstr
curs_getwstr(3CURSES)
- getparyx
curs_getyx(3CURSES)
- getstr
curs_getstr(3CURSES)
- getsyx
curs_kernel(3CURSES)
- getwch
curs_getwch(3CURSES)
- getwin
curs_util(3CURSES)
- getwstr
curs_getwstr(3CURSES)
- getyx
curs_getyx(3CURSES)
- halfdelay
curs_inopts(3CURSES)
- has_colors
curs_color(3CURSES)
- has_ic
curs_termattrs(3CURSES)
- has_il
curs_termattrs(3CURSES)
- idcok
curs_outopts(3CURSES)
- idlok
curs_outopts(3CURSES)
- immedok
curs_outopts(3CURSES)
- inch
curs_inch(3CURSES)
- inchnstr
curs_inchstr(3CURSES)
- inchstr
curs_inchstr(3CURSES)
- init_color
curs_color(3CURSES)
- init_pair
curs_color(3CURSES)
- initscr
curs_initscr(3CURSES)
- innstr
curs_instr(3CURSES)
- innwstr
curs_inwstr(3CURSES)
- insch
curs_insch(3CURSES)
- insdelln
curs_deleteln(3CURSES)
- insertln
curs_deleteln(3CURSES)
- insnstr
curs_insstr(3CURSES)
- insnwstr
curs_inswstr(3CURSES)
- insstr
curs_insstr(3CURSES)
- instr
curs_instr(3CURSES)
- inswch
curs_inswch(3CURSES)
- inswstr
curs_inswstr(3CURSES)
- intrflush
curs_inopts(3CURSES)
- inwch
curs_inwch(3CURSES)
- inwchnstr
curs_inwchstr(3CURSES)
- inwchstr
curs_inwchstr(3CURSES)
- inwstr
curs_inwstr(3CURSES)
- is_linetouched
curs_touch(3CURSES)
- is_wintouched
curs_touch(3CURSES)
- isendwin
curs_initscr(3CURSES)
- keyname
curs_util(3CURSES)
- keypad
curs_inopts(3CURSES)
- killchar
curs_termattrs(3CURSES)
- leaveok
curs_outopts(3CURSES)
- longname
curs_termattrs(3CURSES)
- meta
curs_inopts(3CURSES)
- move
curs_move(3CURSES)
- movenextch
curs_alecompat(3CURSES)
- moveprevch
curs_alecompat(3CURSES)
- mvaddch
curs_addch(3CURSES)
- mvaddchnstr
curs_addchstr(3CURSES)
- mvaddchstr
curs_addchstr(3CURSES)
- mvaddnstr
curs_addstr(3CURSES)
- mvaddnwstr
curs_addwstr(3CURSES)
- mvaddstr
curs_addstr(3CURSES)
- mvaddwch
curs_addwch(3CURSES)
- mvaddwchnstr
curs_addwchstr(3CURSES)
- mvaddwchstr
curs_addwchstr(3CURSES)
- mvaddwstr
curs_addwstr(3CURSES)
- mvcur
curs_terminfo(3CURSES)
- mvdelch
curs_delch(3CURSES)
- mvderwin
curs_window(3CURSES)
- mvgetch
curs_getch(3CURSES)
- mvgetnwstr
curs_getwstr(3CURSES)
- mvgetstr
curs_getstr(3CURSES)
- mvgetwch
curs_getwch(3CURSES)
- mvgetwstr
curs_getwstr(3CURSES)
- mvinch
curs_inch(3CURSES)
- mvinchnstr
curs_inchstr(3CURSES)
- mvinchstr
curs_inchstr(3CURSES)
- mvinnstr
curs_instr(3CURSES)
- mvinnwstr
curs_inwstr(3CURSES)
- mvinsch
curs_insch(3CURSES)
- mvinsnstr
curs_insstr(3CURSES)
- mvinsnwstr
curs_inswstr(3CURSES)
- mvinsstr
curs_insstr(3CURSES)
- mvinstr
curs_instr(3CURSES)
- mvinswch
curs_inswch(3CURSES)
- mvinswstr
curs_inswstr(3CURSES)
- mvinwch
curs_inwch(3CURSES)
- mvinwchnstr
curs_inwchstr(3CURSES)
- mvinwchstr
curs_inwchstr(3CURSES)
- mvinwstr
curs_inwstr(3CURSES)
- mvprintw
curs_printw(3CURSES)
- mvscanw
curs_scanw(3CURSES)
- mvwaddch
curs_addch(3CURSES)
- mvwaddchnstr
curs_addchstr(3CURSES)
- mvwaddchstr
curs_addchstr(3CURSES)
- mvwaddnstr
curs_addstr(3CURSES)
- mvwaddnwstr
curs_addwstr(3CURSES)
- mvwaddstr
curs_addstr(3CURSES)
- mvwaddwch
curs_addwch(3CURSES)
- mvwaddwchnstr
curs_addwchstr(3CURSES)
- mvwaddwchstr
curs_addwchstr(3CURSES)
- mvwaddwstr
curs_addwstr(3CURSES)
- mvwdelch
curs_delch(3CURSES)
- mvwgetch
curs_getch(3CURSES)
- mvwgetnwstr
curs_getwstr(3CURSES)
- mvwgetstr
curs_getstr(3CURSES)
- mvwgetwch
curs_getwch(3CURSES)
- mvwgetwstr
curs_getwstr(3CURSES)
- mvwin
curs_window(3CURSES)
- mvwinch
curs_inch(3CURSES)
- mvwinchnstr
curs_inchstr(3CURSES)
- mvwinchstr
curs_inchstr(3CURSES)
- mvwinnstr
curs_instr(3CURSES)
- mvwinnwstr
curs_inwstr(3CURSES)
- mvwinsch
curs_insch(3CURSES)
- mvwinsnstr
curs_insstr(3CURSES)
- mvwinsstr
curs_insstr(3CURSES)
- mvwinstr
curs_instr(3CURSES)
- mvwinswch
curs_inswch(3CURSES)
- mvwinswstr
curs_inswstr(3CURSES)
- mvwinwch
curs_inwch(3CURSES)
- mvwinwchnstr
curs_inwchstr(3CURSES)
- mvwinwchstr
curs_inwchstr(3CURSES)
- mvwinwstr
curs_inwstr(3CURSES)
- mvwprintw
curs_printw(3CURSES)
- mvwscanw
curs_scanw(3CURSES)
- napms
curs_kernel(3CURSES)
- newpad
curs_pad(3CURSES)
- newterm
curs_initscr(3CURSES)
- newwin
curs_window(3CURSES)
- nl
curs_outopts(3CURSES)
- nocbreak
curs_inopts(3CURSES)
- nodelay
curs_inopts(3CURSES)
- noecho
curs_inopts(3CURSES)
- nonl
curs_outopts(3CURSES)
- noqiflush
curs_inopts(3CURSES)
- noraw
curs_inopts(3CURSES)
- notimeout
curs_inopts(3CURSES)
- overlay
curs_overlay(3CURSES)
- overwrite
curs_overlay(3CURSES)
- pair_content
curs_color(3CURSES)
- pechochar
curs_pad(3CURSES)
- pechowchar
curs_pad(3CURSES)
- pnoutrefresh
curs_pad(3CURSES)
- prefresh
curs_pad(3CURSES)
- printw
curs_printw(3CURSES)
- putp
curs_terminfo(3CURSES)
- putwin
curs_util(3CURSES)
- qiflush
curs_inopts(3CURSES)
- raw
curs_inopts(3CURSES)
- redrawwin
curs_refresh(3CURSES)
- refresh
curs_refresh(3CURSES)
- reset_prog_mode
curs_kernel(3CURSES)
- reset_shell_mode
curs_kernel(3CURSES)
- resetty
curs_kernel(3CURSES)
- restartterm
curs_terminfo(3CURSES)
- ripoffline
curs_kernel(3CURSES)
- savetty
curs_kernel(3CURSES)
- scanw
curs_scanw(3CURSES)
- scr_dump
curs_scr_dump(3CURSES)
- scr_init
curs_scr_dump(3CURSES)
- scr_restore
curs_scr_dump(3CURSES)
- scr_set
curs_scr_dump(3CURSES)
- scroll
curs_scroll(3CURSES)
- scrollok
curs_outopts(3CURSES)
- set_curterm
curs_terminfo(3CURSES)
- set_term
curs_initscr(3CURSES)
- setscrreg
curs_outopts(3CURSES)
- setsyx
curs_kernel(3CURSES)
- setterm
curs_terminfo(3CURSES)
- setupterm
curs_terminfo(3CURSES)
- slk_attroff
curs_slk(3CURSES)
- slk_attron
curs_slk(3CURSES)
- slk_attrset
curs_slk(3CURSES)
- slk_clear
curs_slk(3CURSES)
- slk_init
curs_slk(3CURSES)
- slk_label
curs_slk(3CURSES)
- slk_noutrefresh
curs_slk(3CURSES)
- slk_refresh
curs_slk(3CURSES)
- slk_restore
curs_slk(3CURSES)
- slk_set
curs_slk(3CURSES)
- slk_touch
curs_slk(3CURSES)
- srcl
curs_scroll(3CURSES)
- standend
curs_attr(3CURSES)
- standout
curs_attr(3CURSES)
- start_color
curs_color(3CURSES)
- subpad
curs_pad(3CURSES)
- subwin
curs_window(3CURSES)
- syncok
curs_window(3CURSES)
- termattrs
curs_termattrs(3CURSES)
- termname
curs_termattrs(3CURSES)
- tgetent
curs_termcap(3CURSES)
- tgetflag
curs_termcap(3CURSES)
- tgetnum
curs_termcap(3CURSES)
- tgetstr
curs_termcap(3CURSES)
- tgoto
curs_termcap(3CURSES)
- tigetflag
curs_terminfo(3CURSES)
- tigetnum
curs_terminfo(3CURSES)
- tigetstr
curs_terminfo(3CURSES)
- timeout
curs_inopts(3CURSES)
- touchline
curs_touch(3CURSES)
- touchwin
curs_touch(3CURSES)
- tparm
curs_terminfo(3CURSES)
- tputs
curs_terminfo(3CURSES)
- typeahead
curs_inopts(3CURSES)
- unctrl
curs_util(3CURSES)
- ungetch
curs_getch(3CURSES)
- ungetwch
curs_getwch(3CURSES)
- untouchwin
curs_touch(3CURSES)
- use_env
curs_util(3CURSES)
- vidattr
curs_terminfo(3CURSES)
- vidputs
curs_terminfo(3CURSES)
- vwprintw
curs_printw(3CURSES)
- vwscanw
curs_scanw(3CURSES)
- waddch
curs_addch(3CURSES)
- waddchnstr
curs_addchstr(3CURSES)
- waddchstr
curs_addchstr(3CURSES)
- waddnstr
curs_addstr(3CURSES)
- waddnwstr
curs_addwstr(3CURSES)
- waddstr
curs_addstr(3CURSES)
- waddwch
curs_addwch(3CURSES)
- waddwchnstr
curs_addwchstr(3CURSES)
- waddwchstr
curs_addwchstr(3CURSES)
- waddwstr
curs_addwstr(3CURSES)
- wadjcurspos
curs_alecompat(3CURSES)
- wattroff
curs_attr(3CURSES)
- wattron
curs_attr(3CURSES)
- wattrset
curs_attr(3CURSES)
- wbkgd
curs_bkgd(3CURSES)
- wbkgdset
curs_bkgd(3CURSES)
- wborder
curs_border(3CURSES)
- wclear
curs_clear(3CURSES)
- wclrtobot
curs_clear(3CURSES)
- wclrtoeol
curs_clear(3CURSES)
- wcursyncup
curs_window(3CURSES)
- wdelch
curs_delch(3CURSES)
- wdeleteln
curs_deleteln(3CURSES)
- wechochar
curs_addch(3CURSES)
- wechowchar
curs_addwch(3CURSES)
- werase
curs_clear(3CURSES)
- wgetch
curs_getch(3CURSES)
- wgetnstr
curs_getstr(3CURSES)
- wgetnwstr
curs_getwstr(3CURSES)
- wgetstr
curs_getstr(3CURSES)
- wgetwch
curs_getwch(3CURSES)
- wgetwstr
curs_getwstr(3CURSES)
- whline
curs_border(3CURSES)
- winch
curs_inch(3CURSES)
- winchnstr
curs_inchstr(3CURSES)
- winchstr
curs_inchstr(3CURSES)
- winnstr
curs_instr(3CURSES)
- winnwstr
curs_inwstr(3CURSES)
- winsch
curs_insch(3CURSES)
- winsdelln
curs_deleteln(3CURSES)
- winsertln
curs_deleteln(3CURSES)
- winsnstr
curs_insstr(3CURSES)
- winsnwstr
curs_inswstr(3CURSES)
- winsstr
curs_insstr(3CURSES)
- winstr
curs_instr(3CURSES)
- winswch
curs_inswch(3CURSES)
- winswstr
curs_inswstr(3CURSES)
- winwch
curs_inwch(3CURSES)
- winwchnstr
curs_inwchstr(3CURSES)
- winwchstr
curs_inwchstr(3CURSES)
- winwstr
curs_inwstr(3CURSES)
- wmove
curs_move(3CURSES)
- wmovenextch
curs_alecompat(3CURSES)
- wmoveprevch
curs_alecompat(3CURSES)
- wnoutrefresh
curs_refresh(3CURSES)
- wprintw
curs_printw(3CURSES)
- wredrawln
curs_refresh(3CURSES)
- wrefresh
curs_refresh(3CURSES)
- wscanw
curs_scanw(3CURSES)
- wscrl
curs_scroll(3CURSES)
- wsetscrreg
curs_outopts(3CURSES)
- wstandend
curs_attr(3CURSES)
- wstandout
curs_attr(3CURSES)
- wsyncdown
curs_window(3CURSES)
- wsyncup
curs_window(3CURSES)
- wtimeout
curs_inopts(3CURSES)
- wtouchln
curs_touch(3CURSES)
- wvline
curs_border(3CURSES)
Return Values
Routines that return an integer return ERR upon failure and an integer
value other than ERR upon successful completion, unless otherwise noted in the
routine descriptions.
All macros return the value of the w version, except setscrreg(), wsetscrreg(),
getyx(), getbegyx(), and getmaxyx(). The return values of setscrreg(), wsetscrreg(), getyx(), getbegyx(),
and getmaxyx() are undefined (that is, these should not be used as
the right-hand side of assignment statements).
Routines that return pointers return NULL on error.
Attributes
See attributes(5) for descriptions of the following attributes:
See Also
curses(3XCURSES), libcurses(3LIB), libcurses(3XCURSES), terminfo(4), attributes(5)
Notes
The header <curses.h> automatically includes the headers <stdio.h> and <unctrl.h>.
