[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

General Programming Concepts: Writing and Debugging Programs

Understanding Terminals with curses

The capabilities of your program are limited, in part, by the capabilities of the terminal on which it runs. This section provides information about initializing terminals and identifying their capabilities.

For further information on terminals, see the following articles:

Manipulating Multiple Terminals

With curses, you can use one or more terminals for input and output. The terminal subroutines enable you to establish new terminals, to switch input and output processing, and to retrieve terminal capabilities.

You can start curses on a single default screen using the initscr subroutine. This should be sufficient for most applications. However, if your application sends output to more than one terminal, you should use the newterm subroutine. Call this subroutine for each terminal. You should also use the newterm subroutine if your application wants an indication of error conditions so that it can continue to run in a line-oriented mode if the terminal cannot support a screen-oriented program.

When it completes, a program must call the endwin subroutine for each terminal it used. If you call the newterm subroutine more than once for the same terminal, the first terminal referred to must be the last one for which you call the endwin subroutine.

The set_term subroutine switches input and output processing between different terminals.

Determining Terminal Capabilities

curses supplies the following subroutines to help you determine the capabilities of a terminal:

longname Returns the verbose name of the terminal.
has_ic Determines whether a terminal has the insert-character capability.
has_il Determines whether a terminal has the insert-line capability.

The longname subroutine returns a pointer to a static area containing a verbose description of the current terminal. This area is defined only after a call to the initscr or newterm subroutine. If you intend to use the longname subroutine with multiple terminals, you should know that each call to the newterm subroutine overwrites this area. Calls to the set_term subroutine do not restore the value. Instead, save this area between calls to the newterm subroutine.

The has_ic subroutine returns TRUE if the terminal has insert and delete character capabilities.

The has_il subroutine returns TRUE if the terminal has insert and delete line capabilities or can simulate the capabilities using scrolling regions. Use the has_il subroutine to check whether it is appropriate to turn on physical scrolling using the scrollok or idlok subroutines.

Setting Terminal Input and Output Modes

The subroutines that control input and output determine how your application retrieves and displays data to users.

Input Modes

Special input characters include the flow-control characters, the interrupt character, the erase character, and the kill character. Four mutually-exclusive curses modes let the application control the effect of the input characters.

Cooked Mode
This achieves normal line-at-a-time processing with all special characters handled outside the application. This achieves the same effect as canonical-mode input processing. The state of the ISIG and IXON flags are not changed upon entering this mode by calling nocbreak( ), and are set upon entering this mode by calling noraw( ).

The implementation supports erase and kill characters from any supported locale, no matter what the width of the character is.

cbreak Mode
Characters typed by the user are immediately available to the application and curses does not perform special processing on either the erase character or the kill character. An application can select cbreak mode to do its own line editing but to let the abort character be used to abort the task. This mode achieves the same effect as non-canonical-mode, Case B input processing (with MIN set to 1 and ICRNL cleared). The state of the ISIG and IXON flags are not changed upon entering this mode.

Half-Delay Mode
The effect is the same as cbreak, except that input functions wait until a character is available or an interval defined by the application elapses, whichever comes first. This mode achieves the same effect as non-canonical-mode, Case C input processing (with TIME set to the value specified by the application). The state of the ISIG and IXON flags are not changed upon entering this mode.

Raw Mode
Raw mode gives the application maximum control over terminal input. The application sees each character as it is typed. This achieves the same effect as non-canonical mode, Case D input processing. The ISIG and IXON flags are cleared upon entering this mode.

The terminal interface settings are recorded when the process calls initscr or newterm to initialize curses and restores these settings when endwin is called. The initial input mode for curses operations is unspecified unless the implementation supports Enhanced curses compliance, in which the initial input mode is cbreak mode.

The behavior of the BREAK key depends on other bits in the display driver that are not set by curses.

Delay Mode

Two mutually-exclusive delay modes specify how quickly certain curses functions return to the application when there is no terminal input waiting when the function is called:

No Delay The function fails.
Delay The application waits until the implementation passes text through to the application. If cbreak or Raw Mode is set, this is after one character. Otherwise, this is after the first <newline> character, end-of-line character, or end-of-file character.

The effect of No Delay Mode on function key processing is unspecified.

Echo Processing

echo mode determines whether curses echoes typed characters to the screen. The effect of echo mode is analogous to the effect of the echo flag in the local mode field of the termios structure associated with the terminal device connected to the window. However, curses always clears the echo flag when invoked, to inhibit the operating system from performing echoing. The method of echoing characters is not identical to the operating system's method of echoing characters, because curses performs additional processing of terminal input.

If in echo mode, curses performs its own echoing. Any visible input character is stored in the current or specified window by the input function that the application called, at that window's cursor position, as though addch( ) were called, with all consequent effects such as cursor movement and wrapping.

If not in echo mode, any echoing of input must be performed by the application. Applications often perform their own echoing in a controlled area of the screen, or do not echo at all, so they disable echo mode.

It may not be possible to turn off echo processing for synchronous and network asynchronous terminals because echo processing is done directly by the terminals. Applications running on such terminals should be aware that any characters typed will appear on the screen at wherever the cursor is positioned.

cbreak or nocbreak Puts the terminal into or takes it out of CBREAK mode.
delay_output Sets the output delay in milliseconds.
echo or noecho Controls echoing of typed characters to the screen.
halfdelay Returns ERR if no input was typed after blocking for a specified amount of time.
nl or nonl Determines whether curses translates a new line into a carriage return and line feed on output, and translates a return into a new line on input.
raw or noraw Places the terminal into or out of RAW mode.

The echo subroutine puts the terminal into echo mode. In echo mode, curses writes characters typed by the user to the terminal at the physical cursor position. The noecho subroutine takes the terminal out of echo mode.

The raw subroutine puts the terminal into raw mode. In raw mode, characters typed by the user are immediately available to the program. Additionally, the interrupt, quit, suspend, and flow-control characters are passed uninterpreted instead of generating a signal as they do in cbreak mode. The noraw subroutine takes the terminal out of raw mode.

The cbreak subroutine performs a subset of the functions performed by the raw subroutine. In cbreak mode, characters typed by the user are immediately available to the program and erase or kill character processing is not done. Unlike RQW mode, interrupt and flow characters are acted upon. Otherwise, the tty driver buffers the characters typed until a new line or carriage return is typed.

Note: cbreak mode disables translation by the tty driver.

The nocbreak subroutine takes the terminal out of cbreak mode.

The delay_output subroutine sets the output delay to the specified number of milliseconds. Do not use this subroutine extensively because it uses padding characters instead of a processor pause.

The nl and nonl subroutines, respectively, control whether curses translates new lines into carriage returns and line feeds on output, and whether curses translates carriage returns into new lines on input. Initially, these translations do occur. By disabling these translations, the curses subroutine library has more control over the line-feed capability, resulting in faster cursor motion.

Using the terminfo and termcap Files

When curses is initialized, it checks the TERM environment variable to identify the terminal type. Then, curses looks for a definition explaining the capabilities of the terminal. Usually this information is kept in a local directory specified by the TERMINFO environment variable or in the /usr/share/lib/terminfo directory. All curses programs first check to see if the TERMINFO environment variable is defined. If this variable is not defined, the /usr/share/lib/terminfo directory is checked.

For example, if the TERM variable is set to vt100 and the TERMINFO variable is set to the /usr/mark/myterms file, curses checks for the /usr/mark/myterms/v/vt100 file. If this file does not exist, curses checks the /usr/share/lib/terminfo/v/vt100 file.

Additionally, the LINES and COLUMNS environment variables can be set to override the terminal description.

Writing Programs That Use the terminfo Subroutines

Use the terminfo subroutines when your program needs to deal directly with the terminfo database. For example, use these subroutines to program function keys. In all other cases, curses subroutines are more suitable and their use is recommended.

Initializing Terminals

Your program should begin by calling the setupterm subroutine. Normally, this subroutine is called indirectly by a call to the initscr or newterm subroutine. The setupterm subroutine reads the terminal-dependent variables defined in the terminfo database. The terminfo database includes boolean, numeric, and string variables. All of these terminfo variables use the values defined for the specified terminal. After reading the database, the setupterm subroutine initializes the cur_term variable with the terminal definition. When working with multiple terminals, you can use the set_curterm subroutine to set the cur_term variable to a specific terminal.

Another subroutine, restartterm, is similar to the setupterm subroutine. However, it is called after memory is restored to a previous state. For example, you would call the restartterm subroutine after a call to the scr_restore subroutine. The restartterm subroutine assumes that the input and output options are the same as when memory was saved, but that the terminal type and baud rate may differ.

The del_curterm subroutine frees the space containing the capability information for a specified terminal.

Header Files

Include the curses.h and term.h files in your program in the following order:

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

These files contain the definitions for the strings, numbers, and flags in the terminfo database.

Handling Terminal Capabilities

Pass all parametized strings through the tparm subroutine to instantiate them. You should print all terminfo strings and the output of the tparm subroutine with the tputs or putp subroutine.

putp Provides a shortcut to the tputs subroutine.
tparm Instantiates a string with parameters.
tputs Applies padding information to the given string and outputs it.

Use the following subroutines to obtain and pass terminal capabilities:

tigetflag Returns the value of a specified boolean capability. If the capability is not boolean, a -1 is returned.
tigetnum Returns the value of a specified numeric capability. If the capability is not numeric, a -2 is returned.
tigetstr Returns the value of a specified string capability. If the capability specified is not a string, the tigetstr subroutine returns the value of (char *) -1.

Exiting the Program

When your program exits you should restore the tty modes to their original state. To do this, call the reset_shell_mode subroutine. If your program uses cursor addressing, it should output the enter_ca_mode string at startup and the exit_ca_mode string when it exits.

Programs that use shell escapes should call the reset_shell_mode subroutine and output the exit_ca_mode string before calling the shell. After returning from the shell, the program should output the enter_ca_mode string and call the reset_prog_mode subroutine. This process differs from standard curses operations which call the endwin subroutine on exit.

Low-Level Screen Subroutines

Use the following subroutines for low-level screen manipulations:

scr_restore Restores the virtual screen to the contents of a previously dumped file.
scr_dump Dumps the contents of the virtual screen to the specified file.
scr_init Initializes the curses data structures from a specified file.
ripoffline Strips a single line from the stdscr.

termcap Subroutines

If your program uses the termcap file for terminal information, the termcap subroutines are included as a conversion aid. The parameters are the same for the termcap subroutines. curses emulates the subroutines using the terminfo database. The following termcap subroutines are supplied:

tgetent Emulates the setupterm subroutine.
tgetflag Returns the boolean entry for a termcap identifier.
tgetnum Returns the numeric entry for a termcap identifier.
tgetstr Returns the string entry for a termcap identifier.
tgoto Duplicates the tparm subroutine. The output from the tgoto subroutine should be passed to the tputs subroutine.

Converting termcap Descriptions to terminfo Descriptions

The captoinfo command converts termcap descriptions to terminfo descriptions. The following example illustrates how the captoinfo command works:

captoinfo /usr/lib/libtermcap/termcap.src

This command converts the /usr/lib/libtermcap/termcap.src file to terminfo source. The captoinfo command writes the output to standard output and preserves comments and other information in the file.

Manipulating TTYs

The following functions save and restore the state of terminal modes:

savetty Saves the state of the tty modes.
resetty Restores the state of the tty modes to what they were the last time the savetty subroutine was called.

Related Information

Chapter 2, The Curses Library

Manipulating Video Attributes

Synchronous and Networked Asynchronous Terminals

Synchronous, networked synchronous (NWA) or non-standard directly-connected asynchronous terminals are often used in a mainframe environment and communicate to the host in block mode. That is, the user types characters at the terminal then presses a special key to initiate transmission of the characters to the host.

Although it may be possible to send arbitrary sized blocks to the host, it is not possible or desirable to cause a character to be transmitted with only a single keystroke. Doing so could cause severe problems to an application wishing to make use of single-character input.


The curses interface can be used in the normal way for all operations pertaining to output to the terminal, with the possible exception that on some terminals the refresh( ) routine may have to redraw the entire screen contents in order to perform any update.

If it is additionally necessary to clear the screen before each such operation, the result could be undesirable.


Because of the nature of operation of synchronous (block-mode) and NWA terminals, it might not be possible to support all or any of the curses input functions. In particular, the following points should be noted:

[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]