# curs_initscr

## NAME



           **initscr** , **newterm** , **endwin** , **isendwin** , **set_term** , **delscreen** - **curses**
           screen initialization and manipulation routines
    


## SYNOPSIS



           **#include <curses.h>**
    
           **WINDOW *initscr(void);**
           **int endwin(void);**
    
           **bool isendwin(void);**
    
           **SCREEN *newterm(const char ***_type_**, FILE ***_outfd_**, FILE ***_infd_**);**
           **SCREEN *set_term(SCREEN ***_new_**);**
           **void delscreen(SCREEN***_sp_**);**
    


## DESCRIPTION



       **initscr**
           **initscr** is normally the first **curses** routine to call when initial‐
           izing  a  program.   A  few  special routines sometimes need to be
           called before it;  these  are  **slk_init**(3X),  **filter** ,  **ripoffline** ,
           **use_env**.   For  multiple-terminal  applications,  **newterm** may  be
           called before **initscr**.
    
           The initscr code determines the terminal type and initializes  all
           **curses** data structures.  **initscr** also causes the first call to **re‐**
           **fresh**(3X) to clear the screen.  If errors occur, **initscr** writes an
           appropriate  error message to standard error and exits; otherwise,
           a pointer is returned to **stdscr**.
    
       **newterm**
           A program that outputs to more than one terminal  should  use  the
           **newterm** routine  for each terminal instead of **initscr**.  A program
           that needs to inspect capabilities, so it can continue to run in a
           line-oriented mode if the terminal cannot support a screen-orient‐
           ed program, would also use **newterm**.  The routine **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.
           **newterm** 's arguments are
    
           •   the _type_ of the terminal to be used in place of **$TERM** ,
    
           •   a file pointer for output to the terminal, and
    
           •   another file pointer for input from the terminal
    
           If the _type_ parameter is **NULL** , **$TERM** will be used.
    
       **endwin**
           The program must also call **endwin** for each terminal being used be‐
           fore exiting from **curses**.  If **newterm** is called more than once for
           the same terminal, the first terminal referred to must be the last
           one for which **endwin** is called.
    
           A program should always call **endwin** before exiting or escaping
           from **curses** mode temporarily.  This routine
    
           •   resets colors to correspond with the default color pair 0,
    
           •   moves the cursor to the lower left-hand corner of the screen,
    
           •   clears the remainder of the line so that it uses the default
               colors,
    
           •   sets the cursor to normal visibility (see **curs_set**(3X)),
    
           •   stops cursor-addressing mode using the _exit_ca_mode_ terminal
               capability,
    
           •   restores tty modes (see **reset_shell_mode**(3X)).
    
           Calling **refresh**(3X) or **doupdate**(3X) after a temporary escape caus‐
           es the program to resume visual mode.
    
       **isendwin**
           The **isendwin** routine returns **TRUE** if **endwin** has been called with‐
           out any subsequent calls to **wrefresh** , and **FALSE** otherwise.
    
       **set_term**
           The **set_term** routine is used to switch between different termi‐
           nals.  The screen reference _new_ becomes the new current terminal.
           The previous terminal is returned by the routine.  This is the on‐
           ly routine which manipulates **SCREEN** pointers; all other routines
           affect only the current terminal.
    
       **delscreen**
           The **delscreen** routine frees storage associated with the **SCREEN** da‐
           ta structure.  The **endwin** routine does not do this, so **delscreen**
           should be called after **endwin** if a particular **SCREEN** is no longer
           needed.
    


## RETURN VALUE



           **endwin** returns the integer **ERR** upon failure and **OK** upon successful
           completion.
    
           Routines that return pointers always return **NULL** on error.
    
           X/Open defines no error conditions.  In this implementation
    
           •   **endwin** returns an error if the terminal was not initialized.
    
           •   **newterm** returns an error if it cannot allocate the data struc‐
               tures for the screen, or for the top-level windows within the
               screen, i.e., **curscr** , **newscr** , or **stdscr**.
    
           •   **set_term** returns no error.
    


## PORTABILITY



           These functions were described in the XSI Curses standard, Issue
           4.  As of 2015, the current document is X/Open Curses, Issue 7.
    
       **Differences**
           X/Open specifies that portable applications must not call **initscr**
           more than once:
    
           •   The portable way to use **initscr** is once only, using **refresh**
               (see curs_refresh(3X)) to restore the screen after **endwin**.
    
           •   This implementation allows using **initscr** after **endwin**.
    
           Old versions of curses, e.g., BSD 4.4, would return a null pointer
           from **initscr** when an error is detected, rather than exiting.  It
           is safe but redundant to check the return value of **initscr** in XSI
           Curses.
    
           Calling **endwin** does not dispose of the memory allocated in **initscr**
           or **newterm**.  Deleting a **SCREEN** provides a way to do this:
    
           •   X/Open Curses does not say what happens to **WINDOW** s when
               **delscreen** “frees storage associated with the **SCREEN** ” nor does
               the SVr4 documentation help, adding that it should be called
               after **endwin** if a **SCREEN** is no longer needed.
    
           •   However, **WINDOW** s are implicitly associated with a **SCREEN**.  so
               that it is reasonable to expect **delscreen** to deal with these.
    
           •   SVr4 curses deletes the standard **WINDOW** structures **stdscr** and
               **curscr** as well as a work area **newscr**.  SVr4 curses ignores
               other windows.
    
           •   Since version 4.0 (1996), ncurses has maintained a list of all
               windows for each screen, using that information to delete
               those windows when **delscreen** is called.
    
           •   NetBSD copied this feature of ncurses in 2001.  PDCurses fol‐
               lows the SVr4 model, deleting only the standard **WINDOW** struc‐
               tures.
    
       **Unset TERM Variable**
           If the TERM variable is missing or empty, **initscr** uses the value
           “unknown”, which normally corresponds to a terminal entry with the
           _generic_ (_gn_) capability.  Generic entries are detected by **se‐**
           **tupterm**(see curs_terminfo(3X)) and cannot be used for full-screen
           operation.  Other implementations may handle a missing/empty TERM
           variable differently.
    
       **Signal Handlers**
           Quoting from X/Open Curses, section 3.1.1:
    
                _Curses implementations may provide for special handling of_
                _the_ **SIGINT** _,_ **SIGQUIT** _and_ **SIGTSTP** _signals if their disposition_
                _is_ **SIG_DFL** _at the time_ **initscr** _is called_ ...
    
                _Any special handling for these signals may remain in effect_
                _for the life of the process or until the process changes the_
                _disposition of the signal._
    
                _None of the Curses functions are required to be safe with_
                _respect to signals_ ...
    
           This implementation establishes signal handlers during initializa‐
           tion, e.g., **initscr** or **newterm**.  Applications which must handle
           these signals should set up the corresponding handlers _after_ ini‐
           tializing the library:
    
           **SIGINT**
                The handler _attempts_ to cleanup the screen on exit.  Although
                it _usually_ works as expected, there are limitations:
    
                •   Walking the **SCREEN** list is unsafe, since all list manage‐
                    ment is done without any signal blocking.
    
                •   On systems which have **REENTRANT** turned on, **set_term** uses
                    functions which could deadlock or misbehave in other
                    ways.
    
                •   **endwin** calls other functions, many of which use stdio or
                    other library functions which are clearly unsafe.
    
           **SIGTERM**
                This uses the same handler as **SIGINT** , with the same limita‐
                tions.  It is not mentioned in X/Open Curses, but is more
                suitable for this purpose than **SIGQUIT**(which is used in de‐
                bugging).
    
           **SIGTSTP**
                This handles the _stop_ signal, used in job control.  When re‐
                suming the process, this implementation discards pending in‐
                put with **flushinput**(see curs_util(3X)), and repaints the
                screen assuming that it has been completely altered.  It also
                updates the saved terminal modes with **def_shell_mode**(see
                **curs_kernel**(3X)).
    
           **SIGWINCH**
                This handles the window-size changes which were ignored in
                the standardization efforts.  The handler sets a (signal-
                safe) variable which is later tested in **wgetch**(see
                curs_getch(3X)).  If **keypad** has been enabled for the corre‐
                sponding window, **wgetch** returns the key symbol **KEY_RESIZE**.
                At the same time, **wgetch** calls **resizeterm** to adjust the stan‐
                dard screen **stdscr** , and update other data such as **LINES** and
                **COLS**.
    


* * *