doc/html/man/curs_initscr.3x.html

   1 <HTML>
   2 <BODY>
   3 <PRE>
   4 <!-- Manpage converted by man2html 3.0.1 -->
   5
   6 </PRE>
   7 <H2>NAME</H2><PRE>
   8        <B>initscr</B>,  <B>newterm</B>, <B>endwin</B>, <B>isendwin</B>, <B>set_term</B>, <B>delscreen</B> -
   9        <B>curses</B> screen initialization and manipulation routines
  10
  11
  12 </PRE>
  13 <H2>SYNOPSIS</H2><PRE>
  14        <B>#include</B> <B>&lt;curses.h&gt;</B>
  15
  16        <B>WINDOW</B> <B>*initscr(void);</B>
  17        <B>int</B> <B>endwin(void);</B>
  18        <B>bool</B> <B>isendwin(void);</B>
  19        <B>SCREEN</B>  <B>*newterm(const</B>  <B>char</B>  <B>*type,</B>  <B>FILE</B>  <B>*outfd,</B>   <B>FILE</B>
  20        <B>*infd);</B>
  21        <B>SCREEN</B> <B>*set_term(SCREEN</B> <B>*new);</B>
  22        <B>void</B> <B>delscreen(SCREEN*</B> <B>sp);</B>
  23
  24
  25 </PRE>
  26 <H2>DESCRIPTION</H2><PRE>
  27        <B>initscr</B>  is normally the first <B>curses</B> routine to call when
  28        initializing a program.  A few special routines  sometimes
  29        need  to  be called before it; these are <B>slk_init</B>, <B>filter</B>,
  30        <B>ripoffline</B>, <B>use_env</B>.  For multiple-terminal  applications,
  31        <B>newterm</B> may be called before <B>initscr</B>.
  32
  33        The initscr code determines the terminal type and initial-
  34        izes all <B>curses</B> data structures.  <B>initscr</B> also causes  the
  35        first  call  to  <B>refresh</B>  to  clear the screen.  If errors
  36        occur, <B>initscr</B> writes  an  appropriate  error  message  to
  37        standard error and exits; otherwise, a pointer is returned
  38        to <B>stdscr</B>.
  39
  40        A program that outputs to more than  one  terminal  should
  41        use  the  <B>newterm</B>  routine  for  each  terminal instead of
  42        <B>initscr</B>.  A program that needs to inspect capabilities, so
  43        it can continue to run in a line-oriented mode if the ter-
  44        minal cannot support a screen-oriented program, would also
  45        use  <B>newterm</B>.   The  routine <B>newterm</B> should be called once
  46        for each terminal.  It returns a variable of type <B>SCREEN</B> <B>*</B>
  47        which  should  be  saved  as a reference to that terminal.
  48        The arguments are the <I>type</I> of the terminal to be  used  in
  49        place of <B>$TERM</B>, a file pointer for output to the terminal,
  50        and another file pointer for input from the  terminal  (if
  51        <I>type</I>  is <B>NULL</B>, <B>$TERM</B> will be used).  The program must also
  52        call <B>endwin</B> for each terminal being  used  before  exiting
  53        from  <B>curses</B>.  If <B>newterm</B> is called more than once for the
  54        same terminal, the first terminal referred to must be  the
  55        last one for which <B>endwin</B> is called.
  56
  57        A  program  should  always  call  <B>endwin</B> before exiting or
  58        escaping  from  <B>curses</B>  mode  temporarily.   This  routine
  59        restores  tty  modes,  moves the cursor to the lower left-
  60        hand corner of the screen and resets the terminal into the
  61        proper non-visual mode.  Calling <B>refresh</B> or <B>doupdate</B> after
  62        a temporary escape causes the  program  to  resume  visual
  63        mode.
  64
  65        The  <B>isendwin</B>  routine  returns  <B>TRUE</B>  if  <B>endwin</B> has been
  66        called without any subsequent calls to <B>wrefresh</B>, and <B>FALSE</B>
  67        otherwise.
  68
  69        The  <B>set_term</B>  routine is used to switch between different
  70        terminals.  The screen reference <B>new</B> becomes the new  cur-
  71        rent  terminal.   The previous terminal is returned by the
  72        routine.  This  is  the  only  routine  which  manipulates
  73        <B>SCREEN</B>  pointers;  all other routines affect only the cur-
  74        rent terminal.
  75
  76        The <B>delscreen</B> routine frees storage  associated  with  the
  77        <B>SCREEN</B>  data  structure.   The  <B>endwin</B> routine does not do
  78        this, so <B>delscreen</B> should be called after <B>endwin</B> if a par-
  79        ticular <B>SCREEN</B> is no longer needed.
  80
  81
  82 </PRE>
  83 <H2>RETURN VALUE</H2><PRE>
  84        <B>endwin</B>  returns  the  integer <B>ERR</B> upon failure and <B>OK</B> upon
  85        successful completion.
  86
  87        Routines that return pointers always return <B>NULL</B> on error.
  88
  89
  90 </PRE>
  91 <H2>NOTES</H2><PRE>
  92        Note that <B>initscr</B> and <B>newterm</B> may be macros.
  93
  94
  95 </PRE>
  96 <H2>PORTABILITY</H2><PRE>
  97        These  functions are described in the XSI Curses standard,
  98        Issue 4.  It specifies that portable applications must not
  99        call <B>initscr</B> more than once.
 100
 101        Old versions of curses, e.g., BSD 4.4, may have returned a
 102        null pointer from  <B>initscr</B>  when  an  error  is  detected,
 103        rather  than  exiting.   It is safe but redundant to check
 104        the return value of <B>initscr</B> in XSI Curses.
 105
 106
 107 </PRE>
 108 <H2>SEE ALSO</H2><PRE>
 109        <B><A HREF="ncurses.3x.html">curses(3x)</A></B>,       <B><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></B>,       <B><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></B>,
 110        <B><A HREF="curs_slk.3x.html">curs_slk(3x)</A></B>, <B><A HREF="curs_util.3x.html">curs_util(3x)</A></B>
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127 </PRE>
 128 <HR>
 129 <ADDRESS>
 130 Man(1) output converted with
 131 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
 132 </ADDRESS>
 133 </BODY>
 134 </HTML>