X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_initscr.3x;h=d08043dc192b7dc6f7a759aa1058bd4e567ebdd2;hp=0582ea2df680e375c261c24c0bfffdfbff2eae0a;hb=6b4f5830b7910188b532d661f79775306715f67e;hpb=32f9f5f12cd9159261f9db228461049e8c770404 diff --git a/man/curs_initscr.3x b/man/curs_initscr.3x index 0582ea2d..d08043dc 100644 --- a/man/curs_initscr.3x +++ b/man/curs_initscr.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2014,2015 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2017,2018 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,10 +26,11 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_initscr.3x,v 1.23 2015/07/16 09:23:42 tom Exp $ +.\" $Id: curs_initscr.3x,v 1.31 2018/07/28 22:15:59 tom Exp $ .TH curs_initscr 3X "" .de bP -.IP \(bu 4 +.ie n .IP \(bu 4 +.el .IP \(bu 2 .. .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -55,25 +56,26 @@ .br \fBbool isendwin(void);\fR .br -\fBSCREEN *newterm(char *type, FILE *outfd, FILE *infd);\fR +\fBSCREEN *newterm(const char *\fP\fItype\fP\fB, FILE *\fP\fIoutfd\fP\fB, FILE *\fP\fIinfd\fP\fB);\fR .br -\fBSCREEN *set_term(SCREEN *new);\fR +\fBSCREEN *set_term(SCREEN *\fP\fInew\fP\fB);\fR .br -\fBvoid delscreen(SCREEN* sp);\fR +\fBvoid delscreen(SCREEN* \fP\fIsp\fP\fB);\fR .br .SH DESCRIPTION .SS initscr \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, +these are \fBslk_init\fR(3X), \fBfilter\fR, \fBripoffline\fR, \fBuse_env\fR. For multiple-terminal applications, \fBnewterm\fR may be called before \fBinitscr\fR. .PP 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. +\fBinitscr\fR also causes the first call to \fBrefresh\fR(3X) +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. @@ -108,14 +110,19 @@ A program should always call \fBendwin\fR before exiting or escaping from \fBcurses\fR mode temporarily. This routine .bP -restores tty modes, +resets colors to correspond with the default color pair 0, .bP -moves the cursor to the lower left-hand corner of the screen and +moves the cursor to the lower left-hand corner of the screen, .bP -resets the terminal into -the proper non-visual mode. +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\fR or \fBdoupdate\fR after a +Calling \fBrefresh\fR(3X) or \fBdoupdate\fR(3X) after a temporary escape causes the program to resume visual mode. .SS isendwin .PP @@ -155,8 +162,6 @@ i.e., .bP \fBset_term\fP returns no error. -.SH NOTES -Note that \fBinitscr\fR and \fBnewterm\fR may be macros. .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. @@ -165,7 +170,8 @@ X/Open specifies that portable applications must not call \fBinitscr\fR 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 @@ -179,23 +185,25 @@ 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 .PP -\fICurses implementations may provide for special handling of the SIGINT, -SIGQUIT and SIGTSTP signals if their disposition is SIG_DFL at the time -\fBinitscr()\fP is called \fP... +\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... +\fINone of the Curses functions are required to be safe +with respect to signals \fP... .RE .PP This implementation establishes signal handlers during initialization, @@ -228,10 +236,11 @@ 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\fR(3X)). .TP 5 .B SIGWINCH -This handles the window-size changes which were initially ignored in +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)).