'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2015,2017 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 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.52 2017/11/18 23:47:37 tom Exp $
+.\" $Id: curs_util.3x,v 1.55 2019/03/23 21:51:12 tom Exp $
.TH curs_util 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.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
.br
-\fBchar *keyname(int c);\fR
+\fBconst char *keyname(int c);\fR
.br
-\fBchar *key_name(wchar_t w);\fR
+\fBconst char *key_name(wchar_t w);\fR
.br
\fBvoid filter(void);\fR
.br
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),
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,