curses
Purpose
Controls cursor movement and windowing.
Library
Curses Library (libcurses.a)
Syntax
#include <curses.h>
#include <term.h>
Description
Note: The curses package of subroutines is included here
only for compatibility with existing programs. For
information about the enhanced screen-handling subroutine
library, see "extended curses library."
The curses subroutine package updates the screen with
reasonable optimization. The term.h header file is only
needed if terminfo level routines are needed (see
"Terminfo Level Subroutines").
In order to initialize the routines, the routine initscr
must be called before any of the other routines that deal
with windows and screens are used. The routine endwin
should be called before exiting. To get character-at-a-
time input without echoing, call the nonl, cbreak, and
noecho routines. Most interactive, screen-oriented pro-
grams require the character-at-a-time input without
echoing.
The full curses interface permits manipulation of data
structures called windows, which can be thought of as
two-dimensional arrays of characters representing all or
part of a screen. A default window called stdscr is sup-
plied, and others can be created with the newwin routine.
Windows are referred to by variables declared WINDOW *.
The type WINDOW is defined in curses.h to be a C struc-
ture. These data structures are manipulated with the
routines described following, among which the most basic
are move and addch. Then the refresh routine is called,
telling the routines to make the screen look like stdscr.
More general versions of these routines are included with
names beginning with w allowing you to specify a window.
The routines not beginning with a w affect stdscr.
Minicurses is a subset of curses that does not allow
manipulation of more than one window. To invoke this
subset, use -DMINICURSES as a cc option. This level is
smaller and faster than the full curses.
If the environment variable TERMINFO is defined, any
program using curses checks for a local terminal defi-
nition before checking in /usr/lib/terminfo. For
example, TERM is set to vt100, then normally, the com-
piled file is found in /usr/lib/terminfo/v/vt100. (The
directory name v is copied from the first letter of vt100
to avoid creating huge directories.) If, for example,
TERMINFO is set to /usr/mark/myterms, curses first checks
/usr/mark/myterms/v/vt100. If this file does not exist,
curses then checks /usr/lib/terminfo/v/vt100. This is
useful for developing experimental definitions or when
write permission in /usr/lib/terminfo is not available.
Note: The plotting library, plot and the curses library,
curses both use the names erase and move. The curses
versions are macros. If you need both libraries, put the
plot code in a different source file than the curses
code, or include the following statements in the plot
code:
#undef move()
#undef erase()
ROUTINES
The routines listed here can be called when using the
full curses. Those marked with an asterisk can be called
when using minicurses.
addch(ch)* Add a character to stdscr (like
putchar), wrapping to the next
line at the end of a line.
waddch(win, ch) Add the character ch to win
mvwaddch(win, y, x, ch)
Move (y, x) then add the character
ch to win
addstr(str)* Call addch with each character in
str
mvaddstr(y, x, str) Move (y, x) then add str
waddstr(win, str) Add the string str to win
mvwaddstr(win, y, x, str)
Move (y, x) then add the string
str to win
attroff(attrs)* Turn off the attributes named in
attrs
attron(attrs)* Turn on the attributes named in
attrs
attrset(attrs)* Set current attributes to those
specified in attrs
baudrate ( )* Set current terminal speed
beep ( )* Sound beep on terminal
box(win, vert, hor) Draw a box around edges of win.
The vert and hor parameters are
the characters to use for vertical
and horizontal edges of the box.
cbreak ( )* Set cbreak mode
nocbreak ( )* Unset cbreak mode
clear ( ) Clear stdscr
clearok(win, bf) Clear screen before next redraw of
win
clrtobot ( ) Clear to bottom of stdscr
clrtoeol ( ) Clear to end of line on stdscr
delay_output(ms)* Insert ms millisecond pause in
output
nodelay(win, bf) Enable nodelay input mode through
getch
delch ( ) Delete a character
deleteln ( ) Delete a line
delwin(win) Delete window win
doupdate ( ) Update screen from all
wnoutrefresh
echo ( )* Set echo mode
noecho ( )* Unset echo mode
endwin ( )* End window modes
erase ( ) Erase stdscr
erasechar ( ) Return user's erase character
fixterm ( ) Restore terminal to in curses
state
flash ( ) Flash screen or beep
flushinp ( )* Throw away any type-ahead
getch ( )* Get a character from tty
getstr(str) Get a string through stdscr
gettmode ( ) Establish current tty modes
getyx(win, y, x) Get (y, x) coordinates
has_ic ( ) Has value of "true" if terminal
can do insert character
has_il ( ) Has value of "true" if terminal
can do insert line
idlok(win, bf)* Use terminal's insert/delete line
if bf!=0
inch ( ) Get character at current (y, x)
coordinates
initscr ( )* Initialize screens
insch(c) Insert a character
insertln ( ) Insert a line
intrflush(win, bf) Interrupt flush output if bf is
true
keypad(win, bf) Enable keypad input
killchar ( ) Return current user's kill char-
acter
leaveok(win, flag) Permit cursor to be left anywhere
after refresh if flag!=0 for win;
otherwise cursor must be left at
current position
longname ( ) Return verbose name of terminal
meta(win, flag)* Allow metacharacters on input if
flag!=0
move(y, x, ch)* Move to (y, x) on stdscr
mvaddch(y, x, ch) Move (y, x) then add ch
mvcur(oldrow, oldcol, newrow, newcol)
Move cursor from current position
to another position
mvdelch(y, x) Move (y, x) then delete a char-
acter
mvgetch(y, x) Move (y, x) then get a character
from tty
mvgetstr(y, x, str) Move (y, x) then get a string
through stdscr
mvinch(y, x) Move (y, x) then get the character
at current (y, x) coordinates
mvinsch(y, x, c) Move (y, x) then insert the char-
acter c
mvprintw(y, x, fmt, args)
Move (y, x) then get print on
stdscr
mvscanw(y, x, fmt, args)
Move (y, x) then scan through
stdscr
mvwdelch(win, y, x) Move (y, x) then delete a char-
acter from win
mvwgetch(win, y, x) Move (y, x) then get a character
through win
mvwgetstr(win, y, x, str)
Move (y, x) then get a string
through win
mvwin(win, by, bx) Move win so that the upper left-
hand corner is located at (y, x)
mvwinch(win, y, x) Move (y, x) then get the character
at current (y, x) in win
mvwinsch(win, y, x, c) Move (y, x) then insert the char-
acter c into win
mvwprintw(win, y, x, fmt, args)
Move (y, x) then printf on stdscr
mvwscanw(win, y, x, fmt, args)
Move (y, x) then scanf through
stdscr
newpad(nlines, ncols) Create a new pad with given dimen-
sions
newterm(type, fd) Set up new terminal of given type
to output on fd
newwin(lines, cols, begin_y, begin_x)
Create a new window
nl ( )* Set newline mapping
nonl ( )* Unset newline mapping
overlay(win1, win2) Overlay win1 on win2
overwrite(win1, win2) Overwrite win1 on top of win2
printw(fmt, arg1, arg2, ...)
Print on stdscr
raw ( )* Set raw mode
refresh ( )* Make current screen look like
stdscr
prefresh(pad, pminrow, pmincol, sminrow, smincol,
smaxrow, smaxcol)
Refresh from pad starting with
given upper left corner of pad
with output to given portion of
screen
pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol,
smaxrow, smaxcol)
Refresh like prefresh, but with no
output until doupdate is called
noraw ( )* Unset raw mode
resetterm ( )* Set tty modes to out of curses
state
resetty ( )* Reset tty flags to stored value
saveterm ( )* Save current modes as in curses
state
savetty ( )* Store current tty flags
scanw(fmt, arg1, arg2, ...)
Scanf through stdscr
scroll(win) Scroll win one line
scrollok(win, flag) Allow terminal to scroll if
flag!=0
set_term(new) Enable talk to terminal new
setscrreg(t, b) Set user scrolling region to lines
t through b
setterm(type) Establish terminal with a give
type
standend ( )* Clear standout mode attribute
standout ( )* Set standout mode attribute
subwin(win, lines, cols, begin_y, begin_x)
Create a subwindow
touchwin(win) Change all of win
traceoff ( ) Turn off debugging trace output
traceon ( ) Turn on debugging trace output
typeahead(fd) Check file descriptor fd to check
type-ahead
unctrl(ch)* Use printable version of ch
wattroff(win, attrs) Turn off attrs in win
wattron(win, attrs) Turn on attrs in win
wattrset(win, attrs) Set attributes in win to attrs
wclear(win) Clear win
wclrtobot(win) Clear to bottom of win
wclrtoeol(win) Clear to end of line on win
wdelch(win, c) Delete the character c from win
wdeleteln(win) Delete line from win
werase(win) Erase win
wgetch(win) Get a character through win
wgetstr(win, str) Get the string str through win
winch(win) Get the character at current (y,
x) in win
winsch(win, c) Insert the character c into win
winsertln(win) Insert line into win
wmove(win, y, x) Set current (y, x) coordinates on
win
wnoutrefresh(win) Refresh but no screen output
wprintw(win, fmt, arg1, arg2, . . . )
printf on win
wrefresh(win) Make screen look like win
wscanw(win, fmt, arg1, arg2, . . . )
scanf through win
wsetscrreg(win, t, b) Set scrolling region of win
wstandend(win) Clear standout attribute in win
wstandout(win) Set standout attribute in win
TERMINFO LEVEL SUBROUTINES
These routines should be called by programs that have to
deal directly with the terminfo data base. Due to the
low level of this interface, its use is discouraged. The
header files curses.h and term.h should be included (in
that order) to get the definitions for these strings,
numbers, and flags. You should call setupterm before
using any of the other terminfo subroutines. This
defines the set of terminal-dependent variables defined
in the terminfo file.
If the program needs only one terminal, you can specify
the -DSINGLE flag to the C compiler. This results in
static references instead of dynamic references to capa-
bilities. The result is smaller code, but only one ter-
minal can be used at a time for the program.
Capabilities with a Boolean value have the value 1 if the
capability is present and 0 if it is not. Numeric capa-
bilities have a value of -1 if the capability is missing
and a value of 0 or greater if it is present. String
capabilities have a NULL value if the capability is
missing and otherwise have type char * and point to a
character string that contains the capability. Special
character codes that use the backslash and circumflex
characters (\ and ^) are transformed into the appropriate
ASCII characters. Padding information of the form
$<time>, and parameter information beginning with %
(percent) are left uninterpreted. The tputs routine
interprets padding information and tparm interprets
parameter information.
All terminfo strings (including the output of tparm)
should be printed with tputs or putp. Before exiting,
reset_shell_mode should be called to restore the tty
modes. Programs desiring shell escapes can call
reset_shell_mode before the shell is called and
reset_prog_mode after returning from the shell.
delay_output (ms)
Sets the output delay, in milliseconds.
def_prog_mode
Saves the current terminal mode as program mode, in
cur_term->Nttyb.
def_shell_mode
Saves the shell mode as normal mode, in
cur_term->Ottyb. def_shell_mode is called automat-
ically by setupterm.
putp(str)
Calls tputs(str, 1, putchar).
reset_prog_mode
Puts the terminal into program mode.
reset_shell_mode
Puts the terminal into shell mode. All programs must
call reset_shell_mode before they exit. The higher-
level routine endwin automatically does this.
setupterm(term, fd, rc)
Reads in the data base. term is a character string
that specifies the terminal name. If term is 0, then
the value of the TERM environment variable is used.
One of the following status values is stored into the
integer pointed to by rc:
1 Successful completion
0 No such terminal
-1 An error occurred while locating the terminfo
data base.
If the rc parameter is 0, then no status value is
returned, and an error causes setupterm to print an
error message and exit, rather than return. fd is the
file descriptor of the terminal being used for output.
setupterm calls termdef to determine the number of
lines and columns on the display. If termdef cannot
supply this information, then setupterm uses the
values in the terminfo data base. The simplest call
is setupterm(0, 1, 0), which uses all the defaults.
After the call to setupterm, the global variable
cur_term is set to point to the current structure of
terminal capabilities. It is possible for a program
to use more than one terminal at a time by calling
setupterm for each terminal and saving and restoring
cur_term.
The setupterm subroutine also initializes the global
variable ttytype as an array of characters to the
value of the list of names for the terminal. The list
comes from the beginning of the terminfo description.
tparm(str, p1, p2, . . . p9)
Instantiates the string str with parameters p[i]. The
character string returned has the given parameters
applied.
tputs(str, affcnt, putc)
Applies padding information to string str. affcnt is
the number of lines affected, or 1 if not applicable.
putc is a putchar-like routine to which the characters
are passed one at a time.
Some strings are of a form like "$<20>", which is an
instruction to pad for 20 milliseconds.
vidputs(attrs, putc)
Outputs the string to put terminal in video attribute
mode attrs. Characters are passed to the putchar-like
routine putc. The attrs are defined in <curses.h>.
The previous mode is retained by this routine.
vidattr(attrs)
Like vidputs, but outputs through putchar.
TERMCAP COMPATIBILITY ROUTINES
These routines are included for compatibility with pro-
grams that require termcap. Their parameters are the
same as for termcap, and they are emulated using the
terminfo data base.
tgetent(bp, name)
Looks up the termcap entry for name. bp and name are
strings. name is a terminal name; bp is ignored.
Calls setupterm.
tgetflag(id)
Returns the Boolean entry for id. id is a 2-character
string that contains a termcap identifier.
tgetnum(id)
Returns the numeric entry for id. id is a 2-character
string that contains a termcap identifier.
tgetstr(id, area)
Returns the string entry for id. id is a 2-character
string that contains a termcap identifier. The area
parameter is ignored.
tgoto(cap, col, row)
Applies parameters to the given cap. Calls tparm.
tputs(cap, affcnt, fn)
Applies padding to cap calling fn as putchar.
ATTRIBUTES
The following video attributes can be passed to the rou-
tines attron, attroff, and attrset.
A_STANDOUT The terminal's best highlighting mode
A_UNDERLINE Underlined
A_REVERSE Reverse video
A_BLINK Blinking
A_DIM Half bright
A_BOLD Extra bright or bold
A_INVIS Invisible (blanked or zero-intensity)
A_PROTECT Protected
A_ALTCHARSET Alternate character set
A_NORMAL Normal attributes
FUNCTION KEYS
The following function keys might be returned by getch if
keypad has been enabled. Note that not all of these are
currently supported due to lack of definitions in
terminfo, or due to the terminal not transmitting a
unique code when the key is pressed.
KEY_BREAK Break key (unreliable)
KEY_DOWN Down-arrow key
KEY_UP Up-arrow key
KEY_LEFT Left-arrow key
KEY_RIGHT Right-arrow key
KEY_HOME Home key
KEY_BACKSPACE Backspace (unreliable)
KEY_F(n) Function key Fn, where n is an integer
from 0 to 63
KEY_DL Delete line
KEY_IL Insert line
KEY_DC Delete character
KEY_IC Insert character or enter insert mode
KEY_EIC Exit insert character mode
KEY_CLEAR Clear screen
KEY_EOS Clear to end of screen
KEY_EOL Clear to end of line
KEY_SF Scroll 1 line forward
KEY_SR Scroll 1 line backwards (reverse)
KEY_NPAGE Next page
KEY_PPAGE Previous page
KEY_STAB Set tab
KEY_CTAB Clear tab
KEY_CATAB Clear all tabs
KEY_ENTER Enter or send (unreliable)
KEY_SRESET Soft (partial) reset (unreliable)
KEY_RESET Reset or hard reset (unreliable)
KEY_PRINT Print or copy
KEY_LL Home down or bottom (lower left)
KEY_A1 Upper left key of keypad
KEY_A3 Upper right key of keypad
KEY_B2 Center key of keypad
KEY_C1 Lower left key of keypad
KEY_C3 Lower right key of keypad
Related Information
In this book: "extended curses library," "termdef," and
"terminfo."