X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_initscr.3x;h=00366177df527212366e55010d85fd11d9b014ca;hp=ea41729ed7dfabc34bb6d0f16b9f5ba5b8863990;hb=74433bcf4f6fe40862a28f3c00edaedcd5054b01;hpb=46722468f47c2b77b3987729b4bcf2321cccfd01 diff --git a/man/curs_initscr.3x b/man/curs_initscr.3x index ea41729e..00366177 100644 --- a/man/curs_initscr.3x +++ b/man/curs_initscr.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. * +.\" Copyright 2018-2020,2021 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,99 +27,234 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_initscr.3x,v 1.11 2002/07/20 14:51:04 tom Exp $ +.\" $Id: curs_initscr.3x,v 1.36 2021/12/25 21:41:58 tom Exp $ .TH curs_initscr 3X "" +.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\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 - -\fBWINDOW *initscr(void);\fR +\fB#include \fP +.sp +\fBWINDOW *initscr(void);\fP .br -\fBint endwin(void);\fR +\fBint endwin(void);\fP +.sp +\fBbool isendwin(void);\fP +.sp +\fBSCREEN *newterm(const char *\fP\fItype\fP\fB, FILE *\fP\fIoutfd\fP\fB, FILE *\fP\fIinfd\fP\fB);\fP .br -\fBbool isendwin(void);\fR +\fBSCREEN *set_term(SCREEN *\fP\fInew\fP\fB);\fP .br -\fBSCREEN *newterm(char *type, FILE *outfd, FILE *infd);\fR -.br -\fBSCREEN *set_term(SCREEN *new);\fR -.br -\fBvoid delscreen(SCREEN* sp);\fR +\fBvoid delscreen(SCREEN* \fP\fIsp\fP\fB);\fP .br .SH DESCRIPTION -\fBinitscr\fR is normally the first \fBcurses\fR routine to call when -initializing a program. A few special routines sometimes need to be -called before it; these are \fBslk_init\fR, \fBfilter\fR, \fBripoffline\fR, -\fBuse_env\fR. For multiple-terminal applications, \fBnewterm\fR may be -called before \fBinitscr\fR. - -The initscr code determines the terminal type and initializes all \fBcurses\fR -data structures. \fBinitscr\fR also causes the first call to \fBrefresh\fR to -clear the screen. If errors occur, \fBinitscr\fR writes an appropriate error -message to standard error and exits; otherwise, a pointer is returned to -\fBstdscr\fR. - -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 needs to -inspect capabilities, so it can continue to run in a line-oriented mode if the +.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 \fBslk_init\fP(3X), \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 \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\fP. +.SS newterm +.PP +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 -as a reference to that terminal. The arguments are the \fItype\fR of the -terminal to be used in place of \fB$TERM\fR, a file pointer for output to the -terminal, and another file pointer for input from the terminal (if \fItype\fR -is \fBNULL\fR, \fB$TERM\fR will be used). 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. - -A program should always call \fBendwin\fR before exiting or escaping from -\fBcurses\fR mode temporarily. This routine restores tty modes, moves the -cursor to the lower left-hand corner of the screen and resets the terminal into -the proper non-visual mode. Calling \fBrefresh\fR or \fBdoupdate\fR after a +\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\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\fP parameter is \fBNULL\fP, \fB$TERM\fP will be used. +.SS endwin +.PP +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 \fBcurs_set\fP(3X)), +.bP +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\fP(3X) or \fBdoupdate\fP(3X) after a temporary escape causes the program to resume visual mode. - -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 \fBset_term\fR routine is used to switch between different -terminals. The screen reference \fBnew\fR becomes the new current -terminal. The previous terminal is returned by the routine. This is -the only routine which manipulates \fBSCREEN\fR pointers; all other -routines affect only the current terminal. - -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. +.SS isendwin +.PP +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\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; +all other routines affect only the current terminal. +.SS delscreen +.PP +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. - -Routines that return pointers always return \fBNULL\fR on error. -.SH NOTES -Note that \fBinitscr\fR and \fBnewterm\fR may be macros. +.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 the terminal was not initialized. +.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 are described in the XSI Curses standard, Issue 4. It -specifies that portable applications must not call \fBinitscr\fR more than -once. - +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 \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 +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. +.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. +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 +.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... +.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 +.PP +\fINone of the Curses functions are required to be safe +with respect to signals \fP... +.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 cleanup 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 +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. +.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 \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 \fBcurs_kernel\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)). +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\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_refresh\fR(3X), -\fBcurs_slk\fR(3X), \fBcurs_util\fR(3X) -.\"# -.\"# The following sets edit modes for GNU EMACS -.\"# Local Variables: -.\"# mode:nroff -.\"# fill-column:79 -.\"# End: +\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).