'\" t
.\"***************************************************************************
-.\" Copyright 2018-2022,2023 Thomas E. Dickey *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $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"
+.\" $Id: curs_util.3x,v 1.101 2024/04/20 21:20:07 tom Exp $
+.TH curs_util 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.nf
\fB#include <curses.h>
.PP
-\fBconst char *unctrl(chtype \fIc\fP);
-\fBwchar_t *wunctrl(cchar_t *\fIc\fP);
+\fBconst char *unctrl(chtype \fIch\fP);
+\fBwchar_t *wunctrl(cchar_t *\fIwch\fP);
.PP
\fBconst char *keyname(int \fIc\fP);
-\fBconst char *key_name(wchar_t \fIw\fP);
+\fBconst char *key_name(wchar_t \fIwc\fP);
.PP
\fBvoid filter(void);
.PP
.SH DESCRIPTION
.SS unctrl
The \fBunctrl\fP routine returns a character string which is a printable
-representation of the character \fIc\fP:
+representation of the character \fIch\fP:
.bP
Printable characters are displayed as themselves,
e.g., a one-character string containing the key.
this follows the X/Open specification.
.PP
The corresponding \fBwunctrl\fP returns a printable representation of
-a complex character \fIc\fP.
+a complex character \fIwch\fP.
.PP
In both \fBunctrl\fP and \fBwunctrl\fP the attributes and color associated
with the character parameter are ignored.
-.SS keyname/key_name
+.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.
\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
+.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:
using operating system calls to obtain size.
T}
.TE
-.SS putwin/getwin
+.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.
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,
+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.
.PP
Routines that return pointers return \fBNULL\fP on error.
.PP
-X/Open does not define any error conditions.
+X/Open Curses does not specify any error conditions.
In this implementation
.RS 3
.TP 5
.SS filter
The SVr4 documentation describes the action of \fBfilter\fP only in the vaguest
terms.
-The description here is adapted from the XSI Curses standard (which
+The description here is adapted from X/Open Curses (which
erroneously fails to describe the disabling of \fBcuu\fP).
-.SS delay_output padding
+.SS "delay_output padding"
The limitation to 30 seconds
and the use of \fBnapms\fP
differ from other implementations.
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
+.SS "nofilter, use_tioctl"
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 \fI\%ncurses\fP extensions
be conditioned using \fBNCURSES_VERSION\fP.
-.SS putwin/getwin file-format
+.SS "putwin/getwin file-format"
The \fBputwin\fP and \fBgetwin\fP functions have several issues with
portability:
.bP
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.
+Most implementations simply dump the binary \fI\%WINDOW\fP structure
+to the file.
These include SVr4 curses, NetBSD and PDCurses,
as well as older \fI\%ncurses\fP versions.
This implementation
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
-The XSI Curses standard, Issue 4 describes these functions.
+.SS "unctrl, wunctrl"
+X/Open Curses, Issue 4 describes these functions.
It states that \fBunctrl\fP and \fBwunctrl\fP will return a null pointer if
unsuccessful, but does not define any error conditions.
This implementation checks for three cases:
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
+.SS "use_env, use_tioctl"
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
projects / ncurses.git / blobdiff