HPUX curses[3x]
curses(3X) curses(3X)
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.
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
curses(3X) curses(3X)
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
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
curses(3X) curses(3X)
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
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
curses(3X) curses(3X)
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
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992
curses(3X) curses(3X)
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
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) A handy function that calls
tputs(str, 1, putchar).
Hewlett-Packard Company - 5 - HP-UX Release 9.0: August 1992
curses(3X) curses(3X)
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
Hewlett-Packard Company - 6 - HP-UX Release 9.0: August 1992
curses(3X) curses(3X)
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.
Name Value Key name
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 reserved
for up to 64 keys.
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)
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
Hewlett-Packard Company - 7 - HP-UX Release 9.0: August 1992
curses(3X) curses(3X)
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 - 8 - HP-UX Release 9.0: August 1992