initscr(3X)

DESCRIPTION

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

The newterm() 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 TERM 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() function should be called once for each terminal.

The initscr() function is equivalent to:

If the current disposition for the signals SIGINT, SIGQUIT or SIGTSTP is SIGDFL, then initscr() 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() and newterm() functions initialise the cur_term external variable.

RETURN VALUE

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

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

ERRORS

No errors are defined.

APPLICATION USAGE

A program that outputs to more than one terminal should use newterm() for each terminal instead of initscr(). 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().

SEE ALSO

delscreen(3X), doupdate(3X), del_curterm(3X), filter(3X), slk_attroff(3X), use_env(3X), terminfo(4), see Selecting a Terminal, <curses.h>.

CHANGE HISTORY

First released in X/Open Curses, Issue 2.

X/Open Curses, Issue 4

The newterm() function is merged with this entry. In previous issues, it appeared in an entry of its own.

The entry is rewritten for clarity. The argument list for the initscr() function is explicitly declared as void.