CURSES(3X) DOMAIN/IX Reference Manual (SYS5) CURSES(3X)
NAME
curses - CRT screen handling and optimization package
USAGE
#include <curses.h>
cc [ flags ] files -lcurses [ libraries ]
DESCRIPTION
These routines let you update screens with reasonable optim-
ization. To initialize the routines, you must call the rou-
tine initscr() before using any of the other routines that
deal with windows and screens. You must also call the rou-
tine endwin() before exiting. To get character-at-a-time
input without echoing, (most interactive, screen oriented-
programs want this) call initscr(), followed by ``nonl();
cbreak(); noecho();'' calls.
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. The program supplies a default window called
stdscr; you can create others with newwin. Windows are
referred to by variables declared ``WINDOW *''; the type
WINDOW is defined in curses.h to be a C structure.
These data structures are manipulated with functions
described below, among which the most basic are move and
addch. (More general versions of these functions are
included with names beginning with ``w'', allowing you to
specify a window. The routines not beginning with ``w''
affect stdscr.) The refresh() call then tells the routines
to make your screen look like stdscr.
``Mini-Curses'', a subset of curses, does not allow manipu-
lation of more than one window. To invoke this subset, use
-DMINICURSES as a cc(1) option. This level is smaller and
faster than full curses.
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 the stan-
dard place is /usr/lib/terminfo, and TERM is set to
``vt100'', then normally the compiled file is found in
/usr/lib/terminfo/v/vt100. (The ``v'' is copied from the
first letter of ``vt100'' to avoid creation of huge direc-
tories.)
However, if TERMINFO is set to /usr/mark/myterms, curses
first checks /opusr/mark/myterms/v/vt100. If that fails, it
then checks the file /usr/lib/terminfo/v/vt100. This feature
is useful for developing experimental definitions or when
write permission in /usr/lib/terminfo is not available.
Printed 1/27/86 CURSES-1
CURSES(3X) DOMAIN/IX Reference Manual (SYS5) CURSES(3X)
FUNCTIONS
You may call routines listed here when using the full curses
program. Those marked with an asterisk apply to the ``Mini-
Curses'' subset.
addch(ch)* Add a character to stdscr (like
putchar) (wraps to next line at end
of line)
addstr(str)* Call addch with each character in
str
attroff(attrs)* Turn off named attributes
attron(attrs)* Turn on named attributes
attrset(attrs)* Set current attributes to attrs
baudrate()* Current terminal speed
beep()* Sound beep on terminal
box(win, vert, hor) Draw a box around edges of win; use
vert and hor for vertical and hor-
izontal edges of box
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
cbreak()* Set cbreak mode
delay_output(ms)* Insert ms millisecond pause in out-
put
delch() Delete a character
deleteln() Delete a line
delwin(win) Delete win
doupdate() Update screen from all
wnooutrefresh
echo()* Set echo mode
CURSES-2 Printed 1/27/86
CURSES(3X) DOMAIN/IX Reference Manual (SYS5) CURSES(3X)
endwin()* End window modes
erase() Erase stdscr
erasechar() Return user's erase character
fixterm() Restore tty to ``in curses" state
flash() Flash screen or beep
flushinp()* Throw away any typeahead
getch()* Get a char from tty
getstr(str) get a string through stdscr
gettmode() Establish current tty modes
getyx(win, y, x) Get (y, x) co-ordinates
has_ic() True if terminal can do insert
character
has_il() True if terminal can do insert line
idlok(win, bf)* Use terminal's insert/delete line
if bf != 0
inch() Get char at current (y, x) co-
ordinates
initscr()* Initialize screens
insch(c) Insert a char
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 charac-
ter
leaveok(win, flag) OK to leave cursor anywhere after
refresh if flag!=0 for , otherwise
cursor must be left at current
position
longname() Return verbose name of terminal
Printed 1/27/86 CURSES-3
CURSES(3X) DOMAIN/IX Reference Manual (SYS5) CURSES(3X)
meta(win, flag)* Allow metacharacters on input if
flag != 0
move(y, x)* Move to (y, x) on sdtscr
mvaddch(y, x, ch) Move(y, x) then addch(ch)
mvaddstr(y, x, str) Similar...
mvcur(oldrow, oldcol, newrow, newcol) Low level cursor
motion
mvdelch(y, x) Like delch, but move(y, x) first
mvgetch(y, x) etc.
mvgetstr(y, x)
mvinch(y, x)
mvinsch(y, x, c)
mvprintw(y, x, fmt, args)
mvscanw(y, x, fmt, args)
mvwaddch(win, y, x, ch)
mvwaddstr(win, y, x, str)
mvwdelch(win, y, x)
mvwgetch(win, y, x)
mvwgetstr(win, y, x)
mvwin(win, by, bx)
mvwinch(win, y, x)
mvwinsch(win, y, x, c)
mvwprintw(win, y, x, fmt, args)
mvwscanw(win, y, x, fmt, args)
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
CURSES-4 Printed 1/27/86
CURSES(3X) DOMAIN/IX Reference Manual (SYS5) CURSES(3X)
newwin(lines, cols, begin_y, begin_x)
Create a new window
nl()* Set newline mapping
nocbreak()* Unset cbreak mode
nodelay(win, bf) Enable nodelay input mode through
getch
noecho()* Unset echo mode
nonl()* Unset newline mapping
noraw()* Unset raw mode
overlay(win1, win2) Overlay win1 on win2
overwrite(win1, win2) Overwrite win1 on top of win2
pnoutrefresh(pad, pminrow, pmincol,
Like prefresh but with no output
until
sminrow, smincol, smaxrow, smax-
col) doupdate called.
prefresh(pad, pminrow, pmincol,
Refresh from pad starting with
given upper left
sminrow, smincol, smaxrow, smaxcol)
corner of pad with output to given
portion of screen.
printw(fmt, arg1, arg2, ...)
Printf on stdscr
raw()* Set raw mode
refresh()* Make current screen look like
stdscr
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, ...)
Printed 1/27/86 CURSES-5
CURSES(3X) DOMAIN/IX Reference Manual (SYS5) CURSES(3X)
Scanf through stdscr
scroll(win) Scroll win one line
scrollok(win, flag) Allow terminal to scroll if flag !=
0
set_term(new) Now talk to terminal new
setscrreg(t, b) Set user scrolling region to lines
t through b
setterm(type) Establish terminal with given type
setupterm(term, filenum, errret)
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) Use file descriptor fd to check
typeahead
unctrl(ch)* Printable version of ch
waddch(win, ch) Add char to win
waddstr(win, str) Add string to win
wattroff(win, attrs) Turn off attrs in win
wattron(win, attrs) Turn on attrs in win
wattrset(win, attrs) Set attrs 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 char from win
CURSES-6 Printed 1/27/86
CURSES(3X) DOMAIN/IX Reference Manual (SYS5) CURSES(3X)
wdeleteln(win) Delete line from win
werase(win) Erase win
wgetch(win) Get a char through win
wgetstr(win, str) Get a string through win
winch(win) Get char at current (y, x) in win
winsch(win, c) Insert char into win
winsertln(win) Insert line into win
wmove(win, y, x) Set current (y, x) co-ordinates 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 ROUTINES
Programs that deal directly with the terminfo database
should call these routines. Due to the low level of this
interface, their use is discouraged. Initially, setupterm
should be called. This routine defines the set of
terminal-dependent variables defined in terminfo (4). The
include files, <curses.h> and <term.h>, should be included
to get the definitions for these strings, numbers, and
flags.
Parmeterized strings should be passed through tparm to
instantiate them. All terminfo strings (including the out-
put of tparm) should be printed with tputs or putp. Before
exiting, resetterm should be called to restore the tty
modes. (Programs desiring shell escapes or suspending with
CTRL-Z can call resetterm before the shell is called and
fixterm after returning from the shell.)
fixterm() Restore tty modes for terminfo use
Printed 1/27/86 CURSES-7
CURSES(3X) DOMAIN/IX Reference Manual (SYS5) CURSES(3X)
(called by setupterm)
resetterm() Reset tty modes to state before
program entry
setupterm(term, fd, rc) Read in database; terminal type is
character string term, all output
is to UNIX System file descriptor
fd; status value is returned in the
integer pointed to by rc (1 is nor-
mal); simplest call would be setup-
term(0, 1, 0), which uses all
defaults
tparm(str, p1, p2, ..., p9)
Instantiate string str with parms
p .
i
tputs(str, affcnt, putc) Apply padding info to string str;
affcnt is the number of lines
affected, or 1 if not applicable.
Putc is a putchar-like function to
which the characters are passed,
one at a time.
putp(str) Handy function that calls tputs
(str, 1, putchar).
vidputs(attrs, putc) Output the string to put terminal
in video attribute mode attrs (any
combination of the attributes
listed below; chars are passed to
putchar-like function putc.
vidattr(attrs) Like vidputs but outputs through
putchar.
TERMCAP COMPATIBILITY ROUTINES
These routines were included as a conversion aid for pro-
grams that use termcap. Their parameters are the same as for
termcap. They are emulated using the terminfo database.
tgetent(bp, name) Look up termcap entry for name
tgetflag(id) Get boolean entry for id
tgetnum(id) Get numeric entry for id
tgetstr(id, area) Get string entry for id
tgoto(cap, col, row) Apply parms to given cap
CURSES-8 Printed 1/27/86
CURSES(3X) DOMAIN/IX Reference Manual (SYS5) CURSES(3X)
tputs(cap, affcnt, fn) Apply padding to cap calling fn as
putchar
ATTRIBUTES
The following video attributes can be passed to the func-
tions attron, attroff, attrset:
A_STANDOUT Terminal's best highlighting mode
A_UNDERLINE Underlining
A_REVERSE Reverse video
A_BLINK Blinking
A_DIM Half bright
A_BOLD Extra bright or bold
A_BLANK Blanking (invisible)
A_PROTECT Protected
A_ALTCHARSET Alternate character set
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 the terminal not transmitting a unique code when the key
is pressed.
Name Value Key Name
KEY_BREAK 0401 Break key (unreliable)
KEY_DOWN 0402 The four arrow keys ...
KEY_UP 0403
KEY_LEFT 0404
KEY_RIGHT 0405 ...
KEY_HOME 0406 Home key (upward+left arrow)
KEY_BACKSPACE 0407 Backspace (unreliable)
KEY_F0 0410 Function keys; space for 64 reserved
KEY_F(n) (KEY_F0+(n)) Formula for fn
KEY_DL 0510 Delete line
KEY_IL 0511 Insert line
KEY_DC 0512 Delete character
KEY_IC 0513 Insert char or enter insert mode
KEY_EIC 0514 Exit insert char mode
KEY_CLEAR 0515 Clear screen
KEY_EOS 0516 Clear to end of screen
KEY_EOL 0517 Clear to end of line
KEY_SF 0520 Scroll 1 line forward
Printed 1/27/86 CURSES-9
CURSES(3X) DOMAIN/IX Reference Manual (SYS5) CURSES(3X)
KEY_SR 0521 Scroll 1 line backwards (reverse)
KEY_NPAGE 0522 Next page
KEY_PPAGE 0523 Previous page
KEY_STAB 0524 Set tab
KEY_CTAB 0525 Clear tab
KEY_CATAB 0526 Clear all tabs
KEY_ENTER 0527 Enter or send (unreliable)
KEY_SRESET 0530 Soft (partial) reset (unreliable)
KEY_RESET 0531 Reset or hard reset (unreliable)
KEY_PRINT 0532 Print or copy
KEY_LL 0533 Home down or bottom (lower left)
RELATED INFORMATION
terminfo(4)
CURSES-10 Printed 1/27/86