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, filter,
@@ -69,10 +74,10 @@
The initscr code determines the terminal type and initial-
izes all curses data structures. initscr also causes the
- first call to refresh 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.
+ first call to refresh to clear the screen. If errors oc-
+ cur, initscr writes an appropriate error message to stan-
+ dard error and exits; otherwise, a pointer is returned to
+ stdscr.
A program that outputs to more than one terminal should
use the newterm routine for each terminal instead of
@@ -82,22 +87,34 @@
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.
- The arguments are the type of the terminal to be used in
- place of $TERM, a file pointer for output to the terminal,
- and another file pointer for input from the terminal (if
- type is NULL, $TERM will be used). 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
- escaping from curses mode temporarily. This routine
- restores tty modes, moves the cursor to the lower left-
- hand corner of the screen and resets the terminal into the
- proper non-visual mode. Calling refresh or doupdate after
- a temporary escape causes the program to resume visual
- mode.
+ 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.
+
+ 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 or doupdate after a temporary escape caus-
+ es the program to resume visual mode.
The isendwin routine returns TRUE if endwin has been
called without any subsequent calls to wrefresh, and FALSE
@@ -117,20 +134,33 @@
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
+
+ oendwin returns an error if the terminal was not ini-
+ tialized.
+
+ onewterm 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.
+
+ oset_term returns no error.
+
These functions are described in the XSI Curses standard,
Issue 4. It specifies that portable applications must not
call initscr more than once.
@@ -140,33 +170,34 @@
rather than exiting. It is safe but redundant to check
the return value of initscr in XSI Curses.
+ 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 curs_terminfo(3x) and cannot be used for full-
+ screen operation. Other implementations may handle a
+ missing/empty TERM variable differently.
+