How do I install the ncurses library

Ncurses: the basics

Installation [edit]

ncurses is (almost) always part of the distributions, at least under Linux and can, if not already done during the initial Linux installation, simply be installed from the installation medium afterwards. A ncurses-Download possibility is mentioned in the chapter web links.

The header files [edit]

The standard ncurses header files are


is mostly just a symbolic link

Also contains ncurses additional header files for special applications:

  • Panels:
  • Menus:
  • Forms:

The libraries [edit]

The standard ncurses functions are in the library

gathered, where stands for (shared object) or (static program library).

There are additional files equivalent to the header files ncurses-Libraries:

  • Panels:
  • Menus:
  • Forms:

The ncurses man pages [edit]

With ncurses Extensive and detailed manual pages are included.

The call of the ncurses-Overview page is done using

man ncurses


info ncurses

Also the descriptions of each ncurses- Functions can be queried in this way, e.g.

man mvaddstr


man 3 ncurses mvaddstr.

[Edit] window

A window represents a rectangular section of the screen. The necessary attributes and data of the corresponding screen section are stored in a data structure. This construct can be found in. is just a synonym for ().

Screens [edit]

Screens are pointers to a WINDOW data structure.

ncurses knows two screens at the start:

  • Standard screen:
  • Current screen:

This is the main window that the programmer uses ncurses-Instructions can be influenced. It represents what is currently displayed on the screen. During a refresh, the changes made are incorporated into this screen and the display on the physical screen is updated.

ncurses and I / O commands from C [edit]

If there is a program in the ncursesMode, the C standard functions may (or should) not be used for input and output (e.g. printf, scanf). To this end, provides ncurses own functions available.

Termcap and Terminfo [edit]

termcap stands for Terminal capabilities and is a file in which the capabilities (number of rows, columns, ...) of numerous terminals are stored.

terminfo basically does the same as termcap. However, lie in the terminfo-Database does not present the terminal capability descriptions in a single overall file, but as separate files in alphabetical order in subdirectories.

In the ncurses-Initialization is done by means of the environment variable the termcap/terminfo evaluated. From this can ncurses determine the relevant data of the terminal used (e.g. number of rows and columns).

Initialize and exit ncurses [edit]

The ncurses initialization is done using the function

WINDOW * initscr (void);

will be the first in most cases ncurses-Function that is called in a program.

The ncurses mode is ended with the function

int endwin (void);

A ncurses- The program should be ended properly with the function.

The ncurses-Mode can also be temporarily interrupted by. The return to ncursesMode is done with a refresh instruction.

The function can be used to query whether the ncursesMode is still active.

is by the way a Boolean data type den ncurses brings along. Valid values ​​are (= 1) and (= 0). The fact that C ++ compilers or other libraries also know a data type is stated in the ncurses-Header file taken into account.

The ncurses main coordinate system [edit]

The following macros are available for querying window and cursor coordinates:

getyx (win, y, x); // Coordinates of the current cursor position getparyx (win, y, x); // origin of coordinates of win in relation to the // parent window getbegyx (win, y, x); // origin of coordinates getmaxyx (win, y, x); // window size (number of rows and columns)

Where a pointer is to the one to be queried and the coordinate values ​​are supplied as integer values ​​in (row) and (column).

Example [edit]

#include #include // required for atexit () void quit () {endwin (); } int main (void) {int x, y; initscr (); atexit (quit); curs_set (0); mvprintw (3, 5, "LINES:% d", LINES); mvprintw (4, 5, "COLS:% d", COLS); getyx (stdscr, y, x); mvprintw (5, 5, "Current cursor position: [% d,% d]", y, x); getbegyx (stdscr, y, x); mvprintw (6, 5, "Origin of coordinates: [% d,% d]", y, x); getmaxyx (stdscr, y, x); mvprintw (7, 5, "Window size: [% d,% d]", y, x); mvaddstr (11, 2, "press key -> end"); refresh (); getch (); return (0); }

The meaning of the individual screen output functions is described in more detail later. The example can be compiled and linked with the following command

gcc -o ex ex.c -lncurses

Prerequisites for successfully compiling / linking this example in the suggested manner:

  • The example was saved under the file name and the compiler is called from the same directory in which it was saved.
  • You are using the C front end of the GNU Compiler Collection (GCC). This GCC must be installed on your system to compile / link the example. Using a different compiler will require a slightly different compiler call.
  • You enter the command in a terminal immediately after the prompt. For other types of program creation, e.g. via IDE, this is just a general note "Don't forget to include the library" given.

The executable program should be available under the file name after a successful compiler run. The program can be started with


directly from the memory directory of the sample program. The result should look like the following screenshot.

The specific numerical values ​​displayed naturally depend on the terminal used.

Cursor [edit]

The function is available for the purpose of positioning the cursor

int move (int y, int x);

to disposal. The cursor determines at which position the text output or an echo takes place. ncurses-Text I / O functions usually also exist as a variant with a -prefix, so that cursor positioning and data I / O can be done in one go and not two functions have to be written one after the other.

The cursor display can be changed with the function

int curs_set (int visibility);

modify. The following values ​​are possible for:

  • 0 ... invisible
  • 1 ... visible
  • 2 ... "particularly" visible.

Text output [edit]

The ncurses-Library knows a variety of text output functions, depending on its purpose.

Adding single characters [edit]

int addch (const chtype ch); int mvaddch (int y, int x, const chtype ch); int echochar (const chtype ch);

corresponds to one with the following.

Insert a character [edit]

int insch (chtype ch); int mvinsch (int y, int x, chtype ch);

Example: Difference between addch () and insch () [edit]

#include #include // required for atexit () void quit () {endwin (); } int main (void) {initscr (); atexit (quit); curs_set (0); mvaddstr (3, 2, "The difference between addch () and insch ():"); mvaddstr (5, 5, "ADDCH: Hello, World"); mvaddch (5, 13, 'A'); mvaddstr (6, 5, "INSCH: Hello, World"); mvinsch (6, 13, 'A'); refresh (); getch (); return (0); }

Adding a string [edit]

int addstr (const char * str); int addnstr (const char * str, int n); int mvaddstr (int y, int x, const char * str); int mvaddnstr (int y, int x, const char * str, int n);

Inserting a string [edit]

int insstr (const char * str); int insnstr (const char * str, int n); int mvinsstr (int y, int x, const char * str); int mvinsnstr (int y, int x, const char * str, int n);

Formatted output [edit]

int printw (const char * fmt, ...); int mvprintw (int y, int x, const char * fmt, ...); int vwprintw (WINDOW * win, const char * fmt, va_list var glist);

The parameters, in particular, of correspond to the function in. Below are excerpts of some conversion symbols for use in

% d,% isigned integer
%Ounsigned integer in octal format
% uunsigned int
% xunsigned integer in hexadecimal format
% f,% FFloating point number (double)
% e,% EFloating point number (double) in exponential representation
% a,% AFloating point number (double) in hexadecimal notation
% sCharacter string (const char *)
% cOne character (char)

Example [edit]

#include #include // required for atexit () void quit () {endwin (); } int main (void) {const int i = 23456; const double f = -12345e-3; initscr (); atexit (quit); curs_set (0); mvprintw (3, 2, "An integer in octal and hexadecimal notation:% o |% x \ n", i, i); mvprintw (4, 2, "An integer with leading zeros:% 010d \ n", i) ; mvprintw (5, 2, "A floating point number:% 8.3f \ n", f); mvprintw (6, 2, "A floating point number:% 8.3e \ n", f); mvprintw (7, 2, "A floating point number in hexadecimal notation:% a \ n ", f); refresh (); getch (); return (0); }

Text entry [edit]

A user interface without the possibility of user input is in most cases relatively useless. The ncurses- Library provides a number of functions for entering data using the keyboard.

Entering a character [edit]

int getch (void); int mvgetch (int y, int x); int ungetch (int ch); int wgetch (WINDOW * win);

corresponds roughly to the function off. writes the character back into the input queue. is a function for entering characters in specially defined windows. The programming of windows is only described in more detail in one of the following chapters.

The interpretation of a return key press is not standardized. Ncurses offers two different functions for this purpose.

int nl (void); int nonl (void);

When using, a return key press (end of line character) is interpreted as 0xA (10dec, LF, Line Feed). When using, pressing a return key only corresponds to 0xD (13dec, CR, Carriage Return).

Entering a character string [edit]

getstr (char * str); getnstr (char * str, int n); mvgetstr (int y, int x, char * str); mvgetnstr (int y, int x, char * str, int n);

Formatted input [edit]

int scanw (char * fmt, ...); int mvscanw (int y, int x, char * fmt, ...); int vwscanw (WINDOW * win, char * fmt, va_list varglist);

is comparable to the conventional one.

Delete actions [edit]

Every now and then a "tabula rasa" promotion is due.

int clear (void); int clrtobot (void); int clrtoeol (void);

deletes the entire standard screen. deletes the content from the current cursor position to the end of the screen. deletes the contents from the current cursor position to the end of the line.

The function

int delete (void);

deletes the entire current line. All subsequent lines are shifted up one line. On the other hand, the function adds

int insertln (void);

a blank line at the current cursor position. All following lines are shifted down one line.

Refresh [edit]

The following instruction is available so that the changes are adopted in the and the screen is updated:

int refresh (void);

Scrolling [edit]

int scroll (WINDOW * win); int scrl (int n);

moves the window content up one line. moves the contents of the window up by one line.

In order for scrolling to work, the following function must be called in advance.

int scrollok (WINDOW * win, bool bf);

The parameter must of course be set to to activate scrolling.

Switch echo on / off [edit]

The input data (the echo) can be displayed using the function

noecho ()

be suppressed.


switches this display on again. This is the default behavior of ncurses.

Beep and flash [edit]

Sometimes a short warning signal to the user can also be useful. Ncurses offers two standard functions for this purpose:

int beep (void); int flash (void);

should produce a short acoustic tone and a short optical "flash". The whole thing depends heavily on the capabilities and settings of the terminal used. If the terminal used has neither audio nor flash capabilities, there is neither an acoustic nor a visual warning. Some of these signals can also be deactivated by the user, e.g. on the KDE console. The use of these functions is therefore of limited use.