NAME

curses − A library that controls cursor movement and windowing

LIBRARY

The curses library (libcurses.so, libcurses.a)

SYNOPSIS

#include <curses.h>
#include <term.h>

DESCRIPTION

The curses library is a screen manipulation package. 

The full curses interface allows you to manipulate structures 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 by using the newwin() function.  Windows are referred to by variables declared as type WINDOW ∗, defined in the curses.h header file.  (Use the term.h header file only when using the terminfo level functions.) 

Routine names beginning with "w" allow you to specify a window.  Routine names not beginning with "w" affect only the window stdscr. 

The minicurses package is a subset of curses that allows you to manipulate only one window.  You invoke this subset by specifying the -DMINICURSES flag to the cc compiler.  The minicurses subset is smaller and faster than the full curses interface. 

If your program needs only one terminal, you can specify the -DSINGLE flag to the C compiler.  This flag produces static references instead of dynamic references to capabilities. The result is more concise code, but you can use only one terminal for the program. 

To initialize the functions that are described in the curses library, you must call the initscr() function before using any other functions that affect windows and screens and the endwin() function before exiting. 

Support for Wide-Character Encoding

As is the case for the process code in the Standard C Library, the curses library has been extended to support Asian language multibyte characters encoded in wchar_t format.  The curses library also includes routines based on the specification of “Unix System V Release 4 Multi-National Language Supplement (SVR4 MNLS)” to process wchar_t data for editing and screen formatting. 

The operation of overwriting a multicolumn character with a character of a different column width may produce orphaned columns. Orphaned columns are automatically filled with the background character SPACE (code 0x20) when you use the curses interfaces that process wchar_t data.  However, if you use a curses interface that handles only single-byte character encoding to overwrite a multicolumn character, the results are undefined. 

When you insert and delete characters, you operate on a character level.  When you insert a character just before the target character, even if the cursor is not at the proper character boundary, the cursor is automatically adjusted to the first column of the target character before the insertion.  Insertion of the character may cause characters to overflow the line on the screen. In this case, the characters at the end of the line automatically wrap to the first column of the next line and may create orphaned columns at the right margin of the screen.  The orphaned columns are automatically filled with the background character. 

Similar rules of operation apply to character deletion.  You delete a character with a single call (using the delch routine, for example). The entire character is deleted by the call, regardless of where the cursor is positioned in a multicolumn character. The cursor is automatically adjusted to the first column of the character before the deletion. Any orphaned columns created after the deletion are filled with the background character. 

When two overlapping or overwriting windows appear on the screen, orphaned columns may be produced at the edge of the underlying window.  The orphaned columns are handled in the same way as those created by character insertion and deletion. 

Cursor movement operates at the column level rather than the character level. For example, you can place the cursor at the second or later column position of a multicolumn character. 

Screen Dimensions

The screen is a matrix of character positions that can contain 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 setupterm(). The functions enforce the following limits on the terminal:

       •If the terminal specification defines fewer than 5 lines, the functions use a value of 24 lines. 

       •If the terminal specification defines fewer than 5 columns, the functions use a value of 80 columns. 

Note that line values (y coordinates) are specified first to the library functions that 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 position 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, your 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:

refreshTransfers the contents of stdscr to the terminal

wrefreshTransfers 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, your program can change the contents of the screen in any order. When the program has made all of the changes, the library functions update the terminal in an efficient manner. 

The curses Routines

The curses routines are summarized as follows:

int addch( chtype ch );
Adds a character to stdscr, wrapping to the next line at the end of a line (like putchar()).  May be called with minicurses. 

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

int addstr( char ∗str );
Calls addch() with each character in string str.  May be used with minicurses. 

int addwch( chtype wch );
Adds a wchar_t character to stdscr, wrapping to the next line at the end of a line (similar to the operation performed by putwchar()).  May be called with minicurses. 

int addwchnstr( chtype ∗wchstr, int n );
Adds the first n wchar_t characters (and attributes) in string wchstr to stdscr. 

int addwchstr( chtype ∗wchstr );
Adds a string of wchar_t characters (and attributes) to stdscr. 

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

int attroff( chtype attrs );
Turns off attributes named in list attrs.  May be used with minicurses. 

int attron( chtype attrs );
Turns on attributes named in list attrs.  May be used with minicurses. 

int attrset( chtype attrs );
Sets current attributes to those specified in list attrs.  May be used with minicurses. 

int baudrate ( void );
Queries current terminal speed. May be used with minicurses. 

int beep ( void );
Sounds beep on terminal. May be used with minicurses. 

int box( WINDOW ∗win, chtype vert, chtype hor );
Draws 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 );
Sets cbreak() mode.  May be used with minicurses. 

int clear ( void );
Clears stdscr. 

int clearok( WINDOW ∗win, bool bool_flag );
Clears screen before next redraw of window win if bool_flag is true. 

int clrtobot ( void );
Clears to bottom of stdscr. 

int clrtoeol ( void );
Clears to end of line on stdscr. 

int delay_output( int ms );
Inserts pause of ms milliseconds in output.  May be used with minicurses. 

int delch ( void );
Deletes a character.

int deleteln ( void );
Deletes a line.

int delwin( WINDOW ∗win );
Deletes window win. 

int doupdate ( void );
Updates screen from all wnoutrefresh(). 

int echo ( void );
Sets echo mode.

int echowchar( chtype wch );
Adds wchar_t character wch to stdscr and refreshes the screen. 

int endwin ( void );
Ends window mode. May be used with minicurses. 

int erase ( void );
Erases stdscr. 

char erasechar ( void );
Returns user’s erase character.

int fixterm ( void );
Restores terminal to "in curses" state.

int flash ( void );
Flashes screen or beeps.

int flushinp ( void );
Throws away any data in type-ahead buffer. May be used with minicurses. 

int flushok ( WINDOW ∗win, bool bool_flag );
Sets the flush-on-refresh flag for window win to be bool_flag. 

int getch ( void );
Gets a character from stdscr. May be used with minicurses.  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_UPUp arrow key

KEY_LEFTLeft arrow key

KEY_RIGHT
Right arrow key

KEY_HOME
Home key

KEY_BACKSPACE
Backspace key (unreliable)

KEY_F(n)Function key Fn, where n is an integer from 0 to 63

KEY_DLDelete line

KEY_ILInsert line

KEY_DCDelete character

KEY_ICInsert character or enter insert mode

KEY_EICExit insert character mode

KEY_CLEAR
Clear screen

KEY_EOSClear to end of screen

KEY_EOLClear to end of line

KEY_SFScroll one line forward

KEY_SRScroll one line backwards (reverse)

KEY_NPAGE
Next page

KEY_PPAGE
Previous page

KEY_STABSet tab

KEY_CTABClear 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_LLHome down or bottom (lower left)

KEY_A1Upper left key of keypad

KEY_A3Upper right key of keypad

KEY_B2Center key of keypad

KEY_C1Lower left key of keypad

KEY_C3Lower right key of keypad

KEY_ACTION
Action key

KEY_HELPHelp key

KEY_COMMAND
Command key

KEY_SELECT
Select key

KEY_BTABBack tab key

char ∗getcap ( char ∗cap_name );
Gets terminal capability cap_name. 

int getstr( char ∗str );
Gets the string through stdscr. 

int getnstr( char ∗str , int n );
Gets at most n characters in the string str through stdscr. 

int getnwstr( wchar_t ∗wstr, int n );
Gets at most n wchar_t characters in the string wstr through stdscr. 

int gettmode ( void );
Gets current tty modes. 

int getwch ( void );
Gets a wchar_t character from stdscr. 

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

int getyx( WINDOW ∗win, int y, int x );
Gets (y,x) coordinates from window win. 

bool has_ic ( void );
Has value of TRUE if terminal can insert character.

bool has_il ( void );
Has value of TRUE if terminal can insert line.

int idlok( WINDOW ∗win, bool bool_flag );
Uses terminal’s insert/delete line on window win if bool_flag is true.  May be used with minicurses. 

chtype inch ( void );
Gets character at current (y,x) coordinates. 

WINDOW ∗initscr ( void );
Initializes screen. May be used with minicurses. 

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

int insch( chtype ch );
Inserts character ch. 

int insertln ( void );
Inserts a line.

int insnwstr( wchar_t ∗wstr, int n );
Inserts the first n wchar_t characters in string wstr. 

int inswch( chtype wch );
Inserts wchar_t character wch. 

int inswstr( wchar_t ∗wstr );
Inserts wchar_t character string wstr. 

int intrflush( WINDOW ∗win, bool bool_flag );
Interrupts flush output on window win if bool_flag is true. 

chtype inwch( void );
Gets a wchar_t character and its attribute.

chtype inwchnstr( chtype ∗wchstr, int n );
Gets a string of at most n wchar_t characters (and attributes) from stdscr. 

chtype inwchstr( chtype ∗wchstr );
Gets a string of wchar_t characters (and attributes) from stdscr. 

int inwstr( wchar_t ∗wstr );
Gets a string of wchar_t characters from stdscr. 

int keypad( WINDOW ∗win, bool bool_flag );
Enables keypad input on window win if bool_flag is true. 

char killchar ( void );
Returns current user’s kill() character. 

int leaveok( WINDOW ∗win, bool bool_flag );
Permits 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 );
Returns verbose name of terminal.

char ∗longname( char ∗termbuf, char ∗name );
Sets 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 );
Allows metacharacters on input from window win if bool_flag is true.  May be used with minicurses. 

int move( int y, int x );
Moves to position (y,x) on stdscr.  May be used with minicurses. 

int mvaddch( int y, int x, chtype ch );
Moves to position (y,x), then adds character ch. 

int mvaddnwstr( int y, int x, wchar_t ∗wstr, int n );
Moves to position (y, x), then adds at most n wchar_t characters in string wstr. 

int mvaddstr( int y, int x, char ∗str );
Moves to position (y, x), then adds string str. 

int mvaddwch( int y, int x, chtype wch );
Moves to position (y,x), then adds a wchar_t character wch. 

int mvaddwchnstr( int y, int x, chtype ∗wchstr,
int n );

Moves to position (y, x), then adds the first n wchar_t characters (and attributes) in the string wchstr to window. 

int mvaddwchstr( int y, int x, chtype ∗wchstr );
Moves to position (y, x), then adds the string wchstr to window. 

int mvaddwstr( int y, int x, wchar_t ∗wstr );
Moves to position (y, x), then adds wchar_t character string wstr. 

char mvcur( int y1, int x1, int y2, int x2 );
Moves cursor from current position (y1,x1) to new position (y2,x2). 

int mvdelch( int y, int x );
Moves to position (y,x), then deletes a character. 

int mvgetch( int y, int x );
Moves to position (y,x), then gets a character from the terminal. 

int mvgetnstr( int y, int x, char ∗str, int n ) ;
Moves to position (y,x), then gets at most n characters in the string str from the terminal. 

int mvgetnwstr( int y, int x, wchar_t ∗wstr, int n );
Moves to position (y,x), then gets at most n wchar_t characters in the string wstr from the terminal. 

int mvgetstr( int y, int x, char ∗str );
Moves to position (y,x), then gets string str from the terminal. 

int mvgetwch( int y, int x );
Moves to position (y,x), then gets a wchar_t character from the terminal. 

int mvgetwstr( int y, int x, wchar_t ∗wstr );
Moves to position (y,x), then gets the wchar_t character string wstr from the terminal. 

chtype mvinch( int y, int x );
Moves to position (y,x), then gets the character at current (y,x) coordinates. 

int mvinnwstr( int y, int x, wchar_t ∗wstr, int n );
Moves to position (y, x), then gets at most n wchar_t characters in string wstr from stdscr. 

int mvinsch( int y, int x, chtype ch );
Moves to position (y,x), then inserts character ch. 

int mvinswch( int y, int x, chtype wch );
Moves to position (y,x), then inserts wchar_t character wch. 

int mvinswstr( int y, int x, wchar_t ∗wstr );
Moves to position (y,x), then inserts wchar_t character string wstr. 

int mvinwch( int y, int x );
Moves to position (y,x), then gets a wchar_t character and its attributes. 

chtype mvinwchnstr( int y, int x, chtype ∗wchstr, int n );
Moves to position (y,x), then gets a string of at most n wchar_t characters (and attributes) from stdscr. 

chtype mvinwchstr( int y, int x, chtype ∗wchstr );
Moves to position (y,x), then gets a string of wchar_t characters (and attributes) from stdscr. 

int mvinwstr( int y, int x, wchar_t ∗wstr );
Moves to position (y,x), then gets a string of wchar_t characters from stdscr. 

int mvprintw( int y, int x, char ∗fmt [, args ] );
Moves to position (y,x), then prints on stdscr. 

int mvscanw( int y, int x, char ∗fmt [, args ] );
Moves to position (y,x), then scans through stdscr. 

int mvwaddch( WINDOW ∗win, int y, int x, chtype ch );
Moves to position (y,x), then adds character ch to window win. 

int mvwaddnwstr( WINDOW ∗win, int y, int x,
wchar_t ∗ ∗Vwstr, int n );

Moves to position (y, x), then adds at most n wchar_t characters in string wstr to window win. 

int mvwaddstr( WINDOW ∗win, int y, int x, char ∗str );
Moves to position (y, x), then adds string str to window win. 

int mvwaddwch( WINDOW ∗win, int y, int x, chtype wch );
Moves to position (y,x), then adds wchar_t character wch to window win. 

int mvwaddwchnstr( WINDOW ∗win, int y, int x,
chtype ∗ wchstr, int n );

Moves to position (y, x), then adds the first n wchar_t characters (and attributes) in string wchstr to window win. 

int mvwaddwchstr( WINDOW ∗win, int y, int x,
chtype ∗ ∗Vwchstr );

Moves to position (y, x), then adds the string wchstr to window win. 

int mvwaddwstr( WINDOW ∗win, int y, int x,
wchar_t ∗wstr );

Moves to position (y, x), then adds wchar_t character string wstr to window win. 

int mvwdelch( WINDOW ∗win, int y, int x );
Moves to position (y,x), then deletes a character from win. 

int mvwgetch( WINDOW ∗win, int y, int x );
Moves to position (y,x), then gets a character through win. 

int mvwgetnstr( WINDOW ∗win, int y, int x,
char ∗str, int n );

Moves to position (y, x), then gets at most n characters in the string str through win. 

int mvwgetnwstr( WINDOW ∗win, int y, int x,
wchar_t ∗ ∗Vwstr, int n );

Moves to position (y, x), then gets a string of at most n wchar_t characters through win. 

int mvwgetstr( WINDOW ∗win, int y, int x, char ∗str );
Moves to position (y,x), then gets a string through win. 

int mvwgetwch( WINDOW ∗win, int y, int x );
Moves to position (y,x), then gets a wchar_t character through win. 

int mvwgetwstr( WINDOW ∗win, int y, int x, wchar_t ∗wstr );
Moves to position (y,x), then gets a wchar_t character string through win. 

int mvwin( WINDOW ∗win, int y, int x );
Moves win so that the upper left corner is located at position (y,x). 

chtype mvwinch( WINDOW ∗win, int y, int x );
Moves to position (y,x) in win, then gets the character at the new position. 

int mvwinnwstr( WINDOW ∗win, int y, int x,
wchar_t ∗wstr, int n );

Moves to position (y, x), then gets at most n wchar_t characters in string wstr from win. 

int mvwinsch( WINDOW ∗win, int y, int x, chtype ch );
Moves to position (y,x), then inserts character ch into win. 

int mvwinsnwstr( WINDOW ∗win, int y, int x,
wchar_t ∗wstr, int n );

Moves to position (y, x), then inserts the first n wchar_t characters in string wstr into win. 

int mvwinswch( WINDOW ∗win, int y, int x, chtype wch );
Moves to position (y,x), then inserts wchar_t character wch into win. 

int mvwinswstr( WINDOW ∗win, int y, int x, wchar_t ∗wstr );
Moves to position (y,x), then inserts wchar_t character string wstr into win. 

int mvwinwch( WINDOW ∗win, int y, int x );
Moves to position (y,x), then gets a wchar_t character and its attributes from win. 

chtype mvwinwchnstr( WINDOW ∗win, int y, int x,
chtype ∗wchstr, int n );

Moves to position (y,x), then gets a string of at most n wchar_t characters (and attributes) from win. 

chtype mvwinwchstr( WINDOW ∗win, int y, int x,
chtype ∗wchstr );

Moves to position (y,x), then gets a string of wchar_t characters (and attributes) from win. 

int mvwinwstr( WINDOW ∗win, int y, int x, wchar_t ∗wstr );
Moves to position (y,x), then gets a string of wchar_t characters from win. 

int mvwprintw( WINDOW ∗win, int y, int x,
char ∗fmt [, args ] );

Moves to position (y,x), then performs printf() on stdscr. 

int mvwscanw( WINDOW ∗win, int y, int x,
char ∗fmt [, args ] );

Moves to position (y,x), then performs scanf() through stdscr. 

WINDOW ∗newpad( int nlines, int ncols );
Creates a new pad with given dimensions.

SCREEN ∗newterm( char ∗type, FILE outfd, FILE infd );
Sets up new terminal of given type to output on outfd and input from infd. 

WINDOW ∗newwin( int lines, int cols,
int begin_y, int begin_x );

Creates a new window. 

int nl ( void );
Sets newline mapping.  May be used with minicurses. 

int nocbreak ( void );
Unsets cbreak() mode. 

int nodelay( WINDOW ∗win, bool bool_flag );
Enables nodelay() input mode through getch() on window win if bool_flag is true. 

int noecho ( void );
Unsets echo mode.

int nonl ( void );
Unsets new line mapping. May be used with minicurses. 

int noraw ( void );
Unsets raw mode. May be used with minicurses. 

int overlay( WINDOW ∗win1, WINDOW ∗win2 );
Overlays win1 on win2. The overlaying window (win1) takes as its origin the window being overlayed (win2). 

int overwrite( WINDOW ∗win1, WINDOW ∗win2 );
Overwrites win1 on win2. 

int pnoutrefresh(WINDOW ∗pad, int pminrow, int pmincol ,
int sminrow, int smincol, int smaxrow, int smaxcol);

Refreshes like prefresh(), but with no output until doupdate() is called. 

int prefresh( WINDOW ∗pad, int pminrow, int pmincol,
int sminrow, int smincol, int smaxrow,
int smaxcol );

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

int printw( char ∗fmt [, arg1, arg2, ... ] );
Prints on stdscr. 

int raw ( void );
Sets raw mode. May be used with minicurses. 

int refresh ( void );
Makes current screen look like stdscr.  May be used with minicurses. 

int pnoutrefresh(WINDOW ∗pad, int pminrow, int pmincol,
int sminrow, int smincol, int smaxrow, int smaxcol);

Refreshes like prefresh(), but with no output until doupdate() is called. 

int resetterm ( void );
Sets tty modes to "out of curses" state.  May be used with minicurses. 

int resetty ( void );
Resets tty flags to stored value.  May be used with minicurses. 

int saveterm ( void );
Saves current modes as "in curses" state. May be used with minicurses. 

int savetty ( void );
Stores current tty flags.  May be used with minicurses. 

int scanw( char ∗fmt [, arg1, arg2, ... ] );
Performs scanf through stdscr. 

int scroll( WINDOW ∗win );
Scrolls win one line. 

int scrollok( WINDOW ∗win, bool bool_flag );
Allows terminal to scroll if bool_flag is true. 

SCREEN ∗set_term( SCREEN ∗new );
Enables talk to terminal new. 

int setscrreg( int top, int bottom );
Sets user scrolling region to lines top through bottom. 

void setterm( char ∗type );
Establishes terminal with a given type.

int standend ( void );
Clears standout mode attribute. May be used with minicurses. 

int standout ( void );
Sets standout mode attribute. May be used with minicurses. 

WINDOW ∗subwin( WINDOW ∗win, int lines,
int cols, int begin_y, int begin_x );

Creates a subwindow. 

int touchline( WINDOW ∗win, int y,
int firstcol, int numcol );

Marks numcol columns, starting at column firstcol, of line y as changed. 

int touchoverlap( WINDOW ∗win1, WINDOW ∗win2 );
Marks overlap of win1 on win2 as changed. 

int touchwin( WINDOW ∗win );
Changes all of win. 

int traceoff ( void );
Turns off debugging trace output.

int traceon ( void );
Turns on debugging trace output.

int typeahead( FILE fd );
Checks file descriptor fd to check type-ahead. 

char ∗unctrl( chtype ch );
Uses printable version of ch.  May be used with minicurses. 

int ungetwch( int wch );
Pushes a wchar_t character back to the input queue.

int vwprintw( WINDOW ∗win, char ∗fmt, va_list varglist );
Performs vprintf() on win. 

int vwscanw( WINDOW ∗win, char ∗fmt, va_list varglist );
Reads input from win by calling wscanw() using a variable argument list.

int waddch( WINDOW ∗win, chtype ch );
Adds character ch to window win. 

int waddnwstr( WINDOW ∗win, wchar_t ∗wstr, int n );
Adds at most n wchar_t characters in string wstr to window win. 

int waddstr( WINDOW ∗win, char ∗str );
Adds string str to window win. 

int waddwch( WINDOW ∗win, chtype wch );
Adds a wchar_t character wch to window win. 

int waddwchnstr( WINDOW ∗win, chtype ∗wchstr, int n ) ;
Adds the first n wchar_t characters (and attributes) in string wchstr to window win. 

int waddwchstr( WINDOW ∗win, chtype ∗wchstr );
Adds the string wchstr to window win. 

int waddwstr( WINDOW ∗win, wchar_t ∗wstr );
Adds wchar_t character string wstr to window win. 

int wattroff( WINDOW ∗win, int attrs );
Turns off attrs in win. 

int wattron( WINDOW ∗win, int attrs );
Turns on attrs in win. 

int wattrset( WINDOW ∗win, int attrs );
Sets attributes in win to attrs. 

int wclear( WINDOW ∗win );
Clears win. 

int wclrtobot( WINDOW ∗win );
Clears to bottom of win. 

int wclrtoeol( WINDOW ∗win );
Clears to end of line on win. 

int wdelch( WINDOW ∗win );
Deletes the current character from win. 

int wdeleteln( WINDOW ∗win );
Deletes line from win. 

int wechowchar( WINDOW ∗win, chtype wch );
Adds wchar_t character wch to window win and refreshes the screen. 

int werase( WINDOW ∗win );
Erases win. 

int wgetch( WINDOW ∗win );
Gets a character through win. 

int wgetnstr( WINDOW ∗win, char ∗str, int n );
Gets at most n characters in the string str through win. 

int wgetnwstr( WINDOW ∗win, wchar_t ∗wstr, int n );
Gets at most n wchar_t characters in the string wstr through win. 

int wgetstr( WINDOW ∗win, char ∗str );
Gets the string str through win. 

int wgetwch( WINDOW ∗win );
Gets a wchar_t character through win. 

int wgetwstr( WINDOW ∗win, wchar_t ∗wstr );
Gets wchar_t character string wstr through win. 

chtype winch( WINDOW ∗win );
Gets the character at current (y, x) in win. 

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

int winsch( WINDOW ∗win, chtype ch );
Inserts character ch into win. 

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

int winswch( WINDOW ∗win, chtype wch );
Inserts wchar_t character wch into win. 

int winswstr( WINDOW ∗win, wchar_t ∗wstr );
Inserts wchar_t character string wstr into win. 

chtype winwch( WINDOW ∗win );
Gets a wchar_t character and its attribute from win. 

chtype winwchnstr( WINDOW ∗win, chtype ∗wchstr, int n );
Gets a string of at most n wchar_t characters (and attributes) from win. 

chtype winwchstr( WINDOW ∗win, chtype ∗wchstr );
Gets a string of wchar_t characters (and attributes) from win. 

int winwstr( WINDOW ∗win, wchar_t ∗wstr );
Gets a string of wchar_t characters from win. 

int winsertln( WINDOW ∗win );
Inserts line into win. 

int wmove( WINDOW ∗win, int y, int x );
Sets current (y, x) coordinates on win. 

int wnoutrefresh( WINDOW ∗win );
Refreshes window but does not output to screen.

int wprintw( WINDOW ∗win, char ∗fmt [, arg1,
arg2, ... ] );

Performs printf() on win. 

int wrefresh( WINDOW ∗win );
Makes screen look like win. 

int wscanw( WINDOW ∗win, char ∗fmt [, arg1,
arg2,...  ] );

Performs scanf() through win. 

int wsetscrreg( WINDOW ∗win, int top, int bottom );
Sets scrolling region of win. 

int wstandend( WINDOW ∗win );
Clears standout attribute in win. 

int wstandout( WINDOW ∗win );
Sets standout attribute in win. 

The 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 definitions for these strings, numbers, and flags.  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. 

Print all terminfo strings (including the output of the tparm() parameter) using the tputs() or putp() function.  Before your program exits, make sure that it calls the reset_shell_mode() function to restore the tty modes. If you want to use shell escapes in your program, you can call the reset_shell_mode() function before the shell is called and the reset_prog_mode() function after returning from the shell. 

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 delay_output ( int ms );
Sets the output delay in milliseconds.

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:

1Successful completion. 

0No such terminal. 

-1An 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 setupterm() 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 setupterm() function uses the values in the terminfo database. The simplest call is setupterm(0,1,0), which uses all the defaults.  You can override the default number of lines and columns reported by a TIOCGWINSZ ioctl call by setting the LINES and COLUMNS environment variables to other values. 

After the call to the setupterm() function, the global variable cur_term is set to point to the current structure of terminal capabilities.  A program can use more than one terminal at a time by calling the setupterm() function for each terminal and saving and restoring cur_term. 

The setupterm() function also initializes the global 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 function is similar to putchar() to which the characters 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 attribute 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(). 

The 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() function. 

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 identifier. 

char ∗tgetstr( char ∗id, char ∗area );
Returns the string entry for id, which is a 2-character string that contains a termcap identifier. 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 if calling putchar(). 

RELATED INFORMATION

Files: terminfo(4).