X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_initscr.3x;h=5e17ead0a659bd23838095397ea0e3b03bb0a443;hb=3183ac61c6bf0a75ee65dc8cbebf54f7c143df46;hp=f692535f7ad99331f46b4e1cfdd8561ef9896a51;hpb=06078d3fa68db669ed37178c01873546b4b28745;p=ncurses.git diff --git a/man/curs_initscr.3x b/man/curs_initscr.3x index f692535f..5e17ead0 100644 --- a/man/curs_initscr.3x +++ b/man/curs_initscr.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2016,2017 Free Software Foundation, Inc. * +.\" Copyright 2018-2021,2022 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 * @@ -26,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_initscr.3x,v 1.29 2017/11/18 23:47:37 tom Exp $ +.\" $Id: curs_initscr.3x,v 1.39 2022/07/24 15:46:49 tom Exp $ .TH curs_initscr 3X "" .de bP .ie n .IP \(bu 4 @@ -39,74 +40,75 @@ .na .hy 0 .SH NAME -\fBinitscr\fR, -\fBnewterm\fR, -\fBendwin\fR, -\fBisendwin\fR, -\fBset_term\fR, -\fBdelscreen\fR \- \fBcurses\fR screen initialization and manipulation routines +\fBinitscr\fP, +\fBnewterm\fP, +\fBendwin\fP, +\fBisendwin\fP, +\fBset_term\fP, +\fBdelscreen\fP \- \fBcurses\fP screen initialization and manipulation routines .ad .hy .SH SYNOPSIS -\fB#include \fR +\fB#include \fP .sp -\fBWINDOW *initscr(void);\fR +\fBWINDOW *initscr(void);\fP .br -\fBint endwin(void);\fR -.br -\fBbool isendwin(void);\fR -.br -\fBSCREEN *newterm(char *\fP\fItype\fP\fB, FILE *\fP\fIoutfd\fP\fB, FILE *\fP\fIinfd\fP\fB);\fR +\fBint endwin(void);\fP +.sp +\fBbool isendwin(void);\fP +.sp +\fBSCREEN *newterm(const char *\fItype\fB, FILE *\fIoutfd\fB, FILE *\fIinfd\fB);\fR .br -\fBSCREEN *set_term(SCREEN *\fP\fInew\fP\fB);\fR +\fBSCREEN *set_term(SCREEN *\fInew\fB);\fR .br -\fBvoid delscreen(SCREEN* \fP\fIsp\fP\fB);\fR +\fBvoid delscreen(SCREEN* \fIsp\fB);\fR .br .SH DESCRIPTION .SS initscr -\fBinitscr\fR is normally the first \fBcurses\fR routine to call when +\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 \fBslk_init\fR(3X), \fBfilter\fR, \fBripoffline\fR, -\fBuse_env\fR. +these are \fBslk_init\fP(3X), \fBfilter\fP, \fBripoffline\fP, +\fBuse_env\fP. For multiple-terminal applications, -\fBnewterm\fR may be called before \fBinitscr\fR. +\fBnewterm\fP may be called before \fBinitscr\fP. .PP -The initscr code determines the terminal type and initializes all \fBcurses\fR +The initscr code determines the terminal type and initializes all \fBcurses\fP data structures. -\fBinitscr\fR also causes the first call to \fBrefresh\fR(3X) to clear the screen. -If errors occur, \fBinitscr\fR writes an appropriate error +\fBinitscr\fP also causes the first call to \fBrefresh\fP(3X) +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\fR. +otherwise, a pointer is returned to \fBstdscr\fP. .SS newterm .PP -A program that outputs to more than one terminal should use the \fBnewterm\fR -routine for each terminal instead of \fBinitscr\fR. +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\fR. -The routine \fBnewterm\fR should be called once for each terminal. -It returns a variable of type \fBSCREEN *\fR which should be saved +\fBnewterm\fP. +The routine \fBnewterm\fP should be called once for each terminal. +It returns a variable of type \fBSCREEN *\fP which should be saved as a reference to that terminal. \fBnewterm\fP's arguments are .bP -the \fItype\fR of the terminal to be used in place of \fB$TERM\fR, +the \fItype\fP of the terminal to be used in place of \fB$TERM\fP, .bP a file pointer for output to the terminal, and .bP another file pointer for input from the terminal .PP -If the \fItype\fR parameter is \fBNULL\fR, \fB$TERM\fR will be used. +If the \fItype\fP parameter is \fBNULL\fP, \fB$TERM\fP will be used. .SS endwin .PP The program must also call -\fBendwin\fR for each terminal being used before exiting from \fBcurses\fR. -If \fBnewterm\fR is called more than once for the same terminal, the first -terminal referred to must be the last one for which \fBendwin\fR is called. +\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\fR before exiting or escaping from -\fBcurses\fR mode temporarily. +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, @@ -121,32 +123,32 @@ stops cursor-addressing mode using the \fIexit_ca_mode\fP terminal capability, .bP restores tty modes (see \fBreset_shell_mode\fP(3X)). .PP -Calling \fBrefresh\fR(3X) or \fBdoupdate\fR(3X) after a +Calling \fBrefresh\fP(3X) or \fBdoupdate\fP(3X) after a temporary escape causes the program to resume visual mode. .SS isendwin .PP -The \fBisendwin\fR routine returns \fBTRUE\fR if \fBendwin\fR has been -called without any subsequent calls to \fBwrefresh\fR, -and \fBFALSE\fR otherwise. +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 .PP -The \fBset_term\fR routine is used to switch between different terminals. -The screen reference \fBnew\fR becomes the new current terminal. +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\fR pointers; +This is the only routine which manipulates \fBSCREEN\fP pointers; all other routines affect only the current terminal. .SS delscreen .PP -The \fBdelscreen\fR routine frees storage associated with the -\fBSCREEN\fR data structure. -The \fBendwin\fR routine does not do -this, so \fBdelscreen\fR should be called after \fBendwin\fR if a -particular \fBSCREEN\fR is no longer needed. +The \fBdelscreen\fP routine frees storage associated with the +\fBSCREEN\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. .SH RETURN VALUE -\fBendwin\fR returns the integer \fBERR\fR upon failure and \fBOK\fR +\fBendwin\fP returns the integer \fBERR\fP upon failure and \fBOK\fP upon successful completion. .PP -Routines that return pointers always return \fBNULL\fR on error. +Routines that return pointers always return \fBNULL\fP on error. .PP X/Open defines no error conditions. In this implementation @@ -166,42 +168,73 @@ 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\fR more than once: +call \fBinitscr\fP more than once: .bP The portable way to use \fBinitscr\fP is once only, -using \fBrefresh\fP (see curs_refresh(3X)) to restore the screen after \fBendwin\fP. +using \fBrefresh\fP (see curs_refresh(3X)) +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, may have returned a null pointer -from \fBinitscr\fR when an error is detected, rather than exiting. -It is safe but redundant to check the return value of \fBinitscr\fR +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 \fBSCREEN\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\*('' +nor does the SVr4 documentation help, +adding that it should be called after \fBendwin\fP if a \fBSCREEN\fP +is no longer needed. +.bP +However, \fBWINDOW\fPs are implicitly associated with a \fBSCREEN\fP. +so that it is reasonable to expect \fBdelscreen\fP to deal with these. +.bP +SVr4 curses deletes the standard \fBWINDOW\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, +using that information to delete those windows when \fBdelscreen\fP is called. +.bP +NetBSD copied this feature of ncurses in 2001. +PDCurses follows the SVr4 model, +deleting only the standard \fBWINDOW\fP structures. .SS Unset TERM Variable .PP If the TERM 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 (see curs_terminfo(3X)) and cannot be -used for full-screen operation. +Generic entries are detected by \fBsetupterm\fP +(see curs_terminfo(3X)) and cannot be used for full-screen operation. Other implementations may handle a missing/empty TERM variable differently. .SS Signal Handlers .PP Quoting from X/Open Curses, section 3.1.1: .RS 5 +.hy 0 .PP -\fICurses implementations may provide for special handling of the \fBSIGINT\fP, -\fBSIGQUIT\fP and \fBSIGTSTP\fP signals -if their disposition is \fBSIG_DFL\fP at the time -\fBinitscr\fP is called \fP... +.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... .PP -\fIAny 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.\fP +.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. .PP -\fINone of the Curses functions are required to be safe with respect to signals \fP... +.I None of the Curses functions are required to be safe +.I with respect to signals \fP... .RE +.hy .PP This implementation establishes signal handlers during initialization, e.g., \fBinitscr\fP or \fBnewterm\fP. @@ -233,7 +266,8 @@ 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 assuming that it has been completely altered. -It also updates the saved terminal modes with \fBdef_shell_mode\fP (see curs_kernel(3X)). +It also updates the saved terminal modes with \fBdef_shell_mode\fP +(see \fBcurs_kernel\fP(3X)). .TP 5 .B SIGWINCH This handles the window-size changes which were ignored in @@ -246,10 +280,10 @@ 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\fR(3X), -\fBcurs_kernel\fR(3X), -\fBcurs_refresh\fR(3X), -\fBcurs_slk\fR(3X), -\fBcurs_terminfo\fR(3X), -\fBcurs_util\fR(3X), -\fBcurs_variables\fR(3X). +\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).