X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;ds=inline;f=doc%2Fhtml%2Fman%2Fcurs_initscr.3x.html;h=9e04741d9abc08b96bb7d10a09848d9df0cd82b0;hb=b793748293cd1a764b1a858455399ad899b5a8a1;hp=3c47ac6c2ce3f12c3cbc39f71609ab618e059b4c;hpb=6a530b46563470c2ca73579d1994a0c8e275dd98;p=ncurses.git diff --git a/doc/html/man/curs_initscr.3x.html b/doc/html/man/curs_initscr.3x.html index 3c47ac6c..9e04741d 100644 --- a/doc/html/man/curs_initscr.3x.html +++ b/doc/html/man/curs_initscr.3x.html @@ -1,6 +1,6 @@ @@ -40,19 +40,17 @@
-curs_initscr(3x) curs_initscr(3x) +curs_initscr(3x) curs_initscr(3x) --
- initscr, newterm, endwin, isendwin, set_term, delscreen - - curses screen initialization and manipulation routines +
+ initscr, newterm, endwin, isendwin, set_term, delscreen - curses screen + initialization and manipulation routines --
+
#include <curses.h> WINDOW *initscr(void); @@ -63,36 +61,29 @@ 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. +
+ 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(3x), filter, ripoffline, use_env. For multiple- + terminal applications, 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. + The initscr code determines the terminal type and initializes all curs- + es data structures. initscr also causes the 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 re- + turned 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 - it can continue to run in a line-oriented mode if the ter- - minal cannot support a screen-oriented program, would also - 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. - newterm's arguments are +
+ 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 it can continue to run in a line-oriented mode + if the terminal cannot support a screen-oriented program, would also + use newterm. The routine newterm should be called once for each termi- + nal. It returns a variable of type SCREEN * which should be saved as a + reference to that terminal. newterm's arguments are o the type of the terminal to be used in place of $TERM, @@ -103,186 +94,157 @@ 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. +
+ 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 + A program should always call endwin before exiting or escaping from + curses mode temporarily. This routine - o restores tty modes, + o resets colors to correspond with the default color pair 0, - o moves the cursor to the lower left-hand corner of the - screen and + o moves the cursor to the lower left-hand corner of the screen, - o resets the terminal into the proper non-visual mode. + o clears the remainder of the line so that it uses the default col- + ors, - Calling refresh or doupdate after a temporary escape caus- - es the program to resume visual mode. + o sets the cursor to normal visibility (see curs_set(3x)), + o stops cursor-addressing mode using the exit_ca_mode terminal capa- + bility, --
- The isendwin routine returns TRUE if endwin has been - called without any subsequent calls to wrefresh, and FALSE - otherwise. + o restores tty modes (see reset_shell_mode(3x)). + Calling refresh(3x) or doupdate(3x) after a temporary escape causes the + program to resume visual mode. --
- 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 - routine. This is the only routine which manipulates - SCREEN pointers; all other routines affect only the cur- - rent terminal. +
+ The isendwin routine returns TRUE if endwin has been called without any + subsequent calls to wrefresh, and FALSE otherwise. --
- 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. +
+ The set_term routine is used to switch between different terminals. + The screen reference new becomes the new current terminal. The previ- + ous terminal is returned by the routine. This is the only routine + which manipulates SCREEN pointers; all other routines affect only the + current terminal. --
- endwin returns the integer ERR upon failure and OK upon - successful completion. - Routines that return pointers always return NULL on error. +
+ 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 particular SCREEN is no longer needed. - X/Open defines no error conditions. In this implementa- - tion - o endwin returns an error if the terminal was not ini- - tialized. +
+ endwin returns the integer ERR upon failure and OK upon successful com- + pletion. - o newterm 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. + Routines that return pointers always return NULL on error. - o set_term returns no error. + X/Open defines no error conditions. In this implementation + o endwin returns an error if the terminal was not initialized. --
- Note that initscr and newterm may be macros. + o newterm returns an error if it cannot allocate the data structures + for the screen, or for the top-level windows within the screen, + i.e., curscr, newscr, or stdscr. + o set_term returns no error. --
- These functions were described in the XSI Curses standard, - Issue 4. As of 2015, the current document is X/Open Curs- - es, Issue 7. +
+ These functions were described in the XSI Curses standard, Issue 4. As + of 2015, the current document is X/Open Curses, 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. +
+ 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 - the return value of initscr in XSI Curses. + 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 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 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. +
+ If the TERM variable is missing or empty, initscr uses the value "un- + known", which normally corresponds to a terminal entry with the generic + (gn) capability. Generic entries are detected by setupterm (see + curs_terminfo(3x)) and cannot be used for full-screen operation. Other + implementations may handle a missing/empty TERM variable differently. --
+
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 ... + Curses implementations may provide for special handling 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. + Any special handling for these signals may remain in effect for + the life of the process or until the process changes the disposi- + tion of the signal. - None of the Curses functions are required to be safe - with respect to signals ... + 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: + This implementation establishes signal handlers during initialization, + e.g., initscr or newterm. Applications which must handle these signals + should set up the corresponding handlers after initializing the li- + brary: SIGINT - The handler attempts to cleanup the screen on exit. - Although it usually works as expected, there are lim- - itations: + The handler attempts to cleanup the screen on exit. Although it + usually works as expected, there are limitations: - o Walking the SCREEN list is unsafe, since all list - management is done without any signal blocking. + 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 On systems which have REENTRANT turned on, set_term uses func- + tions 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. + o endwin calls other functions, many of which use stdio or other + library functions which are clearly 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). + 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)). + This handles the stop signal, used in job control. When resuming + the process, this implementation discards 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. + This handles the window-size changes which were initially 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). +
+ curses(3x), curs_kernel(3x), curs_refresh(3x), curs_slk(3x), curs_ter- + minfo(3x), curs_util(3x), curs_variables(3x). - curs_initscr(3x) + curs_initscr(3x)