Go to main content

man pages section 3: Curses Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

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(5) 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(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
MT-Level
Unsafe

See Also

libcurses(3LIB), curses(3XCURSES), libcurses(3XCURSES), terminfo(5), attributes(7)

Notes

The header <curses.h> automatically includes the headers <stdio.h> and <unctrl.h>.