'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2015,2017 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_util.3x,v 1.47 2017/02/18 16:43:03 tom Exp $
+.\" $Id: curs_util.3x,v 1.54 2018/07/28 22:08:59 tom Exp $
.TH curs_util 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.ie \n(.g .ds '' \(rq
.el .ds '' ''
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.na
.hy 0
.PP
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.
+Calling \fBfilter\fP causes these changes in initialization:
+.bP
+\fBLINES\fR is set to 1;
+.bP
+the capabilities
+\fBclear\fR,
+\fBcud1\fR,
+\fBcud\fR,
+\fBcup\fR,
+\fBcuu1\fR,
+\fBcuu\fR,
+\fBvpa\fR
+are disabled;
+.bP
+the capability \fBed\fP is disabled if \fBbce\fP is set;
+.bP
+and the \fBhome\fR string is set to the value of \fBcr\fR.
.PP
The \fBnofilter\fP routine cancels the effect of a preceding \fBfilter\fP
call.
.IP
If \fBuse_env\fP was called with \fBFALSE\fP for parameter,
it stops here unless
-If \fBuse_tioctl\fP was also called with \fBTRUE\fP for parameter.
+\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,
using a value in those to override the results
from the operating system or terminal database.
.IP
-\fBNcurses\fP also updates the screen size in response to SIGWINCH,
+\fBNcurses\fP also updates the screen size in response to \fBSIGWINCH\fP,
unless overridden by the \fBLINES\fR or \fBCOLUMNS\fR environment variables,
.SS use_tioctl
.PP
should be called before \fBinitscr\fR or \fBnewterm\fR are called
(because those compute the screen size).
After \fBuse_tioctl\fR is called with \fBTRUE\fR as an argument,
-\fBncurses\fP modifies the last step in its computation of screen size as follows:
+\fBncurses\fP modifies the last step in its computation
+of screen size as follows:
.bP
checks if the \fBLINES\fR and \fBCOLUMNS\fR environment variables
are set to a number greater than zero.
\fBncurses\fP updates $LINES and $COLUMNS based on operating system calls.
T}
FALSE/TRUE/T{
-\fBncurses\fP ignores $LINES and $COLUMNS, uses operating system calls to obtain size.
+\fBncurses\fP ignores $LINES and $COLUMNS,
+uses operating system calls to obtain size.
T}
FALSE/FALSE/T{
\fBncurses\fP relies on the terminal database to determine size.
.bP
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.
+The format differs between the wide-character (\fBncursesw\fP) and
+non-wide (\fBncurses\fP) libraries.
You can transfer data between the two, however.
.bP
the retrieved window is always created as a top-level window (or pad),
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
+The \fBuse_extended_names\fP(3X) function controls whether this data is
loaded when the terminal description is read by the library.
.SS nofilter/use_tioctl
.PP
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 \fBncurses\fP versions.
-This implementation (as well as the X/Open variant of Solaris curses, dated 1995)
+These include SVr4 curses, NetBSD and PDCurses,
+as well as older \fBncurses\fP 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
.PP
The strings returned by \fBunctrl\fR in this implementation are determined
at compile time,
-showing C1 controls from the upper-128 codes with a \*(``~\*('' prefix rather than \*(``^\*(''.
+showing C1 controls from the upper-128 codes
+with a \*(``~\*('' prefix rather than \*(``^\*(''.
Other implementations have different conventions.
For example, they may show both sets of control characters with \*(``^\*('',
and strip the parameter to 7 bits.
When treating them as \*(``meta\*('' keys
(or if \fBkeyname\fP is called before initializing curses),
this implementation returns strings \*(``M\-^@\*('', \*(``M\-^A\*('', etc.
+.PP
+X/Open Curses documents \fBunctrl\fP as declared in \fB<unctrl.h>\fP,
+which \fBncurses\fP does.
+However, \fBncurses\fP' \fB<curses.h>\fP includes \fB<unctrl.h>\fP,
+matching the behavior of SVr4 curses.
+Other implementations may not do that.
.SS use_env/use_tioctl
.PP
If \fBncurses\fP is configured to provide the sp-functions extension,