CURSES(3X) DOMAIN/IX SYS5 CURSES(3X)
NAME
curses - CRT screen handling and optimization package
USAGE
#include <curses.h>
DESCRIPTION
These routines let you update screens in an optimal way. To
include these routines in program, include the header file
<curses.h>, and compile with the -lcurses option to link
with libcurses.
To initialize the routines, you must call the routine
initscr() before using any of the other routines that deal
with windows and screens. You must also call the routine
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.
Note: The "windows" managed by curses bear no relation
to the windows managed by the DOMAIN System's
Display Manager, and are typically used by dumb
terminals and, to some extent, by terminal emula-
tion packages that run on DOMAIN/IX.
The program supplies a default window called stdscr; you can
create others with newwin. Windows are referred to by vari-
ables 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 manipula-
tion 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.
Printed 12/4/86 CURSES-1
CURSES(3X) DOMAIN/IX SYS5 CURSES(3X)
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/roc/dumb, curses first
checks /usr/roc/dumb/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 per-
mission in /usr/lib/terminfo is not available.
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 horizontal
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 output
CURSES-2 Printed 12/4/86
CURSES(3X) DOMAIN/IX SYS5 CURSES(3X)
delch() Delete a character
deleteln() Delete a line
delwin(win) Delete win
doupdate() Update screen from all wnooutrefresh
echo()* Set echo mode
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
Printed 12/4/86 CURSES-3
CURSES(3X) DOMAIN/IX SYS5 CURSES(3X)
killchar() Return current user's kill character
leaveok(win, flag) OK to leave cursor anywhere after
refresh if flag!=0 for , otherwise cur-
sor 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)* 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)
CURSES-4 Printed 12/4/86
CURSES(3X) DOMAIN/IX SYS5 CURSES(3X)
mvwprintw(win, y, x, fmt, args)
mvwscanw(win, y, x, fmt, args)
newpad(nlines, ncols)
Create a new pad with given dimensions
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
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, smaxcol)
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 por-
tion 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
Printed 12/4/86 CURSES-5
CURSES(3X) DOMAIN/IX SYS5 CURSES(3X)
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) 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 typea-
head
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
CURSES-6 Printed 12/4/86
CURSES(3X) DOMAIN/IX SYS5 CURSES(3X)
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
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
Printed 12/4/86 CURSES-7
CURSES(3X) DOMAIN/IX SYS5 CURSES(3X)
include files, <curses.h> and <term.h>, should be included
to get the definitions for these strings, numbers, and
flags.
Parameterized 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
(called by setupterm)
resetterm() Reset tty modes to state before program
entry
setupterm(term, fd, rc)
Read in database; terminal type is char-
acter string term, all output is to UNIX
System file descriptor fd; status value
is returned in the integer pointed to by
rc (1 is normal); simplest call would be
setupterm(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 combina-
tion of the attributes listed below;
chars are passed to putchar-like func-
tion putc.
vidattr(attrs) Like vidputs but outputs through
putchar.
CURSES-8 Printed 12/4/86
CURSES(3X) DOMAIN/IX SYS5 CURSES(3X)
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
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
Printed 12/4/86 CURSES-9
CURSES(3X) DOMAIN/IX SYS5 CURSES(3X)
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
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), tic (1M)
CURSES-10 Printed 12/4/86