.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_util.3x,v 1.90 2023/12/02 21:10:36 tom Exp $
-.TH curs_util 3X 2023-12-02 "ncurses 6.4" "Library calls"
+.\" $Id: curs_util.3x,v 1.91 2023/12/16 20:32:22 tom Exp $
+.TH curs_util 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
should be called before \fBinitscr\fP or
\fBnewterm\fP are called
(because those compute the screen size).
-It modifies the way \fIncurses\fP treats environment variables
+It modifies the way \fI\%ncurses\fP treats environment variables
when determining the screen size.
.bP
-Normally \fIncurses\fP looks first at the terminal database for the screen size.
+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
it overrides the values from the terminal database.
.bP
Finally (unless \fBuse_env\fP was called with \fBFALSE\fP parameter),
-\fBncurses\fP examines the \fILINES\fP or \fI\%COLUMNS\fP environment
+\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
-\fBNcurses\fP also updates the screen size in response to \fBSIGWINCH\fP,
+\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
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,
-\fBncurses\fP modifies the last step in its computation
+\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, \fBncurses\fP updates the corresponding environment variable
+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
-\fBncurses\fP re-fetches the value of the environment variables so that
-it is still the environment variables which set the screen size.
+\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
_
TRUE FALSE T{
This is the default behavior.
-\fIncurses\fP uses operating system calls
+\fI\%ncurses\fP uses operating system calls
unless overridden by \fILINES\fP or \fI\%COLUMNS\fP environment
variables;
default.
T}
TRUE TRUE T{
-\fIncurses\fP updates \fILINES\fP and \fI\%COLUMNS\fP based on operating
-system calls.
+\fI\%ncurses\fP updates \fILINES\fP and \fI\%COLUMNS\fP based on
+operating system calls.
T}
FALSE TRUE T{
-\fIncurses\fP ignores \fILINES\fP and \fI\%COLUMNS\fP,
+\fI\%ncurses\fP ignores \fILINES\fP and \fI\%COLUMNS\fP,
using operating system calls to obtain size.
T}
.TE
.bP
the data written is a copy of the \fBWINDOW\fP structure,
and its associated character cells.
-The format differs between the wide-character (\fBncursesw\fP) and
-non-wide (\fBncurses\fP) libraries.
+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),
The \fBdelay_output\fP routine inserts an \fIms\fP millisecond pause
in output.
Employ this function judiciously when terminal output uses padding,
-because \fIncurses\fP transmits null characters
+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:
the environment variable \fB\%NCURSES_NO_PADDING\fP is set.
.PP
If padding is not in use,
-\fIncurses\fP uses \fBnapms\fP to perform the delay.
+\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.
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
-The \fBnofilter\fP and \fBuse_tioctl\fP routines are specific to \fBncurses\fP.
+The \fBnofilter\fP and \fBuse_tioctl\fP routines are specific to
+\fI\%ncurses\fP.
They were not supported on Version 7, BSD or System V implementations.
-It is recommended that any code depending on \fBncurses\fP extensions
+It is recommended that any code depending on \fI\%ncurses\fP extensions
be conditioned using \fBNCURSES_VERSION\fP.
.SS putwin/getwin file-format
The \fBputwin\fP and \fBgetwin\fP functions have several issues with
.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.
+as well as older \fI\%ncurses\fP versions.
This implementation
(as well as the X/Open variant of Solaris curses, dated 1995)
uses textual dumps.
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,
+which \fI\%ncurses\fP does.
+However, \fI\%ncurses\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
-If \fBncurses\fP is configured to provide the sp-functions extension,
+If \fI\%ncurses\fP is configured to provide the sp-functions extension,
the state of \fBuse_env\fP and \fBuse_tioctl\fP may be updated before
creating each \fIscreen\fP rather than once only
(\fBcurs_sp_funcs\fP(3X)).
projects / ncurses.git / blobdiff