ncurses 5.1
[ncurses.git] / 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>