1curs_initscr(3X) curs_initscr(3X)
2
6 initscr, newterm, endwin, isendwin, set_term, delscreen - curses screen
7 initialization and manipulation routines
8
10 #include <curses.h>
11 WINDOW *initscr(void);
13 int endwin(void);
14 bool isendwin(void);
15 SCREEN *newterm(char *type, FILE *outfd, FILE *infd);
16 SCREEN *set_term(SCREEN *new);
17 void delscreen(SCREEN* sp);
18
20 initscr is normally the first curses routine to call when initializing
21 a program. A few special routines sometimes need to be called before
22 it; these are slk_init, filter, ripoffline, use_env. For multiple-ter‐
23 minal applications, newterm may be called before initscr.
24 The initscr code determines the terminal type and initializes all curs‐
26 es data structures. initscr also causes the first call to refresh to
27 clear the screen. If errors occur, initscr writes an appropriate error
28 message to standard error and exits; otherwise, a pointer is returned
29 to stdscr.
30 A program that outputs to more than one terminal should use the newterm
32 routine for each terminal instead of initscr. A program that needs to
33 inspect capabilities, so it can continue to run in a line-oriented mode
34 if the terminal cannot support a screen-oriented program, would also
35 use newterm. The routine newterm should be called once for each termi‐
36 nal. It returns a variable of type SCREEN * which should be saved as a
37 reference to that terminal. The arguments are the type of the terminal
38 to be used in place of $TERM, a file pointer for output to the termi‐
39 nal, and another file pointer for input from the terminal (if type is
40 NULL, $TERM will be used). The program must also call endwin for each
41 terminal being used before exiting from curses. If newterm is called
42 more than once for the same terminal, the first terminal referred to
43 must be the last one for which endwin is called.
44 A program should always call endwin before exiting or escaping from
46 curses mode temporarily. This routine restores tty modes, moves the
47 cursor to the lower left-hand corner of the screen and resets the ter‐
48 minal into the proper non-visual mode. Calling refresh or doupdate af‐
49 ter a temporary escape causes the program to resume visual mode.
50 The isendwin routine returns TRUE if endwin has been called without any
52 subsequent calls to wrefresh, and FALSE otherwise.
53 The set_term routine is used to switch between different terminals.
55 The screen reference new becomes the new current terminal. The previ‐
56 ous terminal is returned by the routine. This is the only routine
57 which manipulates SCREEN pointers; all other routines affect only the
58 current terminal.
59 The delscreen routine frees storage associated with the SCREEN data
61 structure. The endwin routine does not do this, so delscreen should be
62 called after endwin if a particular SCREEN is no longer needed.
63
65 endwin returns the integer ERR upon failure and OK upon successful com‐
66 pletion.
67 Routines that return pointers always return NULL on error.
69 X/Open defines no error conditions. In this implementation endwin re‐
71 turns an error if the terminal was not initialized.
72
74 Note that initscr and newterm may be macros.
75
77 These functions are described in the XSI Curses standard, Issue 4. It
78 specifies that portable applications must not call initscr more than
79 once.
80 Old versions of curses, e.g., BSD 4.4, may have returned a null pointer
82 from initscr when an error is detected, rather than exiting. It is
83 safe but redundant to check the return value of initscr in XSI Curses.
84
86 curses(3X), curs_kernel(3X), curs_refresh(3X), curs_slk(3X),
87 curs_util(3X)
88 curs_initscr(3X)