NAME

curses − CRT screen handling and optimization package

SYNOPSIS

#include <curses.h>
/usr/5bin/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 user’s 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/5lib/terminfo, and TERM is set to “vt100”, then normally the compiled file is found in /usr/5lib/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 /opusr/mark/myterms/v/vt100, and if that fails, will then check /usr/5lib/terminfo/v/vt100.  This is useful for developing experimental definitions or when write permission in /usr/5lib/terminfo is not available. 

SEE ALSO

ioctl(2), getenv(3), tty(4), terminfo(5V)

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 vert.
and hor. 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
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
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, 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
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 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
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

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 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

ATTRIBUTES

The following video attributes can be passed to the functions attron,attroff,attrset.

A_STANDOUTTerminal’s best highlighting mode
A_UNDERLINEUnderlining
A_REVERSEReverse video
A_BLINKBlinking
A_DIMHalf bright
A_BOLDExtra bright or bold
A_BLANKBlanking (invisible)
A_PROTECTProtected
A_ALTCHARSETAlternate 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. 

NameValueKey name
KEY_BREAK0401break key (unreliable)
KEY_DOWN0402The four arrow keys ...
KEY_UP0403
KEY_LEFT0404
KEY_RIGHT0405...
KEY_HOME0406Home key (upward+left arrow)
KEY_BACKSPACE0407backspace (unreliable)
KEY_F00410Function keys.  Space for 64 is reserved.
KEY_F(n)(KEY_F0+(n))      Formula for fn.
KEY_DL0510Delete line
KEY_IL0511Insert line
KEY_DC0512Delete character
KEY_IC0513Insert char or enter insert mode
KEY_EIC0514Exit insert char mode
KEY_CLEAR0515Clear screen
KEY_EOS0516Clear to end of screen
KEY_EOL0517Clear to end of line
KEY_SF0520Scroll 1 line forward
KEY_SR0521Scroll 1 line backwards (reverse)
KEY_NPAGE0522Next page
KEY_PPAGE0523Previous page
KEY_STAB0524Set tab
KEY_CTAB0525Clear tab
KEY_CATAB0526Clear all tabs
KEY_ENTER0527Enter or send (unreliable)
KEY_SRESET0530soft (partial) reset (unreliable)
KEY_RESET0531reset or hard reset (unreliable)
KEY_PRINT0532print or copy
KEY_LL0533home down or bottom (lower left)

WARNING

The plotting library plot(3X) and the curses library curses(3V) both use the names erase() and move().  The curses versions are macros. If you need both libraries, put the plot(3X) code in a different source file than the curses(3V) code, and/or #undef move() and erase() in the plot(3X) code.

Sun Release 3.5  —  Last change: 30 April 1986