diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man3/initscr.3ncurses')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man3/initscr.3ncurses | 319 |
1 files changed, 319 insertions, 0 deletions
diff --git a/upstream/opensuse-tumbleweed/man3/initscr.3ncurses b/upstream/opensuse-tumbleweed/man3/initscr.3ncurses new file mode 100644 index 00000000..92f760fa --- /dev/null +++ b/upstream/opensuse-tumbleweed/man3/initscr.3ncurses @@ -0,0 +1,319 @@ +.\"*************************************************************************** +.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_initscr.3x,v 1.62 2024/02/24 20:03:50 tom Exp $ +.TH initscr 3NCURSES 2024-02-24 "ncurses 6.4" "Library calls" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fB\%initscr\fP, +\fB\%newterm\fP, +\fB\%endwin\fP, +\fB\%isendwin\fP, +\fB\%set_term\fP, +\fB\%delscreen\fP \- +initialize, manipulate, or tear down \fIcurses\fR terminal interface +.SH SYNOPSIS +.nf +\fB#include <ncursesw/curses.h> +.PP +\fBWINDOW *initscr(void); +\fBint endwin(void); +.PP +\fBbool isendwin(void); +.PP +\fBSCREEN *newterm(const char *\fItype\fP, FILE *\fIoutf\fP, FILE *\fIinf\fP); +\fBSCREEN *set_term(SCREEN *\fInew\fP); +\fBvoid delscreen(SCREEN* \fIsp\fP); +.fi +.SH DESCRIPTION +.SS initscr +\fBinitscr\fP is normally the first \fBcurses\fP routine to call when +initializing a program. +A few special routines sometimes need to be called before it; +these are \fB\%slk_init\fP(3NCURSES), \fBfilter\fP, \fBripoffline\fP, +\fBuse_env\fP. +For multiple-terminal applications, +\fBnewterm\fP may be called before \fBinitscr\fP. +.PP +The initscr code determines the terminal type and initializes all \fBcurses\fP +data structures. +\fBinitscr\fP also causes the first call to \fB\%refresh\fP(3NCURSES) +to clear the screen. +If errors occur, \fBinitscr\fP writes an appropriate error +message to standard error and exits; +otherwise, a pointer is returned to \fBstdscr\fP. +.SS newterm +A program that outputs to more than one terminal should use the \fBnewterm\fP +routine for each terminal instead of \fBinitscr\fP. +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 +\fBnewterm\fP. +.PP +The routine \fBnewterm\fP should be called once for each terminal. +It returns a variable of type \fISCREEN *\fP which should be saved +as a reference to that terminal. +\fBnewterm\fP's arguments are +.bP +the \fItype\fP of the terminal to be used in place of \fB$TERM\fP, +.bP +an output stream connected to the terminal, and +.bP +an input stream connected to the terminal +.PP +If the \fItype\fP parameter is \fBNULL\fP, \fB$TERM\fP will be used. +.PP +The file descriptor of the output stream is passed to \fB\%setupterm\fP(3NCURSES), +which returns a pointer to a \fI\%TERMINAL\fP structure. +\fBnewterm\fP's return value holds a pointer to the \fI\%TERMINAL\fP structure. +.SS endwin +The program must also call +\fBendwin\fP for each terminal being used before exiting from \fBcurses\fP. +If \fBnewterm\fP is called more than once for the same terminal, the first +terminal referred to must be the last one for which \fBendwin\fP is called. +.PP +A program should always call \fBendwin\fP before exiting or escaping from +\fBcurses\fP mode temporarily. +This routine +.bP +resets colors to correspond with the default color pair 0, +.bP +moves the cursor to the lower left-hand corner of the screen, +.bP +clears the remainder of the line so that it uses the default colors, +.bP +sets the cursor to normal visibility (see \fB\%curs_set\fP(3NCURSES)), +.bP +stops cursor-addressing mode using the \fIexit_ca_mode\fP terminal capability, +.bP +restores tty modes (see \fB\%reset_shell_mode\fP(3NCURSES)). +.PP +Calling \fB\%refresh\fP(3NCURSES) or \fB\%doupdate\fP(3NCURSES) after a +temporary escape causes the program to resume visual mode. +.SS isendwin +The \fBisendwin\fP routine returns \fBTRUE\fP if \fBendwin\fP has been +called without any subsequent calls to \fBwrefresh\fP, +and \fBFALSE\fP otherwise. +.SS set_term +The \fBset_term\fP routine is used to switch between different terminals. +The screen reference \fInew\fP becomes the new current terminal. +The previous terminal is returned by the routine. +This is the only routine which manipulates \fISCREEN\fP pointers; +all other routines affect only the current terminal. +.SS delscreen +The \fBdelscreen\fP routine frees storage associated with the +\fISCREEN\fP data structure. +The \fBendwin\fP routine does not do +this, so \fBdelscreen\fP should be called after \fBendwin\fP if a +particular \fISCREEN\fP is no longer needed. +.SH RETURN VALUE +\fBendwin\fP returns the integer \fBERR\fP upon failure and \fBOK\fP +upon successful completion. +.PP +Routines that return pointers always return \fBNULL\fP on error. +.PP +X/Open defines no error conditions. +In this implementation +.bP +\fBendwin\fP returns an error if +.RS +.bP +the terminal was not initialized, or +.bP +\fBendwin\fP is called more than once without updating the screen, or +.bP +\fB\%reset_shell_mode\fP(3NCURSES) returns an error. +.RE +.bP +\fBnewterm\fP +returns an error if it cannot allocate the data structures for the screen, +or for the top-level windows within the screen, +i.e., +\fBcurscr\fP, \fBnewscr\fP, or \fBstdscr\fP. +.bP +\fBset_term\fP +returns no error. +.SH PORTABILITY +These functions were described in the XSI Curses standard, Issue 4. +As of 2015, the current document is X/Open Curses, Issue 7. +.SS Differences +X/Open specifies that portable applications must not +call \fBinitscr\fP more than once: +.bP +The portable way to use \fBinitscr\fP is once only, +using \fB\%refresh\fP(3NCURSES) +to restore the screen after \fBendwin\fP. +.bP +This implementation allows using \fBinitscr\fP after \fBendwin\fP. +.PP +Old versions of curses, e.g., BSD 4.4, would return a null pointer +from \fBinitscr\fP when an error is detected, rather than exiting. +It is safe but redundant to check the return value of \fBinitscr\fP +in XSI Curses. +.PP +Calling \fBendwin\fP does not dispose of the memory allocated in \fBinitscr\fP +or \fBnewterm\fP. +Deleting a \fISCREEN\fP provides a way to do this: +.bP +X/Open Curses does not say what happens to \fI\%WINDOW\fPs when \fBdelscreen\fP +\*(``frees storage associated with the \fISCREEN\fP\*('' +nor does the SVr4 documentation help, +adding that it should be called after \fBendwin\fP if a \fISCREEN\fP +is no longer needed. +.bP +However, \fI\%WINDOW\fPs are implicitly associated with a \fISCREEN\fP. +so that it is reasonable to expect \fBdelscreen\fP to deal with these. +.bP +SVr4 curses deletes the standard \fI\%WINDOW\fP structures +\fBstdscr\fP and \fBcurscr\fP as well as a work area \fBnewscr\fP. +SVr4 curses ignores other windows. +.bP +Since version 4.0 (1996), +\fI\%ncurses\fP has maintained a list of all windows for each screen, +using that information to delete those windows when \fBdelscreen\fP is called. +.bP +NetBSD copied this feature of \fI\%ncurses\fP in 2001. +PDCurses follows the SVr4 model, +deleting only the standard \fI\%WINDOW\fP structures. +.SS "High-level versus Low-level" +Different implementations may disagree regarding the level of some functions. +For example, \fISCREEN\fP (returned by \fBnewterm\fP) and +\fI\%TERMINAL\fP (returned by \fB\%setupterm\fP(3NCURSES)) hold file descriptors for +the output stream. +If an application switches screens using \fBset_term\fR, +or switches terminals using \fB\%set_curterm\fP(3NCURSES), +applications which use the output file descriptor can have different +behavior depending on which structure holds the corresponding descriptor. +.PP +For example +.bP +NetBSD's \fB\%baudrate\fP(3NCURSES) function uses the descriptor in \fI\%TERMINAL\fP. +\fI\%ncurses\fP and SVr4 use the descriptor in \fISCREEN\fP. +.bP +NetBSD and \fI\%ncurses\fP use the descriptor +in \fI\%TERMINAL\fP +for terminal I/O modes, +e.g., +\fB\%def_shell_mode\fP(3NCURSES), +\fB\%def_prog_mode\fP(3NCURSES). +SVr4 curses uses the descriptor in \fISCREEN\fP. +.SS "Unset \fITERM\fP Variable" +If the \fITERM\fP variable is missing or empty, \fBinitscr\fP uses the +value \*(``unknown\*('', +which normally corresponds to a terminal entry with the \fIgeneric\fP +(\fIgn\fP) capability. +Generic entries are detected by \fB\%setupterm\fP(3NCURSES) +and cannot be used for full-screen operation. +Other implementations may handle +a missing/empty \fITERM\fP variable differently. +.SS "Signal Handlers" +Quoting from X/Open Curses Issue 7, section 3.1.1: +.RS 5 +.PP +Curses implementations may provide for special handling of the +\%SIGINT, +\%SIGQUIT, +and \%SIGTSTP signals if their disposition is \%SIG_DFL at the time +.I \%initscr +is called.\|.\|. +.PP +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. +.PP +None of the Curses functions are required to be safe +with respect to signals.\|.\|. +.RE +.PP +This implementation establishes signal handlers during initialization, +e.g., \fBinitscr\fP or \fBnewterm\fP. +Applications which must handle these signals should set up the corresponding +handlers \fIafter\fP initializing the library: +.TP 5 +.B SIGINT +The handler \fIattempts\fP to clean up the screen on exit. +Although it \fIusually\fP works as expected, there are limitations: +.RS 5 +.bP +Walking the \fISCREEN\fP list is unsafe, since all list management +is done without any signal blocking. +.bP +On systems which have \fBREENTRANT\fP turned on, \fBset_term\fP uses +functions which could deadlock or misbehave in other ways. +.bP +\fBendwin\fP calls other functions, +many of which use \fI\%stdio\fP(3) or other library functions which are +clearly unsafe. +.RE +.TP 5 +.B SIGTERM +This uses the same handler as \fBSIGINT\fP, with the same limitations. +It is not mentioned in X/Open Curses, but is more suitable for this +purpose than \fBSIGQUIT\fP (which is used in debugging). +.TP 5 +.B SIGTSTP +This handles the \fIstop\fP signal, used in job control. +When resuming the process, this implementation discards pending +input with \fB\%flushinp\fP(3NCURSES), and repaints the screen +assuming that it has been completely altered. +It also updates the saved terminal modes with +\fB\%def_shell_mode\fP(3NCURSES). +.TP 5 +.B 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 \fB\%wgetch\fP(3NCURSES). +If \fBkeypad\fP has been enabled for the corresponding window, +\fBwgetch\fP returns the key symbol \fBKEY_RESIZE\fP. +At the same time, \fBwgetch\fP calls \fBresizeterm\fP to adjust the +standard screen \fBstdscr\fP, +and update other data such as \fBLINES\fP and \fBCOLS\fP. +.SH SEE ALSO +\fB\%ncurses\fP(3NCURSES), +\fB\%kernel\fP(3NCURSES), +\fB\%refresh\fP(3NCURSES), +\fB\%slk\fP(3NCURSES), +\fB\%terminfo\fP(3NCURSES), +\fB\%util\fP(3NCURSES), +\fB\%curses_variables\fP(3NCURSES) |