-The \fBunctrl\fR macro expands to a character string which is a printable
-representation of the character \fIc\fR. Control characters are displayed in
-the \fB^\fR\fIX\fR notation. Printing characters are displayed as is.
-
-The \fBkeyname\fR routine returns a character string corresponding to
-the key \fIc\fR.
-
-The \fBfilter\fR routine, if used, must be called before \fBinitscr\fR or
-\fBnewterm\fR are called. The effect is that, during those calls, \fBLINES\fR
-is set to 1; the capabilities \fBclear\fR, \fBcup\fR, \fBcud\fR, \fBcud1\fR,
-\fBcuu1\fR, \fBcuu\fR, \fBvpa\fR are disabled; and the \fBhome\fR string is
-set to the value of \fBcr\fR.
-
-The \fBuse_env\fR routine, if used, is called before \fBinitscr\fR or
-\fBnewterm\fR are called. When called with \fBFALSE\fR as an
-argument, the values of \fBlines\fR and \fBcolumns\fR specified in the
-\fIterminfo\fR database will be used, even if environment variables
-\fBLINES\fR and \fBCOLUMNS\fR (used by default) are set, or if
-\fBcurses\fR is running in a window (in which case default behavior
-would be to use the window size if \fBLINES\fR and \fBCOLUMNS\fR are
-not set).
-
-The \fBputwin\fR routine writes all data associated with window \fIwin\fR into
-the file to which \fIfilep\fR points. This information can be later retrieved
-using the \fBgetwin\fR function.
-
-The \fBgetwin\fR routine reads window related data stored in the file by
-\fBputwin\fR. The routine then creates and initializes a new window using that
-data. It returns a pointer to the new window.
-
-The \fBdelay_output\fR routine inserts an \fIms\fR millisecond pause
-in output. This routine should not be used extensively because
-padding characters are used rather than a CPU pause.
-
-The \fBflushinp\fR routine throws away any typeahead that has been typed by the
+.SS unctrl
+The \fBunctrl\fP routine returns a character string which is a printable
+representation of the character \fIc\fP:
+.bP
+Printable characters are displayed as themselves,
+e.g., a one-character string containing the key.
+.bP
+Control characters are displayed in the \fB^\fIX\fR notation.
+.bP
+Printing characters are displayed as is.
+.bP
+DEL (character 127) is displayed as \fB^?\fP.
+.bP
+Values above 128 are either meta characters
+(if the screen has not been initialized,
+or if \fBmeta\fP(3X) has been called with a \fBTRUE\fP parameter),
+shown in the \fBM\-\fIX\fR notation,
+or are displayed as themselves.
+In the latter case, the values may not be printable;
+this follows the X/Open specification.
+.PP
+The corresponding \fBwunctrl\fP returns a printable representation of
+a complex character \fIc\fP.
+.PP
+In both \fBunctrl\fP and \fBwunctrl\fP the attributes and color associated
+with the character parameter are ignored.
+.SS keyname/key_name
+The \fBkeyname\fP routine returns a character string
+corresponding to the key \fIc\fP.
+Key codes are different from character codes.
+.bP
+Key codes below 256 are characters.
+They are displayed using \fBunctrl\fP.
+.bP
+Values above 256 may be the codes for function keys.
+The function key name is displayed.
+.bP
+Otherwise (if there is no corresponding name and the key is not a character)
+the function returns null, to denote an error.
+X/Open also lists an \*(``UNKNOWN KEY\*('' return value,
+which some implementations return rather than null.
+.LP
+The corresponding \fBkey_name\fP returns
+a multibyte character string corresponding
+to the wide-character value \fIw\fP.
+The two functions (\fBkeyname\fP and \fBkey_name\fP)
+do not return the same set of strings:
+.bP
+\fBkeyname\fP returns null where \fBkey_name\fP would display a meta character.
+.bP
+\fBkey_name\fP does not return the name of a function key.
+.SS filter/nofilter
+The \fBfilter\fP routine, if used, must be called before \fBinitscr\fP or
+\fBnewterm\fP are called.
+Calling \fBfilter\fP causes these changes in initialization:
+.bP
+\fBLINES\fP is set to 1;
+.bP
+the capabilities
+\fBclear\fP,
+\fBcud1\fP,
+\fBcud\fP,
+\fBcup\fP,
+\fBcuu1\fP,
+\fBcuu\fP,
+\fBvpa\fP
+are disabled;
+.bP
+the capability \fBed\fP is disabled if \fBbce\fP is set;
+.bP
+and the \fBhome\fP string is set to the value of \fBcr\fP.
+.PP
+The \fBnofilter\fP routine cancels the effect of a preceding \fBfilter\fP
+call.
+That allows the caller to initialize a screen on a different device,
+using a different value of \fB$TERM\fP.
+The limitation arises because the \fBfilter\fP routine modifies the
+in-memory copy of the terminal information.
+.SS use_env
+The \fBuse_env\fP routine, if used,
+should be called before \fBinitscr\fP or
+\fBnewterm\fP are called
+(because those compute the screen size).
+It modifies the way \fI\%ncurses\fP treats environment variables
+when determining the screen size.
+.bP
+Normally \fI\%ncurses\fP looks first at the terminal database for the
+screen size.
+.IP
+If \fBuse_env\fP was called with \fBFALSE\fP for parameter,
+it stops here unless
+\fBuse_tioctl\fP was also called with \fBTRUE\fP for parameter.
+.bP
+Then it asks for the screen size via operating system calls.
+If successful,
+it overrides the values from the terminal database.
+.bP
+Finally (unless \fBuse_env\fP was called with \fBFALSE\fP parameter),
+\fI\%ncurses\fP examines the \fILINES\fP or \fI\%COLUMNS\fP environment
+variables,
+using a value in those to override the results
+from the operating system or terminal database.
+.IP
+\fI\%curses\fP also updates the screen size in response to
+\fBSIGWINCH\fP,
+unless overridden by the \fILINES\fP or \fI\%COLUMNS\fP environment
+variables,
+.SS use_tioctl
+The \fBuse_tioctl\fP routine, if used,
+should be called before \fBinitscr\fP or \fBnewterm\fP are called
+(because those compute the screen size).
+After \fBuse_tioctl\fP is called with \fBTRUE\fP as an argument,
+\fI\%ncurses\fP modifies the last step in its computation
+of screen size as follows:
+.bP
+checks if the \fILINES\fP and \fI\%COLUMNS\fP environment variables
+are set to a number greater than zero.
+.bP
+for each, \fI\%ncurses\fP updates the corresponding environment variable
+with the value that it has obtained via operating system call
+or from the terminal database.
+.bP
+\fI\%ncurses\fP re-fetches the value of the environment variables so
+that it is still the environment variables which set the screen size.
+.PP
+The \fB\%use_env\fP and \fB\%use_tioctl\fP routines combine as follows.
+.IP
+.TS
+lB lB lB
+lB lB lx.
+use_env use_tioctl Summary
+_
+TRUE FALSE T{
+This is the default behavior.
+\fI\%ncurses\fP uses operating system calls
+unless overridden by \fILINES\fP or \fI\%COLUMNS\fP environment
+variables;
+default.
+T}
+TRUE TRUE T{
+\fI\%ncurses\fP updates \fILINES\fP and \fI\%COLUMNS\fP based on
+operating system calls.
+T}
+FALSE TRUE T{
+\fI\%ncurses\fP ignores \fILINES\fP and \fI\%COLUMNS\fP,
+using operating system calls to obtain size.
+T}
+.TE
+.SS putwin/getwin
+The \fBputwin\fP routine writes all data associated
+with window (or pad) \fIwin\fP into
+the file to which \fIfilep\fP points.
+This information can be later retrieved
+using the \fBgetwin\fP function.
+.PP
+The \fBgetwin\fP routine reads window related data stored in the file by
+\fBputwin\fP.
+The routine then creates and initializes a new window using that
+data.
+It returns a pointer to the new window.
+There are a few caveats:
+.bP
+the data written is a copy of the \fI\%WINDOW\fP structure,
+and its associated character cells.
+The format differs between the wide-character (\fI\%ncursesw\fP) and
+non-wide (\fI\%ncurses\fP) libraries.
+You can transfer data between the two, however.
+.bP
+the retrieved window is always created as a top-level window (or pad),
+rather than a subwindow.
+.bP
+the window's character cells contain the color pair \fIvalue\fP,
+but not the actual color \fInumbers\fP.
+If cells in the retrieved window use color pairs which have not been
+created in the application using \fBinit_pair\fP,
+they will not be colored when the window is refreshed.
+.SS delay_output
+The \fBdelay_output\fP routine inserts an \fIms\fP millisecond pause
+in output.
+Employ this function judiciously when terminal output uses padding,
+because \fI\%ncurses\fP transmits null characters
+(consuming CPU and I/O resources)
+instead of sleeping and requesting resumption from the operating system.
+Padding is used unless:
+.bP
+the terminal description has \fBnpc\fP (\fBno_pad_char\fP) capability, or
+.bP
+the environment variable \fB\%NCURSES_NO_PADDING\fP is set.
+.PP
+If padding is not in use,
+\fI\%ncurses\fP uses \fBnapms\fP to perform the delay.
+If the value of \fIms\fP exceeds 30,000
+(thirty seconds),
+it is capped at that value.
+.SS flushinp
+The \fBflushinp\fP routine throws away any typeahead that has been typed by the
projects / ncurses.git / blobdiff