NAME
curses Library - Controls cursor movement and windowing
LIBRARY
Curses Library (libcurses.a)
SYNOPSIS
#include <curses.h>
#include <term.h>
DESCRIPTION
The curses library is a screen manipulation package. The
OSF/1 curses library provides interfaces from both the BSD
curses and the System V curses. Some interfaces, such as
addch() and waddch)(), are available from both curses
libraries. Others, such as addbytes(), are available only
for BSD curses applications. The following three list the
curses interfaces that are available to both System V and
BSD curses applications, to just System V applications, and
to BSD applications, respectively. Note that the BSD curses
are provided for compatibility only for existing BSD curses
applications. If you are writing a new curses application,
you should write one using System V curses.
In addition, the System V curses also includes minicurses.
The minicurses package is a subset of curses that does not
allow you to manipulate more than one window. This subset
is invoked with the -DMINICURSES option to cc. This subset
is smaller and faster than the full curses interface. Note
that the minicurses package is available only under the Sys-
tem V curses package.
The following tables summarize each curses function.
System V and BSD curses Functions
waddch() wgetch() waddstr() wgetstr() wmove()
wclear() werase() wclrtobot() wclrtoeol() winsertln()
wdeleteln() wrefresh() winch() winsch() wdelch()
wstandout() wstandend() wmove() addch() getch()
addstr() getstr() move() clear() erase()
clrtobot() clrtoeol() insertln() deleteln() refresh()
inch() insch() delch() standout() standend()
mvwaddch() mvwgetch() mvwaddstr() mvwgetstr() mvwinch()
mvwdelch() mvwinsch() mvaddch() mvgetch() mvaddstr()
mvgetstr() mvinch() mvdelch() mvinsch() initscr()
box() delwin() longname() mvprintw() mvscanw()
mvwin() mvwprintw() mvwscanw() newwin() overlay()
overwrite() printw() scanw() scroll() subwin()
touchwin() wprintw() wscanw() getyx() initscr()
newwin() erasechar() killchar() clearok() leaveok()
scrollok() raw() noraw() cbreak() nocbreak()
crmode() nocrmode() echo() noecho() nl()
nonl() savetty() resetty() baudrate() unctrl()
flushok()
System V-only curses Functions
wattron() wattroff() wattrset() attron() attroff()
attrset() setscrreg() wsetscrreg() newterm() makenew()
_outchar() putp() _tscroll() _tstp() vidattr()
newpad() newterm() nodelay() doupdate() fixterm()
flash() flushinp() has_ic() intrflush() keypad()
meta() prefresh() pnoutrefresh() resetterm() saveterm()
traceoff() traceon() typeahead() wnoutrefresh() delay_output()
has_il()
minicurses Functions
addch() addstr() move() clear() erase()
refresh() standout() standend() attron() attroff()
attrset() mvaddch() mvaddstr() initscr() newterm()
BSD-only curses Functions
addbytes() waddbytes() mvwaddbytes() mvaddbytes() tstp()
getcap() gettmode() mvcur() touchline() touchoverlap()
idlok() endwin()
By default, the curses package is set up to give you System
V curses. To compile a System V curses application, use the
following options:
cc program-name -lcurses
You compile a minicurses application with the following
options:
cc program-name -DMINICURSES -lcurses
To compile a BSD curses application, you use the following
options:
cc program-name -D_BSD -lcurses
Note that a curses application cannot have functions from
both BSD-only and System V-only curses.
The full curses interface allows you to manipulate struc-
tures called windows, which can be thought of as two-
dimensional arrays of characters representing all or part of
the screen. A default window (called stdscr) is supplied,
and you can create others using the newwin() function. Win-
dows are referred to by variables declared as type WINDOW *,
defined in the curses.h header file. (The term.h header
file should be used only for using the terminfo level func-
tions.)
Routine names beginning with "w" allow you to specify a win-
dow. Routine names not beginning with a "w" affect only
stdscr.
If your program needs only one terminal, you can specify the
-DSINGLE flag to the C compiler. This results in static
references instead of dynamic references to capabilities.
The result is more concise code, but only one terminal can
be used at a time for the program.
To initialize the functions which are described in the
curses library, you must call the initscr() function before
using any other functions which affect windows and screens,
and the endwin() function before exiting.
Screen Dimensions
The screen is a matrix of character positions that can con-
tain any character from the terminal's character set. The
actual dimensions of the matrix are different for each type
of terminal. These dimensions are defined when the initscr()
function calls the terminfo initialization function, setup-
term(). The functions enforce the following limits on the
terminal:
o If the terminal specification defines less than 5
lines, the functions use a value of 24 lines.
o If the terminal specification defines less than 5
columns, the functions use a value of 80 columns.
Note that line values (y coordinates) are specified first to
the library functions which request line and column values.
To update the screen, the functions must know what the
screen currently looks like and what it should be changed
to. The functions define the WINDOW data type to hold this
information. This data type is a structure that describes a
window image to the functions, including the starting posi-
tion on the screen (the (line, col) coordinates of the upper
left corner) and size.
You can think of a window as an array of characters on which
to make changes. Using the window, a program builds and
stores an image of a portion of the terminal that it later
transfers to the actual screen. When the window is complete,
use one of the following functions to transfer the window to
the terminal:
refresh Transfers the contents of stdscr to the terminal.
wrefresh Transfers the contents of a named window (not
stdscr) to the terminal.
This two-step process maintains several different copies of
a window in memory and selects the proper one to display at
any time. In addition, the program can change the contents
of the screen in any order. When it has made all of the
changes, the library functions update the terminal in an
efficient manner.
The Curses Routines
The curses functions are summarized below:
int addch( chtype ch );
Add a character to stdscr, wrapping to the next
line at the end of a line (like putchar()). May
be called with minicurses.
int waddch( WINDOW *win, chtype ch );
Add character ch to window win.
int mvwaddch( WINDOW *win, int y, int x, chtype ch );
Move to position (y, x), then add character ch to
window win.
int addstr( char *str );
Call addch() with each character in string str.
May be used with minicurses.
int mvaddstr( int y, int x, char *str );
Move to position (y, x), then add string str. May
be used with minicurses.
int waddstr( WINDOW *win, char *str );
Add string str to window win.
int mvwaddstr( WINDOW *win, int y, int x, char *str );
Move to position (y, x), then add string str to
window win.
int attroff( chtype attrs );
Turn offattributes named in list attrs. May be
used with minicurses.
int attron( chtype attrs );
Turn onattributes named in list attrs. May be
used with minicurses.
int attrset( chtype attrs );
Set currentattributes to those specified in list
attrs. May be used with minicurses.
int baudrate ( void );
Query current terminal speed.
int beep ( void );
Sound beep on terminal.
int box( WINDOW *win, chtype vert, chtype hor );
Draw a box around edges of window win. The vert
and hor parameters are the characters to use for
vertical and horizontal edges of the box.
int cbreak ( void );
Set cbreak() mode.
int nocbreak ( void );
Unset cbreak() mode.
int clear ( void );
Clear stdscr. May be used with minicurses.
int clearok( WINDOW *win, bool bool_flag );
Clear screen before next redraw of window win if
bool_flag is true.
int clrtobot ( void );
Clear to bottom of stdscr.
int clrtoeol ( void );
Clear to end of line on stdscr.
int delay_output( int ms );
Insert pause of ms milliseconds in output.
int nodelay( WINDOW *win, bool bool_flag );
Enable nodelay() input mode through getch() on
window win if bool_flag is true.
int delch ( void );
Delete a character.
int deleteln ( void );
Delete a line.
int delwin( WINDOW *win );
Delete window win.
int doupdate ( void );
Update screen from all wnoutrefresh().
int echo ( void );
Set echo mode.
int noecho ( void );
Unset echo mode.
int endwin ( void );
End window mode.
int erase ( void );
Erase stdscr. May be used with minicurses.
char erasechar ( void );
Return user's erase character.
int fixterm ( void );
"Restore terminal to "in curses" state.
int flash ( void );
Flash screen or beep.
int flushinp ( void );
Throw away any data in type-ahead.
int flushok ( WINDOW *win, bool bool_flag );
Set the flush-on-refresh flag for window win to be
bool_flag.
int getch ( void );
Get a character from stdscr. The following list
contains the function keys that might be returned
by the getch() function if keypad() has been
enabled. Due to lack of definitions in terminfo,
or due to the terminal not transmitting a unique
code when the key is pressed, not all of these
keys are supported.
KEY_BREAK Break key (unreliable)
KEY_DOWN Down arrow key
KEY_UP Up arrow key
KEY_LEFT Left arrow key
KEY_RIGHT Right arrow key
KEY_HOME Home key
KEY_BACKSPACE
Backspace (unreliable)
KEY_F(n) Function key Fn, where n is an integer from 0 to
63
KEY_DL Delete line
KEY_IL Insert line
KEY_DC Delete character
KEY_IC Insert character or enter insert mode
KEY_EIC Exit insert character mode
KEY_CLEAR Clear screen
KEY_EOS Clear to end of screen
KEY_EOL Clear to end of line
KEY_SF Scroll one line forward
KEY_SR Scroll one line backwards (reverse)
KEY_NPAGE Next page
KEY_PPAGE Previous page
KEY_STAB Set tab
KEY_CTAB Clear tab
KEY_CATAB Clear all tabs
KEY_ENTER Enter or send (unreliable)
KEY_SRESET
Soft (partial) reset (unreliable)
KEY_RESET Reset or hard reset (unreliable)
KEY_PRINT Print or copy
KEY_LL Home down or bottom (lower left)
KEY_A1 Upper left key of keypad
KEY_A3 Upper right key of keypad
KEY_B2 Center key of keypad
KEY_C1 Lower left key of keypad
KEY_C3 Lower right key of keypad
char *getcap ( char *cap_name );
Get terminal capability cap_name.
int getstr( char *str );
Get the string through stdscr.
int gettmode ( void );
Get current tty modes.
int getyx( WINDOW *win, int y, int x );
Get (y, x) coordinates from window win.
bool has_ic ( void );
Has value of TRUE if terminal can insert charac-
ter.
bool has_il ( void );
Has value of TRUE if terminal can insert line.
int idlok( WINDOW *win, bool bool_flag );
Use terminal's insert/delete line on window win if
bool_flag is true.
chtype inch ( void );
Get character at current (y, x) coordinates.
WINDOW *initscr ( void );
Initialize screens. May be used with minicurses.
int insch( chtype ch );
Insert character ch.
int insertln ( void );
Insert a line.
int intrflush( WINDOW *win, bool bool_flag );
Interrupt flush output on window win if bool_flag
is true.
int keypad( WINDOW *win, bool bool_flag );
Enable keypad input on window win if bool_flag is
true.
char killchar ( void );
Return current user's kill() character.
int leaveok( WINDOW *win, bool bool_flag );
Permit cursor to be left anywhere after refresh
for window win if bool_flag is true; otherwise
cursor must be left at current position.
char *longname ( void );
Return verbose name of terminal.
char *longname( char *termbuf, char *name );
Set name to the full name of the terminal
described by termbuf. Used in programs that are
compiled with the -D_BSD option to provide BSD
compatibility.
char meta( WINDOW *win, bool bool_flag );
Allow metacharacters on input from window win if
bool_flag is true.
int move( int y, int x );
Move to position (y, x) on stdscr. May be used
with minicurses.
int mvaddch( int y, int x, chtype ch );
Move to position (y, x), then add character ch.
May be used with minicurses.
char mvcur( int y1, int x1, int y2, int x2 );
Move cursor from current position (y1,x1) to new
position (y2,x2).
int mvdelch( int y, int x );
Move to position (y, x), then delete a character.
int mvgetch( int y, int x );
Move to position (y, x), then get a character from
the terminal.
int mvgetstr( int y, int x, char *str );
Move to position (y, x), then get the str string
from the terminal.
chtype mvinch( int y, int x );
Move to position (y, x) then get the character at
current (y, x) coordinates.
int mvinsch( int y, int x, chtype ch );
Move to position (y, x) then insert the character
ch.
int mvprintw( int y, int x, char *fmt [, args ] );
Move to position (y, x), then get print on stdscr.
int mvscanw( int y, int x, char *fmt [, args ] );
Move to position (y, x), then scan through stdscr.
int mvwdelch( WINDOW *win, int y, int x );
Move to position (y, x), then delete a character
from win.
int mvwgetch( WINDOW *win, int y, int x );
Move to position (y, x), then get a character
through win.
int mvwgetstr( WINDOW *win, int y, int x, char *str );
Move to position (y, x), then get a string through
win.
int mvwin( WINDOW *win, int y, int x );
Move win so that the upper left corner is located
at position (y, x).
chtype mvwinch( WINDOW *win, int y, int x );
Move to position (y, x) in win, then get the char-
acter at the new position.
int mvwinsch( WINDOW *win, int y, int x, chtype ch );
Move to position (y, x), then insert the character
ch into win.
int mvwprintw( WINDOW *win, int y, int x, char *fmt [, args ] );
Move to position (y, x) then printf() on stdscr.
int mvwscanw( WINDOW *win, int y, int x, char *fmt [, args ] );
Move (y, x) then scanf() through stdscr.
WINDOW *newpad( int nlines, int ncols );
Create a new pad with given dimensions.
SCREEN *newterm( char *type, FILE outfd, FILE infd );
Set up new terminal of given type to output on
outfd and input from infd. May be used with mini-
curses.
WINDOW *newwin( int lines, int cols, int begin_y, int begin_x );
Create a new window.
int nl ( void );
Set new line mapping.
int nonl ( void );
Unset new line mapping.
int overlay( WINDOW *win1, WINDOW *win2 );
Overlay win1 on win2. The overlaying window (win1)
takes as its origin the window being overlayed
(win2).
int overwrite( WINDOW *win1, WINDOW *win2 );
Overwrite win1 on win2.
int printw( char *fmt [, arg1, arg2, ... ] );
Print on stdscr.
int raw ( void );
Set raw mode.
int refresh ( void );
Make current screen look like stdscr. May be used
with minicurses.
int smincol,
int prefresh( WINDOW *pad, int pminrow, int pmincol, int sminrow,
int smaxrow, int smaxcol );
Refresh from pad starting with given upper left
corner of pad with output to given portion of
screen.
int pnoutrefresh(WINDOW *pad, int pminrow, int pmincol,
int sminrow, int smincol, int smaxrow, int smax-
col);
Refresh like prefresh(), but with no output until
doupdate() is called.
int noraw ( void );
Unset raw mode.
int resetterm ( void );
Set tty" modes to "out of curses" state.
int resetty ( void );
Reset tty flags to stored value.
int saveterm ( void );
"Save current modes as "in curses" state.
int savetty ( void );
Store current tty flags.
int scanw( char *fmt [, arg1, arg2, ... ] );
Scanf through stdscr.
int scroll( WINDOW *win );
Scroll win one line.
int scrollok( WINDOW *win, bool bool_flag );
Allow terminal to scroll if bool_flag is true.
SCREEN *set_term( SCREEN *new );
Enable talk to terminal new.
int setscrreg( int top, int bottom );
Set user scrolling region to lines top through
bottom.
void setterm( char *type );
Establish terminal with a given type.
int standend ( void );
Clear standout mode attribute. May be used with
minicurses.
int standout ( void );
Set standout mode attribute. May be used with
minicurses.
int begin_x );
WINDOW *subwin( WINDOW *win, int lines, int cols, int begin_y,
Create a subwindow.
int touchline( WINDOW *win, int y, int firstcol, int numcol );
Mark numcol columns, starting at column firstcol,
of line y as changed.
int touchoverlap( WINDOW *win1, WINDOW *win2 );
Mark overlap of win1 on win2 as changed.
int touchwin( WINDOW *win );
Change all of win.
int traceoff ( void );
Turn off debugging trace output.
int traceon ( void );
Turn on debugging trace output.
int typeahead( FILE fd );
Check file descriptor fd to check type-ahead.
char *unctrl( chtype ch );
Use printable version of ch.
int wattroff( WINDOW *win, int attrs );
Turn off attrs in win.
int wattron( WINDOW *win, int attrs );
Turn on attrs in win.
int wattrset( WINDOW *win, int attrs );
Set attributes in win to attrs.
int wclear( WINDOW *win );
Clear win.
int wclrtobot( WINDOW *win );
Clear to bottom of win.
int wclrtoeol( WINDOW *win );
Clear to end of line on win.
int wdelch( WINDOW *win );
Delete the current character from win.
int wdeleteln( WINDOW *win );
Delete line from win.
int werase( WINDOW *win );
Erase win.
int wgetch( WINDOW *win );
Get a character through win.
int wgetstr( WINDOW *win, char *str );
Get the string str through win.
chtype winch( WINDOW *win );
Get the character at current (y, x) in win.
int winsch( WINDOW *win, chtype ch );
Insert the character ch into win.
int winsertln( WINDOW *win );
Insert line into win.
int wmove( WINDOW *win, int y, int x );
Set current (y, x) coordinates on win.
int wnoutrefresh( WINDOW *win );
Refresh but no screen output.
int wprintw( WINDOW *win, char *fmt [, arg1, arg2, ... ] );
printf() on win.
int wrefresh( WINDOW *win );
Make screen look like win.
int wscanw( WINDOW *win, char *fmt [, arg1, arg2,... ] );
scanf() through win.
int wsetscrreg( WINDOW *win, int top, int bottom );
Set scrolling region of win.
int wstandend( WINDOW *win );
Clear standout attribute in win.
int wstandout( WINDOW *win );
Set standout attribute in win.
int crmode( void );
Set cbreak() mode.
int nocrmode( void );
Unset cbreak() mode.
WINDOW *makenew ( int lines, int cols, int begin_y, begin_x );
Sets up a window buffer and returns a pointer to
it.
int _outchar ( char ch );
Writes a character or word to a stream to be
passed to the tputs() routine.
int _tscroll ( register WINDOW *win );
Scrolls win's lines up and inserts a blank line.
void _tstp ( void );
Handles stop and start signals.
Terminfo Level Functions
These functions should be called by programs that have to
deal directly with the terminfo database. Due to the low
level of this interface, its use is discouraged.
To use the terminfo level functions of curses, include the
curses.h and term.h files, in that order, to get the defini-
tions for these strings, numbers, and flags. Programs should
call the setupterm() function before using any of the other
terminfo functions. The setupterm() function defines the set
of terminal-dependent variables defined in the terminfo
file.
All terminfo strings (including the output of the tparm()
parameter) should be printed using the tputs() or putp()
function. Before exiting, your program should call the
reset_shell_mode() function to restore the tty modes. Pro-
grams desiring shell escapes can call the reset_shell_mode()
function before the shell is called, and the
reset_prog_mode() function after returning from the shell.
int delay_output ( int ms );
Sets the output delay, in milliseconds.
int def_prog_mode( void );
Saves the current terminal mode as program mode,
in cur_term->Nttyb.
int def_shell_mode( void );
Saves the shell mode as normal mode, in cur_term-
>Ottyb. The def_shell_mode() function is called
automatically by setupterm() function.
int putp( char *str );
Calls tputs()( char *str, 1, putchar()).
int reset_prog_mode ( void );
Puts the terminal into program mode.
int reset_shell_mode ( void );
Puts the terminal into shell mode. All programs
must call the reset_shell_mode() function before
they exit. The higher-level function endwin()
automatically does this.
int setupterm( char *term, int fd, int rc );
Reads in the database. The term parameter is a
character string that specifies the terminal name.
If term is 0 (zero), then the value of the TERM
environment variable is used. One of the following
status values is stored into the integer pointed
to by the rc parameter:
1 Successful completion.
0 No such terminal.
-1 An error occurred while locating the terminfo
database.
If the rc parameter is 0 (zero), then no status
value is returned, and an error causes the setup-
term() function to print an error message and
exit, rather than return. The fd parameter is the
file descriptor of the terminal being used for
output. The setupterm() function calls the
TIOCGWINSZ ioctl function to determine the number
of lines and columns on the display. If termdef
cannot supply this information, then the setup-
term() function uses the values in the terminfo
database. The simplest call is setupterm(0,1,0),
which uses all the defaults.
After the call to the setupterm() function, the
global variable cur_term is set to point to the
current structure of terminal capabilities. It is
possible for a program to use more than one termi-
nal at a time by calling the setupterm() function
for each terminal and saving and restoring
cur_term.
The setupterm() function also initializes the glo-
bal variable ttytype as an array of characters to
the value of the list of names for the terminal.
The list comes from the beginning of the terminfo
description.
char *tparm( char *format [ , arg, ... ]);
Instantiates the format string format, and one or
more arguments of varying type. The character
string returned has the given parameters applied.
void tputs( char *str, int affcnt, int (*putc)();
Applies padding information to string str. The
affcnt parameter is the number of lines affected,
or 1 if not applicable. The putc parameter func-
tion is similar to putchar() to which the charac-
ters are passed one at a time.
Some strings are of a form similar to $<20>, which
is an instruction to pad for 20 milliseconds.
void vidputs( int *attrs, int (*putc)();
Outputs the string to put terminal in video attri-
bute mode attrs. Characters are passed to the putc
function. The attrs are defined in curses.h. The
previous mode is retained by this function.
void vidattr( int attrs );
Like vidputs(), but outputs through putchar().
Termcap Compatibility Functions
These functions are included for compatibility with programs
that require termcap. Their parameters are the same as for
termcap, and they are emulated using the terminfo database.
int tgetent( char *bp, char *name );
Looks up the termcap entry for name. Both bp and
name are strings. The name parameter is a terminal
name; bp is ignored. Calls the setupterm() func-
tion.
int tgetflag( char *id );
Returns the Boolean entry for id, which is a 2-
character string that contains a termcap
identifier.
int tgetnum( char *id );
Returns the numeric entry for id, which is a 2-
character string that contains a termcap identif-
ier.
char *tgetstr( char *id, char *area );
Returns the string entry for id, which is a 2-
character string that contains a termcap identif-
ier. The area parameter is ignored.
char *tgoto( char *cap, int col, int row );
Applies parameters to the given cap. Calls the
tparm() function.
void tputs( char *cap, int affcnt, int (*fn)();
Applies padding to cap calling fn as putchar().
RELATED INFORMATION
Functions: termcap(3)
Files: terminfo(4)
Acknowledgement and Disclaimer