# curs_initscr 3x

    curs_initscr(3x)                                       curs_initscr(3x)

## 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(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
           initializing  a program.  A few special routines sometimes
           need to be called before it; these are  slk_init,  filter,
           ripoffline,  use_env.  For multiple-terminal applications,
           newterm may be called before initscr.

           The initscr code determines the terminal type and initial-
           izes  all curses data structures.  initscr also causes the
           first call to refresh to clear the screen.  If errors  oc-
           cur,  initscr writes an appropriate error message to stan-
           dard 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 ter-
           minal cannot support a screen-oriented 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

           o   the type of the terminal to be used in place of $TERM,

           o   a file pointer for output to the terminal, and

           o   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 before 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 es-
           caping from curses mode temporarily.  This routine

           o   restores tty modes,

           o   moves the cursor to the lower left-hand corner of  the
               screen and

           o   resets the terminal into the proper non-visual mode.

           Calling refresh or doupdate after a temporary escape caus-
           es the program to resume visual mode.

### isendwin

           The isendwin routine  returns  TRUE  if  endwin  has  been
           called without any subsequent calls to wrefresh, and FALSE
           otherwise.

### set_term

           The set_term routine is used to switch  between  different
           terminals.   The screen reference new becomes the new cur-
           rent terminal.  The previous terminal is returned  by  the
           routine.   This  is  the  only  routine  which manipulates
           SCREEN pointers; all other routines affect only  the  cur-
           rent terminal.

### delscreen

           The  delscreen  routine  frees storage associated with the
           SCREEN data structure.  The endwin  routine  does  not  do
           this, so delscreen should be called after endwin if a par-
           ticular 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 implementa-
           tion

           o   endwin returns an error if the terminal was  not  ini-
               tialized.

           o   newterm returns an error if it cannot allocate the da-
               ta structures for the screen,  or  for  the  top-level
               windows  within  the  screen, i.e., curscr, newscr, or
               stdscr.

           o   set_term returns no error.

## NOTES

           Note that initscr and newterm may be macros.

## PORTABILITY

           These functions were described in the XSI Curses standard,
           Issue 4.  As of 2015, the current document is X/Open Curs-
           es, Issue 7.

### Differences

           X/Open specifies that portable applications must not  call
           initscr more than once:

           o   The  portable  way  to use initscr is once only, using
               refresh (see curs_refresh(3x)) to restore  the  screen
               after endwin.

           o   This implementation allows using initscr after endwin.

           Old versions of curses, e.g., BSD 4.4, may have returned 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.

### 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 setupterm (see curs_terminfo(3x)) and can-
           not be used for full-screen operation.  Other  implementa-
           tions  may handle a missing/empty TERM variable different-
           ly.

### Signal Handlers

           Quoting from X/Open Curses, section 3.1.1:

                Curses implementations may provide for  special  han-
                dling  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
           initialization,  e.g.,  initscr  or newterm.  Applications
           which must handle these signals should set up  the  corre-
           sponding handlers after initializing the library:

           SIGINT
                The  handler  attempts to cleanup the screen on exit.
                Although it usually works as expected, there are lim-
                itations:

                o   Walking the SCREEN list is unsafe, since all list
                    management is done without any signal blocking.

                o   On  systems  which  have  REENTRANT  turned   on,
                    set_term  uses  functions which could deadlock or
                    misbehave in other ways.

                o   endwin calls other functions, many of  which  use
                    stdio or other library functions which are clear-
                    ly unsafe.

           SIGTERM
                This uses the same handler as SIGINT, with  the  same
                limitations.   It  is not mentioned in X/Open Curses,
                but is more suitable for this  purpose  than  SIGQUIT
                (which is used in debugging).

           SIGTSTP
                This  handles  the  stop signal, used in job control.
                When resuming the process, this  implementation  dis-
                cards    pending    input    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 ini-
                tially 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 corresponding window, wgetch re-
                turns the key symbol KEY_RESIZE.  At the  same  time,
                wgetch calls resizeterm to adjust the standard screen
                stdscr, and update other data such as LINES and COLS.

## SEE ALSO

           curses(3x),       curs_kernel(3x),       curs_refresh(3x),
           curs_slk(3x), curs_terminfo(3x), curs_util(3x), curs_vari-
           ables(3x).

                                                           curs_initscr(3x)