NAME

curses() − CRT screen handling and optimization package

SYNOPSIS

#include <curses.h>

cc [flags] file ... -lcurses [libraries]

DESCRIPTION

These routines provide a method for updating screens with reasonable optimization.  To initialize curses routines, initscr() must be called before calling any other routine that deals with windows and screens.  endwin() should be called before exiting.  To get character-at-a-time input without echoing, (most interactive, screen oriented-programs need this) after calling initscr() the program 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 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 by using functions described below, among which the most basic are move(), and addch().  (More general versions of these functions are included.  Their names begin with w, allowing the programmer to specify a window.  Routines not beginning with w affect stdscr.)  Then refresh() is called, telling the routines to make the user’s CRT screen resemble 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 an option to the cc(1) command. 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 /usr/lib/terminfo, and TERM is set to vt100, the compiled file is normally 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 first checks /usr/mark/myterms/v/vt100, then, if that fails, checks /usr/lib/terminfo/v/vt100.  This is useful for developing experimental definitions, or when write permission in /usr/lib/terminfo is not available. 

Functions

All routines listed here can be called when using the full curses.  Those marked with an asterisk can be called when using Mini-Curses. 

addch(ch)* Add a character to stdscr (similar to putchar(); wraps to next line at end of line). 

addstr(str)* Call 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 type-ahead characters

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) Permissible 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) Similar to 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, outfd, infd) Set up new terminal of given type to output on outfd, using input (if needed) from infd

newwin(lines, cols, begin_y, begin_x)
Create a new window

nl()* Set new-line mapping

nocbreak()* Unset cbreak mode

nodelay(win, bf) Enable nodelay input mode through getch()

noecho()* Unset echo mode

nonl()* Unset new-line mapping

noraw()* Unset raw mode

overlay(win1, win2) Overlay win1 on win2

overwrite(win1, win2) Overwrite win1 on win2

pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol)
Similar to 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) Switch 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 type-ahead

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 that need to deal directly with the terminfo(4) database. Due to the low level of this interface, its use is discouraged. Initially, setupterm() should be called to define the set of terminal-dependent variables defined in terminfo(4). The header 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(4) 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 HP-UX 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) A 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

set_curterm(term) Set the database pointed to by term

del_curterm(term) Free the space pointed to by term

Termcap Compatibility Routines

These routines were included as a conversion aid for programs that use termcap.  Calling parameters are the same as for termcap.  They are emulated using the terminfo(4) database. Their use in new software is not recommended because they might be deleted in future HP-UX releases. 

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(), and 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

NLS Attributes

The following NLS attributes might be returned by inch():

A_FIRSTOF2 First byte of 16-bit character

A_SECOF2 Second byte of 16-bit character

Function Keys

The following function keys could possibly 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. 

NameValue Key name

KEY_BREAK0401 break key (unreliable)

KEY_DOWN0402 The four arrow keys ... 

KEY_UP0403

KEY_LEFT0404

KEY_RIGHT0405

KEY_HOME0406 Home key (upward+left arrow)

KEY_BACKSPACE0407 backspace (unreliable)

KEY_F00410 Function keys.  Space reserved for up to 64 keys. 

KEY_F(n)(KEY_F0+(n)) Formula for fn. 

KEY_DL0510 Delete line

KEY_IL0511 Insert line

KEY_DC0512 Delete character

KEY_IC0513 Insert char or enter insert mode

KEY_EIC0514 Exit insert char mode

KEY_CLEAR0515 Clear screen

KEY_EOS0516 Clear to end of screen

KEY_EOL0517 Clear to end of line

KEY_SF0520 Scroll 1 line forward

KEY_SR0521 Scroll 1 line backwards (reverse)

KEY_NPAGE0522 Next page

KEY_PPAGE0523 Previous page

KEY_STAB0524 Set tab

KEY_CTAB0525 Clear tab

KEY_CATAB0526 Clear all tabs

KEY_ENTER0527 Enter or send (unreliable)

KEY_SRESET0530 soft (partial) reset (unreliable)

KEY_RESET0531 reset or hard reset (unreliable)

KEY_PRINT0532 print or copy

KEY_LL0533 home down or bottom (lower left)

Window-Change Signal Support

All curses routines except the min-curses subset provide SIGWINCH support.  Applications that are linked with curses routines immediately redraw the screen in response to window size changes.  The environmental variables LINES and COLUMNS are also updated so that children processes work with the correct window size. 

If there is a window size reduction, part of the application display is trimmed.  The trimmed portion is saved in internal memory at the time of resize.  Moreover, this portion is not affected by the application as long as it stays invisible.  If the application’s cursor is trimmed, unexpected behavior results. 

On the other hand, if the window is enlarged, any previously trimmed area is re-displayed (and re-activated).  If the window is enlarged beyond its initial size, the extra area is padded with blank spaces. 

The default SIGWINCH support can be disabled by installing a custom SIGWINCH signal handler via the sigvector command (see sigvector(2)).

WARNINGS

HP supports only terminals listed on the current list of HP-supported devices.  However, the terminfo(4) database may contain information for other terminals besides those that are officially supported. If you use such unsupported terminals, they may not work correctly.

The endwin() routine does not release memory allocated by the initscr() routine. 
 Repeated calls to initscr() can cause a program to use more memory than was intended. 

Some of these routines call malloc() to allocate memory (see malloc(3C)) and can therefore fail for any of the reasons described in the malloc(3C) manual entry.

SEE ALSO

sigvector(2), terminfo(4). 

Using Curses and Terminfo, tutorial in Terminal Control User’s Guide. 

STANDARDS CONFORMANCE

curses(): SVID2, XPG2, XPG3, XPG4

Hewlett-Packard Company  —  HP-UX Release 9.0: August 1992