NAME

curses_intro − Introduction to the curses routines that optimize terminal screen handling and updating

SYNOPSIS

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

DESCRIPTION

The curses (cursor optimization) package is a set of library routines that you can use to write screen-management programs.  Cursor optimization minimizes the number of times 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 curses package is split into three parts: screen updating, screen updating with user input, and cursor motion optimization.  Use the screen-updating routines (with or without user input) when parts of the screen need to be changed but the overall image remains the same.  Use the cursor motion routines for tasks such as defining how the cursor moves in response to tabs and newline characters. 

The curses routines do not write directly to the terminal screen (the physical screen); instead, they write to a window, a two-dimensional array of characters that represents all or part of the terminal screen. A window can be as big as the terminal screen or any smaller size down to a single character. 

The <curses.h> header file supplies two default windows, stdscr (standard screen) and curscr (current screen) for all programs using curses routines.  The stdscr window is the size of the current terminal screen.  Usually, you do not directly access the curscr window with your screen-management program; your program makes changes to the appropriate window and then calls the refresh routine.  The screen program keeps track of what is on the physical screen and what is on stdscr.  When your program calls the refresh() routine, the screen program compares the two screen images and then sends a stream of characters to the terminal to make the physical screen look like stdscr. 

The header file <curses.h> defines stdscr to be of the type WINDOW∗. This type is a pointer to a C structure that includes the starting position of the window on the screen and the window size. 

Some curses routines are designed to work with a pad.  A pad is a type of window whose size is not restricted by the size of the screen.  Use a pad when you need only part of a window on the screen at any one time, for example, when running a spreadsheet application. 

Your program may need to maintain several different screen images, for example, use one window to control input/output and another to display error messages.  In this case, you can create windows with the newwin routine and use those windows instead of stdscr.  Use the subwin routine to create subwindows within windows.  When windows overlap, the contents of the current screen show the most recently refreshed window. 

Among the most basic routines are move and addch.  Use these routines to move the cursor around and to add characters to the default window, stdscr. 

The curses library also provides additional routines, based on the specification of "Unix System V Release 4 Multi-National Language Supplement (SVR4 MNLS)," to process Asian language characters encoded in wchar_t format. 

Use only the routines provided by the curses library to manipulate data in a curses program.  Using routines from other libraries to manipulate data that is also used by the curses routines may cause undesirable results when your program runs. 

Using Curses

The curses library has two types of routines: Main routines and terminfo routines. 

The terminfo routines are a group of routines within the curses library. They provide a database containing descriptions of many terminals that you can use with curses programs.  To use the terminfo level routines in your program:

       •Include the <curses.h> and <term.h> files, in that order. 

       •Call the setupterm() function. 

Use the Main routines for most screen handling.  Follow these guidelines to use screen-handling routines correctly:

       •Include the <curses.h> header file whenever you use curses functions in a program. 

The header file defines global variables and data structures and defines several of the routines as macros.  The integer variables LINES and COLS are defined so that when a curses program is run on a particular terminal, initscr assigns the vertical and horizontal dimensions of the terminal screen to these variables. 

       •Start your curses program by calling the routine initscr to allocate memory space for the windows. 

Call initscr only once in a program because the routine can overflow core memory if it is called repeatedly. 

       •Use the routine endwin to exit from the screen-handling routines. 

       •Most interactive screen-oriented programs need character-at-a-time input without echoing.  To meet this need, call the following routines immediately after calling initscr:

nonl();
cbreak();
noecho();

       •All curses routines that move the cursor, move it relative to the home position in the upper left corner of the screen. The (LINES, COLS) coordinate at this position is (1,1). 

When specifying cursor position (y, x) to routines that move the cursor, specify the vertical coordinate y first and the horizontal coordinate x second. 

Sample Program 1

The following program displays the text "MIDSCREEN" on the center line of the terminal screen.  The −1 in the program takes the home position into account to place the cursor on the center line of the terminal screen.  The program uses the refresh routine after changing a screen to make the terminal screen look like stdscr. 

#include <curses.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 ∗/
}

Sample Program 2

The following program also displays text on the center line of the terminal screen but contains routines that can handle text in different languages. 

/∗ sample program using SVR4 MNLS routines ∗/
#include <stdlib.h>
#include <locale.h>
#include <curses.h>
main ()
{
wchar_t wcs[20];
setlocale(LC_ALL, "");/∗ set locale from environment variable ∗/
mbstowcs(wcs, "SCREEN", 6); /∗ convert char string to wchar_t string ∗/
initscr();/∗initialize terminal settings, data
∗∗ structures and variables∗/
move(LINES/2 −1, COLS/2 −4);
addwstr(wcs);
refresh();/∗ send output to update terminal
                ∗∗  screen ∗/
endwin();/∗restore all terminal settings ∗/
}

The Main Routines

The following list summarizes routines in the Main subset of the curses library.  Routines whose names begin with w affect a specified window.  Specify a window by using a numeric argument, for example: winch (win) where win is a number that identifies the window.  The pnoutrefresh and prefresh routines affect a specified pad.  All other routines affect the default window stdscr. 

addch(ch)Adds a character to stdscr (like putchar, wraps to next line at end of line). 

addnwstr(wstr, n)
Calls addwch with the first n wchar_t characters in string wstr. 

addwch(wch)
Adds a wchar_t character to stdscr (like putwchar, wraps to next line at end of line). 

addstr(str)Calls addch with each character in str. 

addwchnstr(wchstr, n)
Adds a string of wchar_t characters (and attributes) to stdscr. 

addwchstr(wchstr)
Adds a string of wchar_t characters (and attributes) to stdscr. 

addwstr(wstr)
Calls addwch with each wchar_t character in string wstr. 

attroff(attrs)
Turns off named attributes.

attron(attrs)
Turns on named attributes.

attrset(attrs)
Sets current attributes to attrs. 

baudrate()Displays current terminal speed. 

beep()Sounds beep on terminal. 

box(win, vert, hor)
Draws a box around edges of win; vert and hor are the characters to use for the vertical and horizontal edges of the box. 

clear()Clears stdscr. 

clearok(win, bf)
Clears screen before next redrawing of win. 

clrtobot()Clears to bottom of stdscr. 

clrtoeol()Clears to end of line on stdscr. 

cbreak()Sets cbreak mode. 

delay_output(ms)
Inserts an ms millisecond pause in output. 

delch()Deletes a character. 

deleteln()Deletes a line. 

delwin(win)Deletes win. 

doupdate()Updates screen from all wnoutrefresh. 

echo()Sets echo mode. 

echowchar(wch)
Adds a wchar_t character to stdscr and refreshes the screen. 

endwin()Ends window modes. 

erase()Erases stdscr. 

erasechar()Returns user’s erase character. 

fixterm()Restores tty to in “curses” state. 

flash()Flashes screen or beeps. 

flushinp()Throws away any typeahead characters. 

getch()Gets a character from tty. 

getnwstr(wstr, n)
Gets n wchar_t characters in string wstr through stdscr. 

getstr(str)Gets a string through stdscr. 

gettmode()Establishes current tty modes. 

getwch()Gets a wchar_t character from tty. 

getwstr(wstr)
Gets a wchar_t character string through stdscr. 

getyx(win, y, x)
Gets coordinates (y, x). 

has_ic()True if terminal can do insert character. 

has_il()True if terminal can do insert line. 

idlok(win, bf)
Uses the terminal’s insert/delete line if bf != 0. 

inch()Gets the character at current (y, x) coordinates. 

initscr()Initializes screens. 

innwstr(wstr, n)
Gets at most n wchar_t characters in the string wstr from stdscr. 

insch(c)Inserts a character. 

insertln()Inserts a line. 

insnwstr(wstr, n)
Inserts the first n wchar_t characters in string wstr into stdscr. 

inswch(wch)Inserts a wchar_t character. 

inswstr(wstr)
Inserts a wchar_t character string.

inwch()Gets a wchar_t character and its attribute from stdscr. 

inwchnstr(wchstr, n)
Gets at most n wchar_t characters (with attributes) in string wchstr from stdscr. 

inwchstr(wchstr)
Gets a string of wchar_t characters (with attributes) from stdscr. 

inwstr(wstr)Gets a wchar_t character string from stdscr. 

intrflush(win, bf)
Interrupts flush output if bf is TRUE. 

keypad(win, bf)
Enables keypad input.

killchar()Returns the current user’s kill character. 

leaveok(win, flag)
Leaves cursor anywhere after refresh if flag!=0 for win; otherwise, leaves cursor at current position. 

longname()Returns verbose name of terminal. 

meta(win, flag)
Allows meta characters on input if flag!=0. 

move(y, x)Moves to (y, x) coordinates on stdscr. 

NOTE: The following routines, prefixed with mv, require y and x coordinates to move to before performing the same functions as the standard routines discussed in the preceding list. For example, mvaddch performs the same function as addch, but y and x coordinates must be supplied first.  The routines prefixed with mvw also require a window or pad argument. 

mvaddch(y, x, ch)

mvaddnwstr(y, x, wstr, n)

mvaddstr(y, x, str)

mvaddwch(y, x, wch)

mvaddwchnstr(y, x, wchstr, n)

mvaddwchstr(y, x, wchstr)

mvaddwstr(y, x, wstr)

mvcur(oldrow, oldcol, newrow, newcol)
Controls cursor motion directly (low-level cursor control).

mvdelch(y, x)

mvgetch(y, x)

mvgetnstr(y, x, n)

mvgetnwstr(y, x, wstr, n)

mvgetstr(y, x)

mvgetwch(y, x)

mvgetwstr(y, x, wstr)

mvinch(y, x)

mvinnwstr(y, x, wstr, n)

mvinsch(y, x, c)

mvinsnwstr(y, x, wstr, n)

mvinswch(y, x, wch)

mvinswstr(y, x, wstr)

mvinwch(y, x)

mvinwchnstr(y, x, wchstr, n)

mvinwchstr(y, x, wchstr)

mvinwstr(y, x, wstr)

mvprintw(y, x, fmt, args)

mvscanw(y, x, fmt, args)

mvwaddch(win, y, x, ch)

mvwaddnwstr(win, y, x, wstr, n)

mvwaddstr(win, y, x, str)

mvwaddwch(win, y, x, wch)

mvwaddwchnstr(win, y, x, wchstr, n)

mvwaddwchstr(win, y, x, wchstr)

mvwaddwstr(win, y, x, wstr)

mvwdelch(win, y, x)

mvwgetch(win, y, x)

mvwgetnstr(win, y, x, n)

mvwgetnwstr(win, y, x, wstr, n)

mvwgetstr(win, y, x)

mvwgetwch(win, y, x)

mvwgetwstr(win, y, x, wstr)

mvwin(win, by, bx)

mvwinch(win, y, x)

mvwinnwstr(win, y, x, wstr, n)

mvwinsch(win, y, x, c)

mvwinsnwstr(win, y, x, wstr, n)

mvwinswch(win, y, x, wch)

mvwinswstr(win, y, x, wstr)

mvwinwch(win, y, x)

mvwinwchnstr(win, y, x, wchstr, n)

mvwinwchstr(win, y, x, wchstr)

mvwinwstr(win, y, x, wstr)

mvwprintw(win, y, x, fmt, args)

mvwscanw(win, y, x, fmt, args)

newpad(nlines, ncols)
Creates a new pad with given dimensions.

newterm(type, fd)
Sets up a new terminal of given type to output on fd. 

newwin(lines, cols, begin_y, begin_x)
Creates a new window.

nl()Sets newline mapping. 

nocbreak()Unsets cbreak mode. 

nodelay(win, bf)
Enables nodelay input mode through getch. 

noecho()Unsets echo mode. 

nonl()Unsets newline mapping. 

noraw()Unsets raw mode. 

overlay(win1, win2)
Overlays win1 on win2. 

overwrite(win1, win2)
Overwrites 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)

Refreshes from pad starting with given upper left corner of pad with output to given portion of screen. 

printw(fmt, arg1, arg2, ...)
Executes printf on stdscr. 

raw()Sets raw mode. 

refresh()Makes current screen look like stdscr. 

resetterm()Sets tty modes to “out of curses” state. 

resetty()Resets tty flags to stored value. 

saveterm()Saves current modes as “in curses” state. 

savetty()Stores current tty flags. 

scanw(fmt, arg1, arg2, ...)
Executes scanf using stdscr. 

scroll(win)Scrolls win one line. 

scrollok(win, flag)
Allows terminal to scroll if flag != 0. 

set_term(new)
Switches between different terminals.

setscrreg(t, b)
Sets user scrolling region to lines t through b. 

setupterm(term, filenum, errret)
Sets up terminal at low level.

standend()Clears standout mode attribute. 

standout()Sets standout mode attribute. 

subwin(win, lines, cols, begin_y, begin_x)
Creates a subwindow.

touchwin(win)
“Changes” all of win. 

traceoff()Turns off debugging trace output. 

traceon()Turns on debugging trace output. 

typeahead(fd)
Uses file descriptor fd to check typeahead. 

unctrl(ch)Produces printable version of control character ch. 

ungetwch(wch)
Places a wchar_t character back on the input queue.

vwscanw(win, fmt, varglist)
Reads input from win by calling wscanw. 

vwprintw(win, fmt, varglist)
Executes vprintf on win. 

waddch(win, ch)
Adds a character to win. 

waddnwstr(win, wstr, n)
Adds at most n wchar_t characters to string wstr to win. 

waddwchnstr(win, wchstr, n)
Adds the first n wchar_t characters (and attributes) in string wchstr to win. 

waddwchstr(win, wchstr)
Adds a string of wchar_t characters (and attributes) to win. 

waddstr(win, str)
Adds a string to win. 

waddwch(win, wch)
Adds a wchar_t character to win. 

waddwstr(win, wstr)
Adds a wchar_t character string to win. 

wattroff(win, attrs)
Turns off attributes attrs in win. 

wattron(win, attrs)
Turns on attributes attrs in win. 

wattrset(win, attrs)
Sets attributes in win to attrs. 

wclear(win)Clears win. 

wclrtobot(win)
Clears to bottom of win. 

wclrtoeol(win)
Clears to end of line on win. 

wdelch(win, c)
Deletes character c from win. 

wdeleteln(win)
Deletes line from win. 

wechowchar(win, wch)
Adds a wchar_t character to win and refreshes win. 

werase(win)Erases win. 

wgetch(win)Gets a character through win. 

wgetnstr(win, str, n)
Gets up to n characters in string str through win. 

wgetnwstr(win, wstr, n)
Gets n wchar_t characters in string wstr through win. 

wgetstr(win, str)
Gets a string through win. 

wgetwch(win)
Gets a wchar_t character through win. 

wgetwstr(win, wstr)
Gets a wchar_t character string through win. 

winch(win)Gets character at current (y,x) coordinates in win. 

winnwstr(win, wstr, n)
Gets at most n wchar_t characters in string wstr from win. 

winsch(win, c)
Inserts character c into win. 

winsertln(win)
Inserts line into win. 

winsnwstr(win, wstr, n)
Inserts the first n wchar_t characters in string wstr into win. 

winswch(win, wch)
Inserts a wchar_t character into win. 

winswstr(win, wstr)
Inserts a wchar_t character string into win. 

winwch(win)
Gets a wchar_t character and its attribute from win. 

winwchnstr(win, wchstr, n)
Gets at most n wchar_t characters (with attributes) in string wchstr from win. 

winwchstr(win, wchstr)
Gets a string of wchar_t characters (with attributes) from win. 

winwstr(win, wstr)
Gets a wchar_t character string from win. 

wmove(win, y, x)
Sets current (y, x) coordinates on win. 

wnoutrefresh(win)
Refreshes screen but does not execute screen output.

wprintw(win, fmt, arg1, arg2, ...)
Executes printf on win. 

wrefresh(win)
Makes screen look like win. 

wscanw(win, fmt, arg1, arg2, ...)
Executes scanf on win. 

wsetscrreg(win, t, b)
Sets scrolling region of win. 

wstandend(win)
Clears standout attribute in win. 

wstandout(win)
Sets standout attribute in win. 

The terminfo Level Routines

This section lists and describes the terminfo subset of routines in the curses library.  Use the terminfo routines when your program needs to deal directly with the terminfo database. Note, however, that this interface is low level and its use is not recommended. 

If the environment variable TERMINFO is defined, any program using curses checks for a local terminal definition before checking in the standard libraries.  For example, if the standard location is /usr/lib/terminfo, and TERM is set to vt100, the compiled file is usually found in /usr/lib/terminfo/v/vt100.  The v is copied from the first letter of vt100 to avoid creating huge directories.  However, if TERMINFO is set to /usr/mark/myterms, curses first checks /usr/mark/myterms/v/vt100; if that fails, curses then checks /usr/lib/terminfo/v/vt100.  Setting the TERMINFO variable is useful for developing experimental definitions when you do not have write permission for the /usr/lib/terminfo directory. 

At the beginning of your program, include the files <curses.h> and <term.h> to get the definitions for strings, numbers, and flags used by the terminfo routines.  Call the routine setupterm first.  This routine defines the set of terminal-dependent variables specified in the terminfo(4) reference page.  Instantiate parameterized strings by passing them through tparm().  Use tputs() or putp() to print all terminfo strings (including the output of tparm()).  Before your program exits, it should call resetterm() to restore the tty modes. 

If you want to use shell escapes or Ctrl/Z suspending in your program, you can call resetterm() before calling the shell and fixterm() after returning from the shell. 

fixterm()Restores tty modes for terminfo use (called by setupterm). 

resetterm()Resets tty modes to the state they were in before program entry. 

setupterm(term, fd, rc)
Reads in the database.  Terminal type is the character string term; all output is to the system file descriptor fd.  A status value is returned in the integer pointed to by rc.  A status value of 1 is normal.  The simplest call is setupterm(0, 1, 0), which uses all defaults. 

tparm(str, p1, p2, ..., p9)
Instantiates string str with parms p sub i. 

tputs(str, affcnt, putc)
Applies padding info to string str. The affcnt variable is the number of lines affected, or 1 if padding is not applicable.  The putc argument is a function (like putchar) to which the characters are passed, one at a time. 

putp(str)A function that calls tputs(str, 1, putchar). 

vidputs(attrs, putc)
Outputs the string to put terminal in video attribute mode attrs.  Characters are passed to the function putc, which is similar to putchar. 

vidattr(attrs)
Performs operation similar to the vidputs function, but produces output using the putchar function. 

RETURN VALUES

Most curses routines return OK on successful completion and ERR when an error occurs. 

ERRORS

No errors are defined for the curses functions. 

RELATED INFORMATION

Commands: tic(1). 

Functions: ioctl(2), curses(3), getenv(3), printf(3), putchar(3), scanf(3), vprintf(3). 

Files: terminfo(4).