The curses library provides a set of functions that enable you to manipulate a terminal's display regardless of the terminal type. The curses library supports color. However, multibyte characters are not supported. All references to characters in the curses documentation refer to single-byte characters. Throughout this documentation, the curses library is referred to as curses.
The basis of curses programming is the window data structure. Using this structure, you can manipulate data on a terminal's display. You can instruct curses to treat the entire terminal display as one large window, or you can create multiple windows on the display. The windows can be different sizes and can overlap one another. A typical curses application has a single large window and one subwindow within it.
Each window on a terminal's display has its own window data structure. This structure keeps state information about the window, such as its size and where it is located on the display. Curses uses the window data structure to obtain the relevant information it needs to carry out your instructions.
When programming with curses, you should be familiar with the following terms:
A single curses subroutine can have more than one version. Curses subroutines with multiple versions follow distinct naming conventions that identify the separate versions. These conventions add a prefix to a standard curses subroutine and identify what arguments the subroutine requires or what actions take place when the subroutine is called. The different versions of curses subroutine names use the following prefixes:
| Prefix | Description |
|---|---|
| w | Identifies a subroutine that requires a window argument. |
| p | Identifies a subroutine that requires a pad argument. |
| mv | Identifies a subroutine that first performs a move to the program-supplied coordinates. |
If a curses subroutine has multiple versions and does not include one of the preceding prefixes, the curses default window stdscr (standard screen) is used. The majority of subroutines that use the stdscr are macros created in the /usr/include/curses.h file using #define statements. The preprocessor replaces these statements at compilation time. As a result, these macros do not appear in the compiled assembler code, a trace, a debug program, or the curses source code.
If a curses subroutine has only a single version, it does not necessarily use stdscr. For example, the printw subroutine prints a string to the stdscr. The wprintw subroutine prints a string to a specific window by supplying the window argument. The mvprintw subroutine moves the specified coordinates to the stdscr and then performs the same function as the printw subroutine. Likewise, the mvwprintw subroutine moves the specified coordinates to the specified window and then performs the same function as the wprintw subroutine.
In general, a curses program has the following progression:
Some steps are optional, so your program does not have to follow this progression exactly.
With a few exceptions, all curses subroutines return either the integer value ERR or the integer value OK. Subroutines that do not follow this convention are noted appropriately. Subroutines that return pointers always return a null pointer or an error.