4 <!-- Manpage converted by man2html 3.0.1 -->
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
13 <H2>SYNOPSIS</H2><PRE>
14 <B>#include</B> <B><curses.h></B>
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>
21 <B>SCREEN</B> <B>*set_term(SCREEN</B> <B>*new);</B>
22 <B>void</B> <B>delscreen(SCREEN*</B> <B>sp);</B>
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>.
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
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.
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
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>
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-
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.
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.
87 Routines that return pointers always return <B>NULL</B> on error.
92 Note that <B>initscr</B> and <B>newterm</B> may be macros.
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.
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.
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>
130 Man(1) output converted with
131 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>