NAME

curses − CRT screen handling and optimization package

SYNOPSIS

#include <curses.h>
cc [ flags ] files −lcurses [ libraries ]

HP-UX COMPATIBILITY

Level: HP-UX/NUCLEUS

Origin: System V

DESCRIPTION

These routines provide a means for updating screens with reasonable optimization.  To ensure proper initialization, the routine initscr() must be called before any other routines that deal with windows and screens are used.  The endwin() routine should be called before exiting to restore conditions as they existed prior to program entry.  Character-at-a-time input without echoing (used in most interactive, screen oriented-programs), is obtained by calling “nonl(); cbreak(); noecho();” after calling initscr().

The full-curses interface provides a means for manipulating window data structures.  Windows 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.  Other windows can be created by using 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.  Two simple (and widely used) examples are move and addch.  (More-general versions of these functions are provided. Their names begin with ‘w’, to signify that you can specify the window to be used.  Routines not beginning with ‘w’ affect only stdscr.)  After manipulation, refresh() is called to make the user’s CRT screen look like stdscr. 

Mini-Curses is a subset of curses.  It only supports manipulation of the standard 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 checks for a local terminal definition before checking in the standard place.  For example, if the standard place is /users/lib/terminfo, and TERM is set to “hp2623”, the compiled file is normally found in /users/lib/terminfo/h/hp2623 (the “h” is copied from the first letter of “hp2623” to avoid creation of huge directories).  However, if TERMINFO is set to /users/mark/myterms, curses first checks /users/mark/myterms/h/hp2623, then, if that fails, checks /usr/lib/terminfo/h/hp2623.  This is useful when developing experimental definitions and when write permission in /users/lib/terminfo is not available. 

SEE ALSO

terminfo(5) and termcap(3). 

FUNCTIONS

All routines listed here are fully accessible to full curses.  Those marked with an asterisk are also available to Mini-Curses. 

addch(ch)*add a character to (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
baud rate()*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
cbreak()*set 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
delch()delete a character
deleteln()delete a line
delwin(win)delete win
doupdate()update screen from all wnooutrefresh
draino(ms)drain output to ms milliseconds
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()dummy entry point.  Does nothing.
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)*move(y, x) then addstr(str)
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, str)
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, str)
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)
napms(ms)suspend program for ms milliseconds
newpad(nlines, ncols)create a new pad with given dimensons  s
newterm(type, fpout, fpin)*set up new terminal of given type to I/O on fpout/fpin.
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)*set the current terminal to new
setscrreg(t, b)set user scrolling region to lines t through b
setterm(type)establish terminal with given type
setupterm(term, filenum, errret)initialize specified terminal
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()dummy entry point.  Does nothing
traceon()dummy entry point.  Does nothing
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(5).  The 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 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, but they are emulated using the terminfo database.  They may be removed 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_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 are returned by getch if keypad has been enabled and the function is supported.  Note that some of these may not be currently supported due to lack of definitions in terminfo, or because the terminal does not transmit 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(3X) 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(3X) code, and/or #undef move() and erase() in the plot(3X) code.

Hewlett-Packard  —  last mod. May 11, 2021