X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_initscr.3x.html;h=7f398881f2d59a27322d9567a6e95db953609393;hp=e973b2569e952667860bbbc27d3f84d2a2dc6b49;hb=302a066a01e4de40f08b397e87ca0e97f20870a7;hpb=c6cfd97b8beaf0f6deafbf8aac7281cf6aa7f012
diff --git a/doc/html/man/curs_initscr.3x.html b/doc/html/man/curs_initscr.3x.html
index e973b256..7f398881 100644
--- a/doc/html/man/curs_initscr.3x.html
+++ b/doc/html/man/curs_initscr.3x.html
@@ -1,6 +1,6 @@
@@ -38,47 +38,47 @@
-curs_initscr 3x
-
+
curs_initscr(3x) curs_initscr(3x)
-
-
+
initscr, newterm, endwin, isendwin, set_term, delscreen -
curses screen initialization and manipulation routines
-
-
+
#include <curses.h>
WINDOW *initscr(void);
int endwin(void);
bool isendwin(void);
- SCREEN *newterm(char *type, FILE *outfd, FILE *infd);
- SCREEN *set_term(SCREEN *new);
- void delscreen(SCREEN* sp);
+ SCREEN *newterm(char *type, FILE *outfd, FILE *infd);
+ SCREEN *set_term(SCREEN *new);
+ void delscreen(SCREEN* sp);
-
-
+
+
+
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,
- ripoffline, use_env. For multiple-terminal applications,
- newterm may be called before initscr.
+ need to be called before it; these are slk_init(3x), fil-
+ ter, ripoffline, use_env. For multiple-terminal applica-
+ tions, newterm may be called before initscr.
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 oc-
- cur, initscr writes an appropriate error message to stan-
- dard error and exits; otherwise, a pointer is returned to
- stdscr.
+ first call to refresh(3x) 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.
+
+
A program that outputs to more than one terminal should
use the newterm routine for each terminal instead of
initscr. A program that needs to inspect capabilities, so
@@ -97,6 +97,8 @@
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
@@ -113,13 +115,17 @@
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.
+ Calling refresh(3x) or doupdate after a temporary escape
+ causes the program to resume visual mode.
+
+
The isendwin routine returns TRUE if endwin has been
called without any subsequent calls to wrefresh, and FALSE
otherwise.
+
+
The set_term routine is used to switch between different
terminals. The screen reference new becomes the new cur-
rent terminal. The previous terminal is returned by the
@@ -127,14 +133,15 @@
SCREEN pointers; all other routines affect only the cur-
rent terminal.
+
+
The delscreen routine frees storage associated with the
SCREEN data structure. The endwin routine does not do
this, so delscreen should be called after endwin if a par-
ticular SCREEN is no longer needed.
-
-
+
endwin returns the integer ERR upon failure and OK upon
successful completion.
@@ -154,32 +161,105 @@
o set_term returns no error.
-
-
+
Note that initscr and newterm may be macros.
-
-
- These functions are described in the XSI Curses standard,
- Issue 4. It specifies that portable applications must not
- call initscr more than once.
+
+ These functions were described in the XSI Curses standard,
+ Issue 4. As of 2015, the current document is X/Open Curs-
+ es, Issue 7.
+
+
+
+ X/Open specifies that portable applications must not call
+ initscr more than once:
+
+ o The portable way to use initscr is once only, using
+ refresh (see curs_refresh(3x)) to restore the screen
+ after endwin.
+
+ o This implementation allows using initscr after endwin.
Old versions of curses, e.g., BSD 4.4, may have returned a
- null pointer from initscr when an error is detected,
- rather than exiting. It is safe but redundant to check
+ null pointer from initscr when an error is detected,
+ 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.
-
-
-
+
+ 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 setupterm (see curs_terminfo(3x)) and can-
+ not be used for full-screen operation. Other implementa-
+ tions may handle a missing/empty TERM variable different-
+ ly.
+
+
+
+ Quoting from X/Open Curses, section 3.1.1:
+
+ Curses implementations may provide for special han-
+ dling of the SIGINT, SIGQUIT and SIGTSTP signals if
+ their disposition is SIG_DFL at the time initscr is
+ called ...
+
+ Any special handling for these signals may remain in
+ effect for the life of the process or until the
+ process changes the disposition of the signal.
+
+ None of the Curses functions are required to be safe
+ with respect to signals ...
+
+ This implementation establishes signal handlers during
+ initialization, e.g., initscr or newterm. Applications
+ which must handle these signals should set up the corre-
+ sponding handlers after initializing the library:
+
+ SIGINT
+ The handler attempts to cleanup the screen on exit.
+ Although it usually works as expected, there are lim-
+ itations:
+
+ o Walking the SCREEN list is unsafe, since all list
+ management is done without any signal blocking.
+
+ o On systems which have REENTRANT turned on,
+ set_term uses functions which could deadlock or
+ misbehave in other ways.
+
+ o endwin calls other functions, many of which use
+ stdio or other library functions which are clear-
+ ly unsafe.
+
+ SIGTERM
+ This uses the same handler as SIGINT, with the same
+ limitations. It is not mentioned in X/Open Curses,
+ but is more suitable for this purpose than SIGQUIT
+ (which is used in debugging).
+
+ SIGTSTP
+ This handles the stop signal, used in job control.
+ When resuming the process, this implementation dis-
+ cards pending input with flushinput (see
+ curs_util(3x)), and repaints the screen assuming that
+ it has been completely altered. It also updates the
+ saved terminal modes with def_shell_mode (see
+ curs_kernel(3x)).
+
+ SIGWINCH
+ This handles the window-size changes which were ini-
+ tially ignored in the standardization efforts. The
+ handler sets a (signal-safe) variable which is later
+ tested in wgetch (see curs_getch(3x)). If keypad has
+ been enabled for the corresponding window, wgetch re-
+ turns the key symbol KEY_RESIZE. At the same time,
+ wgetch calls resizeterm to adjust the standard screen
+ stdscr, and update other data such as LINES and COLS.
+
+
+
curses(3x), curs_kernel(3x), curs_refresh(3x),
curs_slk(3x), curs_terminfo(3x), curs_util(3x), curs_vari-
ables(3x).
@@ -192,10 +272,25 @@