X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_initscr.3x;h=15f4e8b966756cc9830f877090f08d3dc7d3ac42;hb=bd2d9c5734d2c66abe0b2ddd766695b200c154fe;hp=bd2b674988c21965d4fe03b5540e2ab9201728cd;hpb=d79ff7b4d5f5ac63e7d9d7e76706d95a1ddb243c;p=ncurses.git diff --git a/man/curs_initscr.3x b/man/curs_initscr.3x index bd2b6749..15f4e8b9 100644 --- a/man/curs_initscr.3x +++ b/man/curs_initscr.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" 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 * @@ -27,41 +27,44 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_initscr.3x,v 1.44 2023/07/01 14:25:06 tom Exp $ -.TH curs_initscr 3X 2023-07-01 "ncurses 6.4" "Library calls" +.\" $Id: curs_initscr.3x,v 1.62 2024/02/24 20:03:50 tom Exp $ +.TH curs_initscr 3X 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 .. -.ie \n(.g .ds `` \(lq -.el .ds `` `` -.ie \n(.g .ds '' \(rq -.el .ds '' '' -.na -.hy 0 .SH NAME -\fBinitscr\fP, -\fBnewterm\fP, -\fBendwin\fP, -\fBisendwin\fP, -\fBset_term\fP, -\fBdelscreen\fP \- \fBcurses\fP screen initialization and manipulation routines -.ad -.hy +\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 -\fB#include \fP -.sp -\fBWINDOW *initscr(void);\fP -.br -\fBint endwin(void);\fP -.sp -\fBbool isendwin(void);\fP -.sp -\fBSCREEN *newterm(const char *\fItype\fB, FILE *\fIoutf\fB, FILE *\fIinf\fB);\fR -.br -\fBSCREEN *set_term(SCREEN *\fInew\fB);\fR -.br -\fBvoid delscreen(SCREEN* \fIsp\fB);\fR +.nf +\fB#include +.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 @@ -88,7 +91,7 @@ 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 \fBSCREEN *\fP which should be saved +It returns a variable of type \fISCREEN *\fP which should be saved as a reference to that terminal. \fBnewterm\fP's arguments are .bP @@ -101,8 +104,8 @@ an input stream connected to the terminal 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 \fBsetupterm\fP(3X), -which returns a pointer to a \fBTERMINAL\fP structure. -\fBnewterm\fP's return value holds a pointer to the \fBTERMINAL\fP structure. +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. @@ -135,14 +138,14 @@ and \fBFALSE\fP otherwise. 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 \fBSCREEN\fP pointers; +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 -\fBSCREEN\fP data structure. +\fISCREEN\fP data structure. The \fBendwin\fP routine does not do this, so \fBdelscreen\fP should be called after \fBendwin\fP if a -particular \fBSCREEN\fP is no longer needed. +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. @@ -152,7 +155,15 @@ Routines that return pointers always return \fBNULL\fP on error. X/Open defines no error conditions. In this implementation .bP -\fBendwin\fP returns an error if the terminal was not initialized. +\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 +\fBreset_shell_mode\fP(3X) returns an error. +.RE .bP \fBnewterm\fP returns an error if it cannot allocate the data structures for the screen, @@ -170,7 +181,7 @@ 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 \fBrefresh\fP (see curs_refresh(3X)) +using \fB\%refresh\fP(3X) to restore the screen after \fBendwin\fP. .bP This implementation allows using \fBinitscr\fP after \fBendwin\fP. @@ -182,32 +193,32 @@ in XSI Curses. .PP Calling \fBendwin\fP does not dispose of the memory allocated in \fBinitscr\fP or \fBnewterm\fP. -Deleting a \fBSCREEN\fP provides a way to do this: +Deleting a \fISCREEN\fP provides a way to do this: .bP -X/Open Curses does not say what happens to \fBWINDOW\fPs when \fBdelscreen\fP -\*(``frees storage associated with the \fBSCREEN\fP\*('' +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 \fBSCREEN\fP +adding that it should be called after \fBendwin\fP if a \fISCREEN\fP is no longer needed. .bP -However, \fBWINDOW\fPs are implicitly associated with a \fBSCREEN\fP. +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 \fBWINDOW\fP structures +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), ncurses has maintained a list of all windows -for each screen, +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 ncurses in 2001. +NetBSD copied this feature of \fI\%ncurses\fP in 2001. PDCurses follows the SVr4 model, -deleting only the standard \fBWINDOW\fP structures. -.SS High-level versus low-level +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, \fBSCREEN\fP (returned by \fBnewterm\fP) and -\fBTERMINAL\fP (returned by \fBsetupterm\fP(3X)) hold file descriptors for +For example, \fISCREEN\fP (returned by \fBnewterm\fP) and +\fI\%TERMINAL\fP (returned by \fBsetupterm\fP(3X)) hold file descriptors for the output stream. If an application switches screens using \fBset_term\fR, or switches terminals using \fBset_curterm\fP(3X), @@ -216,42 +227,43 @@ behavior depending on which structure holds the corresponding descriptor. .PP For example .bP -NetBSD's \fBbaudrate\fP(3X) function uses the descriptor in \fBTERMINAL\fP. -\fBncurses\fP and SVr4 use the descriptor in \fBSCREEN\fP. +NetBSD's \fBbaudrate\fP(3X) function uses the descriptor in \fI\%TERMINAL\fP. +\fI\%ncurses\fP and SVr4 use the descriptor in \fISCREEN\fP. .bP -NetBSD and \fBncurses\fP use the descriptor in \fBTERMINAL\fP for terminal I/O modes, +NetBSD and \fI\%ncurses\fP use the descriptor +in \fI\%TERMINAL\fP +for terminal I/O modes, e.g., \fBdef_shell_mode\fP(3X), \fBdef_prog_mode\fP(3X). -SVr4 curses uses the descriptor in \fBSCREEN\fP. -.SS Unset TERM Variable -If the TERM variable is missing or empty, \fBinitscr\fP uses the +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 \fBsetupterm\fP(3X) and cannot be used for full-screen operation. -Other implementations may handle a missing/empty TERM variable differently. -.SS Signal Handlers -Quoting from X/Open Curses, section 3.1.1: +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 -.hy 0 .PP -.I Curses implementations may provide for special handling of the -.I \fBSIGINT\fP, -.I \fBSIGQUIT\fP and -.I \fBSIGTSTP\fP signals -.I if their disposition is \fBSIG_DFL\fP at the time -\fBinitscr\fI is called \fR... +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 -.I Any special handling for these signals may remain in effect for the -.I life of the process or until the process changes the disposition of -.I the signal. +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 -.I None of the Curses functions are required to be safe -.I with respect to signals \fP... +None of the Curses functions are required to be safe +with respect to signals.\|.\|. .RE -.hy .PP This implementation establishes signal handlers during initialization, e.g., \fBinitscr\fP or \fBnewterm\fP. @@ -259,18 +271,19 @@ 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 cleanup the screen on exit. +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 \fBSCREEN\fP list is unsafe, since all list management +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 stdio or -other library functions which are clearly unsafe. +\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 @@ -281,26 +294,26 @@ purpose than \fBSIGQUIT\fP (which is used in debugging). .B SIGTSTP This handles the \fIstop\fP signal, used in job control. When resuming the process, this implementation discards pending -input with \fBflushinput\fP (see curs_util(3X)), and repaints the screen +input with \fB\%flushinp\fP(3X), and repaints the screen assuming that it has been completely altered. -It also updates the saved terminal modes with \fBdef_shell_mode\fP -(see \fBcurs_kernel\fP(3X)). +It also updates the saved terminal modes with +\fB\%def_shell_mode\fP(3X). .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 \fBwgetch\fP (see curs_getch(3X)). +which is later tested in \fB\%wgetch\fP(3X). 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 -\fBcurses\fP(3X), -\fBcurs_kernel\fP(3X), -\fBcurs_refresh\fP(3X), -\fBcurs_slk\fP(3X), -\fBcurs_terminfo\fP(3X), -\fBcurs_util\fP(3X), -\fBcurs_variables\fP(3X). +\fB\%curses\fP(3X), +\fB\%curs_kernel\fP(3X), +\fB\%curs_refresh\fP(3X), +\fB\%curs_slk\fP(3X), +\fB\%curs_terminfo\fP(3X), +\fB\%curs_util\fP(3X), +\fB\%curs_variables\fP(3X)