CURSES(3CURSES) Curses Library Functions CURSES(3CURSES)


NAME


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:


+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|MT-Level | Unsafe |
+---------------+-----------------+

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>.


October 23, 2001 CURSES(3CURSES)