intro(3cur)intro(3cur)Nameintro - introduction to the X/Open Curses Package, which optimizes ter‐
minal screen handling and updating
Syntax
#include <cursesX.h>
cc [ options ] files -lcursesX [ libraries ]
Description
The (cursor optimization) package is the X/Open set of library routines
used for writing screen-management programs. Cursor optimization mini‐
mizes the amount the cursor has to be moved around the screen in order
to update it. Screen-management programs are used for tasks such as
moving the cursor, printing a menu, dividing a terminal screen into
windows or drawing a display on a screen for data entry and retrieval.
The package is split into three parts: screen updating, screen updating
with user input, and cursor motion optimization. Screen-updating rou‐
tines are used when parts of the screen need to be changed but the
overall image remains the same. The cursor motion part of the package
can be used separately for tasks such as defining how the cursor moves
in response to tabs and newline characters
The routines do not write directly to the terminal screen (the physical
screen): instead, they write to a window, a two-dimensional array of
characters which represents all or part of the terminal screen. A win‐
dow can be as big as the terminal screen or any smaller size down to a
single character.
The header file supplies two default windows, (standard screen) and
(current screen) for all programs using routines. The window is the
size of the current terminal screen. The window is not normally
accessed directly by the screen-management program; changes are made to
the appropriate window and then the routine is called. The screen pro‐
gram keeps track of what is on the physical screen and what is on When
is called, it compares the two screen images and then sends a stream of
characters to the terminal to make the physical screen look like
The header file defines to be of the type This is a pointer to a C
structure which includes the starting position of the window on the
screen and the window size.
Some routines are designed to work with a A pad is a type of window
whose size is not restricted by the size of the screen. Use a pad when
you only need part of a window on the screen at any one time, for exam‐
ple when running a spreadsheet application.
Other windows can be created with and used instead of for maintaining
several different screen images, for example, one window can control
input/output and another can display error messages. The routine cre‐
ates subwindows within windows. When windows overlap, the contents of
the current screen show the most recently refreshed window.
Among the most basic routines are and These routines are used to move
the cursor around and to add characters to the default window,
All data is manipulated using the routines provided by the library.
You should not use routines or system calls from other libraries in a
program as they may cause undesirable results when you run the program.
Using Curses
The library has three types of routines; Main routines, TERMINFO rou‐
tines and TERMCAP compatibility routines
The routines are a group of routines within the library which provide a
database containing descriptions of many terminals that can be used
with programs. The termcap compatibility routines are provided as a
conversion aid for programs using termcap.
Most screen handling can be achieved using the Main routines. The fol‐
lowing hints should help you make the most of the screen-handling rou‐
tines.
The header file must always be included whenever functions are used in
a program. Note that the header file includes to enable the terminal to
use the features provided by ULTRIX. All the manual definitions assume
that has been included in the code.
The header file defines global variables and data structures, and
defines several of the routines as macros. The integer variables and
are defined so that when a program is run on a particular terminal,
assigns the vertical and horizontal dimensions of the terminal screen
to these variables.
A program must start by calling the routine to allocate memory space
for the windows. It should only be called once in a program, as it can
overflow core memory if it is called repeatedly. The routine is used
to exit from the screen-handling routines.
Most interactive screen-oriented programs need character-at-a-time
input without echoing. To achieve this, you should call:
nonl();
cbreak();
noecho();
immediately after calling All routines that move the cursor, move it
relative to the home position in the upper left corner of the screen.
The coordinate at this position is (1,1). Note that the vertical coor‐
dinate is given first and the horizontal coordinate is given second.
The -1 in the example program takes the home position into account to
place the cursor on the centre line of the terminal screen. The exam‐
ple program displays MIDSCREEN in the centre of the screen. Use the
routine after changing a screen to make the terminal screen look like
Example Program ®
#include <cursesX.h>
main ()
{
initscr(); /*initialize terminal settings, data
** structures and variables*/
move(LINES/2 -1, COLS/2 -4);
addstr("MID");
refresh(); /* send output to update terminal
** screen */
addstr("SCREEN");
refresh(); /* send more output to terminal
** screen */
endwin(); /*restore all terminal settings */
}
Main Routines
Routines listed here can be called when using the library. Routines
that are preceded by a w affect a specified window, those preceded by a
p affect a specified pad. All other routines affect the default window
Windows are specified by a numeric argument, for example: (win) where
win is the specified window.
addch(ch) Add a character to stdscr (like putchar wraps
to next line at end of line)
addstr(str) Call addch with each character in str
attroff(attrs) Turn off named attributes
attron(attrs) Turn on named attributes
attrset(attrs) Set current attributes to attrs
baudrate() Display current terminal speed
beep() Sound beep on terminal
box(win, vert, hor) Draw a box around edges of win,
vert and hor are characters 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 wnoutrefresh
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 character from tty
getstr(str) Get a string through stdscr
gettmode() Establish current tty modes
getyx(win, y, x) Get (y, x) coordinates
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 character at current (y, x) coordinates
initscr() Initialize screens
insch(c) Insert a character
insertln() Insert a line
intrflush(win, bf) Interrupt flush output if bf is TRUE
keypad(win, bf) Enable keypad input
killchar() Return current user's kill character
leaveok(win, flag) 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
NOTE: The following routines prefixed with mv require and coordinates
to move to, before performing the same functions as the standard rou‐
tines. As an example, performs the same function as and coordinates
must be supplied first. The routines prefixed with mvw also require a
window or pad argument.
mvaddch(y, x, ch)
mvaddstr(y, x, str)
mvcur(oldrow, oldcol, newrow, low level cursor motion
newcol)
mvdelch(y, x)
mvgetch(y, x)
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, Create a new window
begin_y, begin_x)
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, Like prefresh but with no output
pmincol, sminrow, smincol, until doupdate called
smaxrow, smaxcol)
prefresh(pad, pminrow, Refresh from pad starting with given
upper
pmincol, sminrow, smincol, left corner of pad with output to
smaxrow, smaxcol) 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 between different terminals
setscrreg(t, b) Set user scrolling region to lines t
through b
setupterm(term, filenum, errret) Low level terminal setup
standend() Clear standout mode attribute
standout() Set standout mode attribute
subwin(win, lines, cols, Create a subwindow
begin_y, begin_x)
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 typea‐
head
unctrl(ch) Produce printable version of ch
waddch(win, ch) Add character 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 character through win
wgetstr(win, str) Get a string through win
winch(win) Get character 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) coordinates on win
wnoutrefresh(win) Refresh but no screen output
wprintw(win, fmt, printf on win
arg1, arg2, ...)
wrefresh(win) Make screen look like win
wscanw(win, fmt, scanf through win
arg1, arg2, ...)
wsetscrreg(win, t, b) Set scrolling region of win
wstandend(win) Clear standout attribute in win
wstandout(win) Set standout attribute in win
Caution
The plotting library and the library both use the names and The ver‐
sions are macros. If you need both libraries, put the code in a dif‐
ferent source file to the code, and/or and in the code.
TERMINFO Level Routines
If the environment variable TERMINFO is defined, any program using will
check for a local terminal definition before checking in the standard
libraries. For example, if the standard place is set to vt100, the
compiled file will normally be found in The v is copied from the first
letter of vt100 to avoid creating huge directories. However, if TER‐
MINFO is set to will first check and if that fails, will then check
This is useful for developing experimental definitions or when there is
no write permission for
These routines should be called by programs that need to deal directly
with the database, but as this is a low level interface, it is not rec‐
ommended.
Initially, the routine should be called. This will define the set of
terminal-dependent variables defined in The include files and should be
included to get the definitions for these strings, numbers, and flags.
Parameterized strings should be passed through to instantiate them.
All terminfo strings (including the output of should be printed with or
Before exiting, should be called to restore the tty modes.
Programs which want shell escapes or suspending can call before the
shell is called and 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 ULTRIX
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 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
The following 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 database.
DO NOT use these routines in new programs.
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
As an aid to compatibility, the object module has been provided in This
module should be linked into an application before resolving against
the library. If your application contains references such as then
recompile using
cc [options] files /usr/lib/termcap.o -lcursesX [libs]
Errors
No errors are defined for the functions.
Return Values
For most routines, the value is returned if a routine is properly com‐
pleted and the value is returned if some error occurs.
See Alsotic(1), ioctl(2), getenv(3), printf(3s), putchar(3s), scanf(3s),
plot(3x), termcap(5), terminfo(5)
Guide to X/Open curses Screen Handling
intro(3cur)
