X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_initscr.3x.html;fp=doc%2Fhtml%2Fman%2Fcurs_initscr.3x.html;h=1b668b29744ec214314c2d829957c9631afea62c;hp=dc06eaddc6592b318dfc74d6d917e8f87d413e1c;hb=32f9f5f12cd9159261f9db228461049e8c770404;hpb=c99e3eba2cce1c3bd7fa1b4a2eb4554e52ebe264 diff --git a/doc/html/man/curs_initscr.3x.html b/doc/html/man/curs_initscr.3x.html index dc06eadd..1b668b29 100644 --- a/doc/html/man/curs_initscr.3x.html +++ b/doc/html/man/curs_initscr.3x.html @@ -1,6 +1,6 @@ @@ -65,6 +65,9 @@
+ ++
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, @@ -78,6 +81,9 @@ 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 initscr. A program that needs to inspect capabilities, so @@ -96,6 +102,9 @@ 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 @@ -115,10 +124,16 @@ 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 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 @@ -126,6 +141,9 @@ 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- @@ -160,21 +178,100 @@
- 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. + 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.@@ -191,10 +288,25 @@