initscr(CURSES)

initscr -- screen initialisation functions

Synopsis

cc [options] file -lcurses

#include <curses.h>

WINDOW *initscr(void);

SCREEN *newterm(char *type, FILE *outfile, FILE *infile);

Description

The initscr(CURSES) function determines the terminal type and initialises all implementation data structures. The environment variable specifies the terminal type. The initscr(CURSES) function also causes the first refresh operation to clear the screen. If errors occur, initscr(CURSES) writes an appropriate error message to standard error and exits. The only functions that can be called before initscr(CURSES) or newterm(CURSES) are filter(CURSES), ripoffline(CURSES), slk_init(CURSES), use_env(CURSES) and the functions whose prototypes are defined in <term.h>. Portable applications must not call initscr(CURSES) twice.

The newterm(CURSES) function can be called as many times as desired to attach a terminal device. The type argument points to a string specifying the terminal type, except that if type is a null pointer, the environment variable is used. The outfile and infile arguments are file pointers for output to the terminal and input from the terminal, respectively. It is unspecified whether Curses modifies the buffering mode of these file pointers. The newterm(CURSES) function should be called once for each terminal.

The initscr(CURSES) function is equivalent to:

   newterm(getenv("TERM"), stdout, stdin);
   return stdscr;

If the current disposition for the signals SIGINT, SIGQUIT or SIGTSTP is SIGDFL, then initscr(CURSES) may also install a handler for the signal, which may remain in effect for the life of the process or until the process changes the disposition of the signal.

The initscr(CURSES) and newterm(CURSES) functions initialise the cur_term external variable.

Return value

Upon successful completion, initscr(CURSES) returns a pointer to stdscr. Otherwise, it does not return.

Upon successful completion, newterm(CURSES) returns a pointer to the specified terminal. Otherwise, it returns a null pointer.

Errors

No errors are defined.

Usage

A program that outputs to more than one terminal should use newterm(CURSES) for each terminal instead of initscr(CURSES). A program that needs an indication of error conditions, so it can continue to run in a line-oriented mode if the terminal cannot support a screen-oriented program, would also use this function.

Applications should perform any required handling of the SIGINT, SIGQUIT, or SIGTSTP signals before calling initscr(CURSES).

Standards Conformance

The Single UNIX Specification, Version 2; The Open Group.

References

delscreen(CURSES), doupdate(CURSES), del_curterm(CURSES), filter(CURSES), slk_attroff(CURSES), use_env(CURSES), curses(F)