X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_initscr.3x.html;h=ff3e6c26db896c22da47e109b7f18b7a4e15fab7;hp=e973b2569e952667860bbbc27d3f84d2a2dc6b49;hb=HEAD;hpb=c6cfd97b8beaf0f6deafbf8aac7281cf6aa7f012 diff --git a/doc/html/man/curs_initscr.3x.html b/doc/html/man/curs_initscr.3x.html index e973b256..778fc001 100644 --- a/doc/html/man/curs_initscr.3x.html +++ b/doc/html/man/curs_initscr.3x.html @@ -1,6 +1,7 @@ -
- --curs_initscr(3x) curs_initscr(3x) +curs_initscr(3x) Library calls curs_initscr(3x) --
- initscr, newterm, endwin, isendwin, set_term, delscreen - - curses screen initialization and manipulation routines +
+ initscr, newterm, endwin, isendwin, set_term, delscreen - initialize, + manipulate, or tear down curses terminal interface --
+
#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(const char *type, FILE *outf, FILE *inf); + 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. - - 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. - - 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 + +
+ +
+ 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 initializes all + curses 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 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 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 terminal. 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, - o a file pointer for output to the terminal, and + o an output stream connected to the terminal, and - o another file pointer for input from the terminal + o an input stream connected to 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. + The file descriptor of the output stream is passed to setupterm(3x), + which returns a pointer to a TERMINAL structure. newterm's return + value holds a pointer to the TERMINAL structure. - A program should always call endwin before exiting or es- - caping from curses mode temporarily. This routine - o restores tty modes, +
+ 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. - o moves the cursor to the lower left-hand corner of the - screen and + A program should always call endwin before exiting or escaping from + curses mode temporarily. This routine - o resets the terminal into the proper non-visual mode. + o resets colors to correspond with the default color pair 0, - Calling refresh or doupdate after a temporary escape caus- - es the program to resume visual mode. + o moves the cursor to the lower left-hand corner of the screen, - The isendwin routine returns TRUE if endwin has been - called without any subsequent calls to wrefresh, and FALSE - otherwise. + o clears the remainder of the line so that it uses the default + colors, - 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. + o sets the cursor to normal visibility (see curs_set(3x)), - 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. + o stops cursor-addressing mode using the exit_ca_mode terminal + capability, + o restores tty modes (see reset_shell_mode(3x)). --
- endwin returns the integer ERR upon failure and OK upon - successful completion. + Calling refresh(3x) or doupdate(3x) 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 current terminal. The + previous terminal is returned by the routine. This is the only routine + which manipulates SCREEN pointers; all other routines affect only the + current 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 particular SCREEN is no longer needed. + + +
+ 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 + X/Open defines no error conditions. In this implementation + + o endwin returns an error if - o endwin returns an error if the terminal was not ini- - tialized. + o the terminal was not initialized, or - 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. + o endwin is called more than once without updating the screen, or + + o reset_shell_mode(3x) returns an error. + + 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. --
- Note that initscr and newterm may be macros. +
+ These functions were described in X/Open Curses, Issue 4. As of 2015, + the current document is X/Open Curses, Issue 7. --
- These functions are described in the XSI Curses standard, - Issue 4. It specifies that portable applications must not - call initscr more than once. +
+ X/Open Curses specifies that portable applications must not call + initscr more than once: - 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. + o The portable way to use initscr is once only, using refresh(3x) to + restore the screen after endwin. - 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. + o This implementation allows using initscr after endwin. + Old versions of curses, e.g., BSD 4.4, would return 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 X/Open Curses. --
- curses(3x), curs_kernel(3x), curs_refresh(3x), - curs_slk(3x), curs_terminfo(3x), curs_util(3x), curs_vari- - ables(3x). + Calling endwin does not dispose of the memory allocated in initscr or + newterm. Deleting a SCREEN provides a way to do this: + + o X/Open Curses does not say what happens to WINDOWs when delscreen + "frees storage associated with the SCREEN" nor does the SVr4 + documentation help, adding that it should be called after endwin if + a SCREEN is no longer needed. + + o However, WINDOWs are implicitly associated with a SCREEN. so that + it is reasonable to expect delscreen to deal with these. + o SVr4 curses deletes the standard WINDOW structures stdscr and + curscr as well as a work area newscr. SVr4 curses ignores other + windows. + o Since version 4.0 (1996), ncurses has maintained a list of all + windows for each screen, using that information to delete those + windows when delscreen is called. - curs_initscr(3x) + o NetBSD copied this feature of ncurses in 2001. PDCurses follows + the SVr4 model, deleting only the standard WINDOW structures. + + +
+ Different implementations may disagree regarding the level of some + functions. For example, SCREEN (returned by newterm) and TERMINAL + (returned by setupterm(3x)) hold file descriptors for the output + stream. If an application switches screens using set_term, or switches + terminals using set_curterm(3x), applications which use the output file + descriptor can have different behavior depending on which structure + holds the corresponding descriptor. + + For example + + o NetBSD's baudrate(3x) function uses the descriptor in TERMINAL. + ncurses and SVr4 use the descriptor in SCREEN. + + o NetBSD and ncurses use the descriptor in TERMINAL for terminal I/O + modes, e.g., def_shell_mode(3x), def_prog_mode(3x). SVr4 curses + uses the descriptor in SCREEN. + + Unset TERM Variable + 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(3x) + and cannot be used for full-screen operation. Other implementations + may handle a missing/empty TERM variable differently. + + +
+ Quoting from X/Open Curses Issue 7, section 3.1.1: + + 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. + + 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 corresponding handlers after initializing the + library: + + SIGINT + The handler attempts to clean up 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 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(3) 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). + + SIGTSTP + This handles the stop signal, used in job control. When resuming + the process, this implementation discards pending input with + flushinp(3x), and repaints the screen assuming that it has been + completely altered. It also updates the saved terminal modes with + def_shell_mode(3x). + + SIGWINCH + This handles the window-size changes which were ignored in the + standardization efforts. The handler sets a (signal-safe) + variable which is later tested in wgetch(3x). If keypad has been + enabled for the corresponding window, wgetch returns 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_variables(3x) + + + +ncurses 6.5 2024-04-20 curs_initscr(3x)