ncurses 6.2 - patch 20201017
[ncurses.git] / man / curs_util.3x
index 652628a873f3ecdac22554c48fb6b2ded0b3440d..a71015b3ef45ec5d2fc6efccd68ab4bedcb049c5 100644 (file)
@@ -1,5 +1,7 @@
+'\" t
 .\"***************************************************************************
-.\" Copyright (c) 1998-2008,2010 Free Software Foundation, Inc.              *
+.\" Copyright 2018-2019,2020 Thomas E. Dickey                                *
+.\" Copyright 1998-2015,2017 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.28 2010/07/31 16:10:55 tom Exp $
+.\" $Id: curs_util.3x,v 1.58 2020/10/17 22:54:59 tom Exp $
 .TH curs_util 3X ""
+.ie \n(.g .ds `` \(lq
+.el       .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el       .ds '' ''
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
 .na
 .hy 0
 .SH NAME
 \fBputwin\fR,
 \fBunctrl\fR,
 \fBuse_env\fR,
+\fBuse_tioctl\fR,
 \fBwunctrl\fR \- miscellaneous \fBcurses\fR utility routines
 .ad
 .hy
 .SH SYNOPSIS
 \fB#include <curses.h>\fR
 .sp
-\fBchar *unctrl(chtype c);\fR
+\fBconst char *unctrl(chtype c);\fR
 .br
 \fBwchar_t *wunctrl(cchar_t *c);\fR
+.sp
+\fBconst char *keyname(int c);\fR
 .br
-\fBchar *keyname(int c);\fR
-.br
-\fBchar *key_name(wchar_t w);\fR
-.br
+\fBconst char *key_name(wchar_t w);\fR
+.sp
 \fBvoid filter(void);\fR
 .br
 \fBvoid nofilter(void);\fR
-.br
+.sp
 \fBvoid use_env(bool f);\fR
 .br
+\fBvoid use_tioctl(bool f);\fR
+.sp
 \fBint putwin(WINDOW *win, FILE *filep);\fR
 .br
 \fBWINDOW *getwin(FILE *filep);\fR
-.br
+.sp
 \fBint delay_output(int ms);\fR
 .br
 \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.
+a wide character.
+.SS keyname/key_name
 .PP
-The \fBkeyname\fR routine returns a character string corresponding to the key \fIc\fR:
-.RS 3
-.TP 3
-\-
-Printable characters are displayed as themselves, e.g., a one-character string containing the key.
-.TP 3
-\-
+The \fBkeyname\fR routine returns a character string
+corresponding to the key \fIc\fR:
+.bP
+Printable characters are displayed as themselves,
+e.g., a one-character string containing the key.
+.bP
 Control characters are displayed in the \fB^\fR\fIX\fR notation.
-.TP 3
-\-
+.bP
 DEL (character 127) is displayed as \fB^?\fP.
-.TP 3
-\-
+.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(3X) 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;
 this follows the X/Open specification.
-.TP 3
-\-
+.bP
 Values above 256 may be the names of the names of function keys.
-.TP 3
-\-
+.bP
 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
+X/Open also lists an \*(``UNKNOWN KEY\*('' return value,
+which some implementations return rather than null.
 .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.  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.
+\fBnewterm\fR are called.
+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.
@@ -125,30 +150,113 @@ 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, 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).
-Note that setting \fBLINES\fR or \fBCOLUMNS\fR overrides the
-corresponding size which may be obtained from the operating system.
+The \fBuse_env\fR routine, if used,
+should be called before \fBinitscr\fR or
+\fBnewterm\fR are called
+(because those compute the screen size).
+It modifies the way \fBncurses\fP treats environment variables
+when determining the screen size.
+.bP
+Normally \fBncurses\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),
+\fBncurses\fP examines the \fBLINES\fR or \fBCOLUMNS\fR 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,
+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
+(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:
+.bP
+checks if the \fBLINES\fR and \fBCOLUMNS\fR environment variables
+are set to a number greater than zero.
+.bP
+for each, \fBncurses\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.
 .PP
-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
+The \fBuse_env\fP and \fBuse_tioctl\fP routines combine as
+summarized here:
+.TS
+center tab(/);
+l l l
+_ _ _
+lw7 lw7 lw40.
+\fIuse_env\fR/\fIuse_tioctl\fR/\fISummary\fR
+TRUE/FALSE/T{
+This is the default behavior.
+\fBncurses\fP uses operating system calls
+unless overridden by $LINES or $COLUMNS environment variables.
+T}
+TRUE/TRUE/T{
+\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.
+T}
+FALSE/FALSE/T{
+\fBncurses\fP 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
+the file to which \fIfilep\fR points.
+This information can be later retrieved
 using the \fBgetwin\fR function.
 .PP
 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.
+\fBputwin\fR.
+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 \fBWINDOW\fP structure,
+and its associated character cells.
+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),
+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
 .PP
 The \fBdelay_output\fR routine inserts an \fIms\fR millisecond pause
-in output.  This routine should not be used extensively because
+in output.
+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.
+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.
@@ -166,93 +274,135 @@ In this implementation
 \fBflushinp\fR
 returns an error if the terminal was not initialized.
 .TP 5
-\fBmeta\fR
-returns an error if the terminal was not initialized.
-.TP 5
 \fBputwin\fP
 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(3X) 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 \fBncurses\fP.
+They were not supported on Version 7, BSD or System V implementations.
+It is recommended that any code depending on \fBncurses\fP 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 \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
+(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
-.TP 5
-\-
+.bP
 the parameter is a 7-bit US\-ASCII code.
 This is the case that X/Open Curses documented.
-.TP 5
-\-
+.bP
 the parameter is in the range 128\-159, i.e., a C1 control code.
-If \fBuse_legacy_coding\fP has been called with a \fB2\fP parameter,
+If \fBuse_legacy_coding\fP(3X) has been called with a \fB2\fP parameter,
 \fBunctrl\fP returns the parameter, i.e., a one-character string with
 the parameter as the first character.
-Otherwise, it returns ``~@'', ``~A'', etc., analogous to ``^@'', ``^A'', C0 controls.
+Otherwise, it returns \*(``~@\*('', \*(``~A\*('', etc.,
+analogous to \*(``^@\*('', \*(``^A\*('', C0 controls.
 .IP
 X/Open Curses does not document whether \fBunctrl\fP can be called before
 initializing curses.
 This implementation permits that,
-and returns the ``~@'', etc., values in that case.
-.TP 5
-\-
+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,
-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 `^',
+For example, they may show both sets of control characters with \*(``^\*('',
 and strip the parameter to 7 bits.
 Or they may ignore C1 controls and treat all of the upper-128 codes as
 printable.
 This implementation uses 8 bits but does not modify the string to reflect
 locale.
-The \fBuse_legacy_coding\fP function allows the caller to
+The \fBuse_legacy_coding\fP(3X) function allows the caller to
 change the output of \fBunctrl\fP.
 .PP
-Likewise, the \fBmeta\fP function allows the caller to change the
+Likewise, the \fBmeta\fP(3X) function allows the caller to change the
 output of \fBkeyname\fP, i.e.,
-it determines whether to use the `M\-' prefix
-for ``meta'' keys (codes in the range 128 to 255).
-Both \fBuse_legacy_coding\fP and \fBmeta\fP succeed only after
-curses is initialized. 
+it determines whether to use the \*(``M\-\*('' prefix
+for \*(``meta\*('' keys (codes in the range 128 to 255).
+Both \fBuse_legacy_coding\fP(3X) and \fBmeta\fP(3X) succeed only after
+curses is initialized.
 X/Open Curses does not document the treatment of codes 128 to 159.
-When treating them as ``meta'' keys
+When treating them as \*(``meta\*('' keys
 (or if \fBkeyname\fP is called before initializing curses),
-this implementation returns strings ``M\-^@'', ``M\-^A'', etc.
+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 \fBtic\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.
+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
-The \fBnofilter\fP routine is specific to ncurses.
-It was 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.
+If \fBncurses\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\fR(3X)).
+This feature of \fBuse_env\fP
+is not provided by other implementation of curses.
 .SH SEE ALSO
 \fBlegacy_coding\fR(3X),
 \fBcurses\fR(3X),
 \fBcurs_initscr\fR(3X),
+\fBcurs_inopts\fR(3X),
 \fBcurs_kernel\fR(3X),
 \fBcurs_scr_dump\fR(3X),
+\fBcurs_sp_funcs\fR(3X),
+\fBcurs_variables\fR(3X),
 \fBlegacy_coding\fR(3X).
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End: