Function descriptions

This topic describes functions that are important in curses programming.

Initialization and wrapup

initscr()

The first function called should almost always be initscr(). This will determine the terminal type and initialize curses data structures. The initscr() function also establishes that the first call to refresh() will clear the screen. If an error occurs, a message is written to standard error, and the program exits. Otherwise, it returns a pointer to stdscr. A few functions can be called before initscr() (slk_init(), filter(), ripofflines(), use_env(), and, if you are using multiple terminals, newterm()).

endwin()

Your program should always call endwin() before exiting or suspending the program to run a command shell. This function will restore tty modes, move the cursor to the lower-left corner of the screen, and reset the terminal into the proper nonvisual mode. Calling refresh() or doupdate() after a temporary escape from the program will restore the ncurses screen from before the escape.

newterm(type, ofp, ifp)

A program that outputs to more than one terminal should use newterm() instead of initscr(). newterm() should be called once for each terminal. It returns a variable of type SCREEN *, which should be saved as a reference to that terminal. The arguments are the type of the terminal (a string) and FILE pointers for the output and input of the terminal. If type is NULL, the environment variable TERM is used. endwin() should be called once at wrap-up time for each terminal opened using this function.

set_term(new)

You can use this function to switch to a different terminal previously opened by newterm(). The screen reference for the new terminal is passed as the parameter. The previous terminal is returned by the function. All other calls affect only the current terminal.

delscreen(sp)

The inverse of newterm(); de-allocates the data structures associated with a given SCREEN reference.

Sending output to the terminal

refresh() and wrefresh(win)

These functions must be called to get any output on the terminal, as other routines merely manipulate data structures. The wrefresh() function copies the named window to the physical terminal screen, taking into account what is already there in order to do optimizations. The refresh() function does a refresh of stdscr. Unless leaveok() has been enabled, the physical cursor of the terminal is left at the location of the window’s cursor.

doupdate() and wnoutrefresh(win)

These two functions allow multiple updates with more efficiency than wrefresh(). To use them, it is important to understand how curses works. In addition to all the window structures, curses keeps two data structures representing the terminal screen: a physical screen that describes what is actually on the screen, and a virtual screen that describes what you want to have on the screen. The wrefresh() function works by first copying the named window to the virtual screen (wnoutrefresh()), and then calling the routine to update the screen (doupdate()). If you want to output several windows at once, a series of calls to wrefresh() will result in alternating calls to wnoutrefresh() and doupdate(). This causes several bursts of output to the screen. Calling wnoutrefresh() for each window makes it possible to call doupdate() once. This results in only one burst of output, with fewer total characters transmitted. This also prevents a visually annoying flicker at each update.

Low-level capability access

setupterm(term, filenum, errret)

This routine is called to initialize a terminal’s description without setting up the curses screen structures or changing the tty-driver mode bits. The term argument is the character string representing the name of the terminal being used. The filenum argument is the file descriptor of the terminal to be used for output. The errret argument is a pointer to an integer, in which a success or failure indication is returned. The values returned can be: 1 (all is well), 0 (no such terminal), or –1 (some problem locating the terminfo database).

The value of term can be given as NULL, which causes the value of TERM in the environment to be used. The errret pointer can also be given as NULL, meaning no error code is wanted. If errret is defaulted, and something goes wrong, setupterm() prints an appropriate error message and exits rather than returning. Thus, a simple program can call setuterm(0,1,0), which should eliminate concerns about initialization errors.

After the call to setupterm(), the global variable cur_term is set to point to the current structure of terminal capabilities. By calling setupterm() for each terminal, and saving and restoring cur_term, a program can use two or more terminals at once. The setupterm() function also stores the names section of the terminal description in the global character array ttytype[]. Subsequent calls to setupterm() will overwrite this array, so you must save it yourself if need be.

Debugging

The following function is not part of the standard curses application programming interface (API):

trace()

This function can be used to set a trace level explicitly. If the trace level is nonzero, execution of your program will generate a file called trace in the current working directory containing a report on the library’s actions. Higher trace levels enable more detailed (and verbose) reporting (see comments attached to TRACE_ defines in the <curses.h> file for details). (It is also possible to set a trace level by assigning a trace-level value to the environment variable NCURSES_TRACE).