curses(3X) curses(3X)
NAME
curses - CRT screen handling and optimization package
SYNOPSIS
#include <curses.h>
cc [flags]files -lcurses [libraries]
DESCRIPTION
These routines give the user a method of updating screens
with reasonable optimization. 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, (most
interactive, screen oriented-programs want this) after
calling initscr() you should call ``nonl(); cbreak();
noecho();''
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 CRT screen. A default window called stdscr is supplied,
and others can be created 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.) Then
refresh() is called, telling the routines to make the users
CRT screen look like stdscr.
``Mini-Curses'' is a subset of curses which 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 full curses.
If the environment variable TERMINFO is defined, any program
using curses will check for a local terminal definition
before checking in the standard place. For example, if the
standard 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
directories.) However, if TERMINFO is set to
/usr/mark/myterms, curses will first check
/usr/mark/myterms/v/vt100, and if that fails, will then
check /usr/lib/terminfo/v/vt100. This is useful for
developing experimental definitions or when write permission
in /usr/lib/terminfo is not available.
Page 1 (last mod. 1/16/87)
curses(3X) curses(3X)
SEE ALSO
terminfo(4).
FUNCTIONS
Routines listed here may be called when using the full
curses. Those marked with an asterisk may be called when
using Mini-Curses.
addch(ch)* add a character to stdscr
(like putchar) (wraps to next
line at end of line)
addstr(str)* calls addch with each character in str
attroff(attrs)* turn off attributes named
attron(attrs)* turn on attributes named
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
vert and hor are chars to use 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
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) interrupts flush output if bf is TRUE
keypad(win, bf) enable keypad input
killchar() return current user's kill character
leaveok(win, flag) OK to leave cursor anywhere after refresh if
Page 2 (last mod. 1/16/87)
curses(3X) curses(3X)
flag!=0 for win, otherwise cursor must be left
at current position.
longname() return verbose name of terminal
meta(win, flag)* allow meta characters on input if flag != 0
move(y, x)* move to (y, x) on stdscr
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 dimensions
newterm(type, fd) set up new terminal of given type to output on fd
newindow(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,
sminrow, smincol, smaxrow, smaxcol)
like prefresh but with no output until
doupdate called
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
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
Page 3 (last mod. 1/16/87)
curses(3X) curses(3X)
resetty()* reset tty flags to stored value
saveterm()* save current modes as "in curses" state
savetty()* store current tty flags
scanw(fmt, arg1fP, 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
touchwindow(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
wattrst(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, arg1fP, arg2, ...)
printf on win
wrefresh(win) make screen look like win
wscanw(win, fmt, arg1fP, 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
These routines should be called by programs wishing to deal
directly with the terminfo database. Due to the low level
of this interface, it is discouraged. Initially, setupterm
should be called. This will define the set of terminal
Page 4 (last mod. 1/16/87)
curses(3X) curses(3X)
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
output 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 control 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 the
character string term, all output is to UNIX
System file descriptor fd. A status value is
returned in the integer pointed to by rc: 1
is normal. The simplest call would be
setupterm(0, 1, 0) which uses all defaults.
tparm(str, p1, p2, ..., p9)
instantiate string str with parms pi.
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, which is 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
programs that use termcap. Their parameters are the same as
for termcap. They are emulated using the terminfo database.
They may go away at a later date.
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
functions attron,attroff,attrset.
A_STANDOUT Terminal's best highlighting mode
Page 5 (last mod. 1/16/87)
curses(3X) curses(3X)
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
KEYBREAK 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 is 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)
WARNING
The plotting library plot(3X) and the curses library
curses(3X) both use the names erase() and move(). The
curses versions are macros. If you need both libraries, put
Page 6 (last mod. 1/16/87)
curses(3X) curses(3X)
the plot(3X) code in a different source file than the
curses(3X) code, and/or #undef move() and erase() in the
plot(3X) code. .
Page 7 (last mod. 1/16/87)