X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_util.3x;h=4d027dbade11aa8337dce634df4ab57bd684c285;hp=a0c05fe427e2da0895c7c0b3ffedf294c0a04acb;hb=02f02dcd4464143580e783ae32c822d8eb8cdcbf;hpb=aefc1659d732acf7e62c0c78a443d6d8352a3c6e

diff --git a/man/curs_util.3x b/man/curs_util.3x
index a0c05fe4..4d027dba 100644
--- a/man/curs_util.3x
+++ b/man/curs_util.3x
@@ -27,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_util.3x,v 1.38 2015/03/07 23:33:38 tom Exp $
+.\" $Id: curs_util.3x,v 1.43 2015/06/06 23:36:27 tom Exp $
 .TH curs_util 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
@@ -81,16 +81,18 @@
 \fBint flushinp(void);\fR
 .br
 .SH DESCRIPTION
+.SS unctrl
+.PP
 The \fBunctrl\fR routine returns a character string which is a printable
 representation of the character \fIc\fR, ignoring attributes.
 Control characters are displayed in the \fB^\fR\fIX\fR notation.
 Printing characters are displayed as is.
 The corresponding \fBwunctrl\fR returns a printable representation of
 a wide character.
+.SS keyname/key_name
 .PP
 The \fBkeyname\fR routine returns a character string
 corresponding to the key \fIc\fR:
-.RS 3
 .bP
 Printable characters are displayed as themselves,
 e.g., a one-character string containing the key.
@@ -101,7 +103,7 @@ 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 has been called with a TRUE parameter),
+or if \fBmeta\fP has been called with a \fBTRUE\fP parameter),
 shown in the \fBM\-\fR\fIX\fR notation,
 or are displayed as themselves.
 In the latter case, the values may not be printable;
@@ -113,12 +115,12 @@ Otherwise (if there is no corresponding name) the function returns null,
 to denote an error.
 X/Open also lists an "UNKNOWN KEY" return value, which some implementations
 return rather than null.
-.RE
 .LP
 The corresponding \fBkey_name\fR returns a character string corresponding
 to the wide-character value \fIw\fR.
 The two functions do not return the same set of strings;
 the latter returns null where the former would display a meta character.
+.SS filter/nofilter
 .PP
 The \fBfilter\fR routine, if used, must be called before \fBinitscr\fR or
 \fBnewterm\fR are called.
@@ -133,6 +135,7 @@ 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
 .PP
 The \fBuse_env\fR routine, if used,
 should be called before \fBinitscr\fR or
@@ -158,6 +161,7 @@ from the operating system or terminal database.
 .IP
 Ncurses also updates the screen size in response to SIGWINCH,
 unless overridden by the \fBLINES\fR or \fBCOLUMNS\fR environment variables,
+.SS use_tioctl
 .PP
 The \fBuse_tioctl\fR routine, if used,
 should be called before \fBinitscr\fR or \fBnewterm\fR are called
@@ -198,6 +202,7 @@ FALSE/FALSE/T{
 ncurses relies on the terminal database to determine size.
 T}
 .TE
+.SS putwin/getwin
 .PP
 The \fBputwin\fR routine writes all data associated
 with window (or pad) \fIwin\fR into
@@ -216,6 +221,7 @@ the data written is a copy of the \fBWINDOW\fP structure,
 and its associated character cells.
 The format differs between the wide-character (ncursesw) and
 non-wide (ncurses) 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.
@@ -225,6 +231,7 @@ 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
 .PP
 The \fBdelay_output\fR routine inserts an \fIms\fR millisecond pause
 in output.
@@ -232,6 +239,7 @@ This routine should not be used extensively because
 padding characters are used rather than a CPU pause.
 If no padding character is specified,
 this uses \fBnapms\fR to perform the delay.
+.SS flushinp
 .PP
 The \fBflushinp\fR routine throws away any typeahead that has been typed by the
 user and has not yet been read by the program.
@@ -256,11 +264,65 @@ returns an error if the terminal was not initialized.
 returns an error if the associated \fBfwrite\fP calls return an error.
 .RE
 .SH PORTABILITY
+.SS filter
+.PP
+The SVr4 documentation describes the action of \fBfilter\fR only in the vaguest
+terms.
+The description here is adapted from the XSI Curses standard (which
+erroneously fails to describe the disabling of \fBcuu\fR).
+.SS keyname
+.PP
+The \fBkeyname\fP function may return the names of user-defined
+string capabilities which are defined in the terminfo entry via the \fB\-x\fP
+option of \fB@TIC@\fP.
+This implementation automatically assigns at run-time keycodes to
+user-defined strings which begin with "k".
+The keycodes start at KEY_MAX, but are not guaranteed to be
+the same value for different runs because user-defined codes are
+merged from all terminal descriptions which have been loaded.
+The \fBuse_extended_names\fP function controls whether this data is
+loaded when the terminal description is read by the library.
+.SS nofilter/use_tioctl
+.PP
+The \fBnofilter\fP and \fBuse_tioctl\fP routines are specific to ncurses.
+They were not supported on Version 7, BSD or System V implementations.
+It is recommended that any code depending on ncurses extensions
+be conditioned using NCURSES_VERSION.
+.SS putwin/getwin
+.PP
+The \fBputwin\fP and \fBgetwin\fP functions have several issues with
+portability:
+.bP
+The files written and read by these functions
+use an implementation-specific format.
+Although the format is an obvious target for standardization,
+it has been overlooked.
+.IP
+Interestingly enough, according to the copyright dates in Solaris source,
+the functions (along with \fBscr_init\fP, etc.) originated with
+the University of California, Berkeley (in 1982)
+and were later (in 1988) incorporated into SVr4.
+Oddly, there are no such functions in the 4.3BSD curses sources.
+.bP
+Most implementations simply dump the binary \fBWINDOW\fP structure to the file.
+These include SVr4 curses, NetBSD and PDCurses, as well as older ncurses versions.
+This implementation (as well as the X/Open variant of Solaris curses, dated 1995)
+uses textual dumps.
+.IP
+The implementations which use binary dumps use block-I/O
+(the \fBfwrite\fP and \fBfread\fP functions).
+Those that use textual dumps use buffered-I/O.
+A few applications may happen to write extra data in the file using
+these functions.
+Doing that can run into problems mixing block- and buffered-I/O.
+This implementation reduces the problem on writes by flushing the output.
+However, reading from a file written using mixed schemes may not be successful.
+.SS unctrl/wunctrl
+.PP
 The XSI Curses standard, Issue 4 describes these functions.
 It states that \fBunctrl\fR and \fBwunctrl\fR will return a null pointer if
 unsuccessful, but does not define any error conditions.
 This implementation checks for three cases:
-.RS 3
 .bP
 the parameter is a 7-bit US\-ASCII code.
 This is the case that X/Open Curses documented.
@@ -279,12 +341,6 @@ and returns the \*(``~@\*('', etc., values in that case.
 .bP
 parameter values outside the 0 to 255 range.
 \fBunctrl\fP returns a null pointer.
-.RE
-.PP
-The SVr4 documentation describes the action of \fBfilter\fR only in the vaguest
-terms.
-The description here is adapted from the XSI Curses standard (which
-erroneously fails to describe the disabling of \fBcuu\fR).
 .PP
 The strings returned by \fBunctrl\fR in this implementation are determined
 at compile time,
@@ -309,22 +365,6 @@ X/Open Curses does not document the treatment of codes 128 to 159.
 When treating them as \*(``meta\*('' keys
 (or if \fBkeyname\fP is called before initializing curses),
 this implementation returns strings \*(``M\-^@\*('', \*(``M\-^A\*('', etc.
-.PP
-The \fBkeyname\fP function may return the names of user-defined
-string capabilities which are defined in the terminfo entry via the \fB\-x\fP
-option of \fB@TIC@\fP.
-This implementation automatically assigns at run-time keycodes to
-user-defined strings which begin with "k".
-The keycodes start at KEY_MAX, but are not guaranteed to be
-the same value for different runs because user-defined codes are
-merged from all terminal descriptions which have been loaded.
-The \fBuse_extended_names\fP function controls whether this data is
-loaded when the terminal description is read by the library.
-.PP
-The \fBnofilter\fP and \fBuse_tioctl\fP routines are specific to ncurses.
-They were not supported on Version 7, BSD or System V implementations.
-It is recommended that any code depending on ncurses extensions
-be conditioned using NCURSES_VERSION.
 .SH SEE ALSO
 \fBlegacy_coding\fR(3X),
 \fBcurses\fR(3X),