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(3x),  fil-
       ter,  ripoffline, use_env.  For multiple-terminal applica-
       tions, 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(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 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(3x)  or doupdate after a temporary escape
       causes 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)