libncurses: Import https://ftp.gnu.org/pub/gnu/ncurses/ncurses-6.5.tar.gz changes
Change-Id: I3433d30ca01359fd2e3623ede96b531f0b39cbfa
Signed-off-by: micky387 <mickaelsaibi@free.fr>
diff --git a/man/MKada_config.in b/man/MKada_config.in
index 6845897..ee037ff 100644
--- a/man/MKada_config.in
+++ b/man/MKada_config.in
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2010-2011,2014 Free Software Foundation, Inc. *
+.\" Copyright 2019-2023,2024 Thomas E. Dickey *
+.\" Copyright 2010-2014,2016 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 *
@@ -26,97 +27,123 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: MKada_config.in,v 1.8 2014/06/07 19:32:52 tom Exp $
-.TH ADACURSES "1" "" "" "User Commands"
+.\" $Id: MKada_config.in,v 1.35 2024/04/20 21:13:27 tom Exp $
+.TH adacurses@USE_CFG_SUFFIX@\-config 1 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.ds C adacurses@USE_CFG_SUFFIX@\-config
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.ds ' \(aq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.ie t .ds ' \(aq
+.el .ds ' '
+.\}
+.
+.\" Fix broken EX/EE macros on DWB troff.
+.\" Detect it: only DWB sets up a `)Y` register.
+.if !\n(.g .if \n()Y \{\
+.\" Revert the undesired changes to indentation.
+.am EX
+.in -5n
+..
+.am EE
+.in +5n
+..
+.\}
+.
.SH NAME
-adacurses\-config \- helper script for AdaCurses libraries
+\fB\%adacurses@USE_CFG_SUFFIX@\-config\fP \-
+configuration helper for \fI@ADA_LIBNAME@\fP libraries
.SH SYNOPSIS
-.B adacurses\-config
-[\fIoptions\fR]
+.B \*C
+.RB [ \-\-cflags ]
+.RB [ \-\-libs ]
+.PP
+.B \*C \-\-version
+.PP
+.B \*C \-\-help
.SH DESCRIPTION
-This is a shell script which simplifies configuring an application to use
-the AdaCurses library binding to ncurses.
+This program development aid simplifies the process of configuring
+applications to use the \fI@ADA_LIBNAME@\fP library binding to
+\fI\%ncurses\fP.
.SH OPTIONS
+.TP 11 \" "--version" + 2n
+\fB\-\-cflags\fP
+reports the GNAT (Ada compiler) flags needed to compile with
+\fI@ADA_LIBNAME@\fP.
.TP
-\fB\-\-cflags\fR
-echos the gnat (Ada compiler) flags needed to compile with AdaCurses.
+\fB\-\-libs\fP
+reports the GNAT libraries needed to link with \fI@ADA_LIBNAME@\fP.
.TP
-\fB\-\-libs\fR
-echos the gnat libraries needed to link with AdaCurses.
+\fB\-\-version\fP
+reports the release and patch date information of the \fI\%ncurses\fP
+libraries used to configure and build \fI@ADA_LIBNAME@\fP and exits
+successfully.
.TP
-\fB\-\-version\fR
-echos the release+patchdate version of the ncurses libraries used
-to configure and build AdaCurses.
-.TP
-\fB\-\-help\fR
-prints a list of the \fBadacurses\-config\fP script's options.
+\fB\-\-help\fP
+issues a usage message and exits successfully.
.PP
-If no options are given, \fBadacurses\-config\fP prints the combination
-of
-\fB\-\-cflags\fR and
-\fB\-\-libs\fR
-that \fBgnatmake\fP expects (see example).
-.SH EXAMPLE
+Omitting options implies \*(``\fB\-\-cflags \-\-libs\fP\*(''.
+.SH EXAMPLES
+Consider a program using \fI@ADA_LIBNAME@\fP to write the message
+\*(``Hello, world!\*('' in the center of the screen and wait for the
+user to press the \*(``q\*('' key before exiting.
+Populate a file \fIhello.adb\fP with the following.
.PP
-For example, supposing that you want to compile the "Hello World!"
-program for AdaCurses.
-Make a file named "hello.adb":
-.RS
-.nf
-.ft CW
+.if \n(LL>67n .RS 4
+.EX
with Terminal_Interface.Curses; use Terminal_Interface.Curses;
procedure Hello is
-
Visibility : Cursor_Visibility := Invisible;
+ Message : constant String := "Hello, World!";
done : Boolean := False;
c : Key_Code;
-
begin
-
Init_Screen;
Set_Echo_Mode (False);
-
Set_Cursor_Visibility (Visibility);
Set_Timeout_Mode (Standard_Window, Non_Blocking, 0);
- Move_Cursor (Line => Lines / 2, Column => (Columns - 12) / 2);
- Add (Str => "Hello World!");
+ Move_Cursor (Line => Lines / 2,
+ Column => (Columns \- Message\*'Length) / 2);
+ Add (Str => Message);
while not done loop
-
c := Get_Keystroke (Standard_Window);
+
case c is
- when Character'Pos ('q') => done := True;
- when others => null;
+ when Character\*'Pos (\*'q\*') => done := True;
+ when others => null;
end case;
Nap_Milli_Seconds (50);
end loop;
End_Windows;
-
end Hello;
-.fi
-.RE
+.EE
+.if \n(LL>67n .RE
+.ne 2
.PP
Then, using
-.RS
-.ft CW
-gnatmake `adacurses-config --cflags` hello -largs `adacurses-config --libs`
-.ft
+.RS 4
+.EX
+gnatmake \(gaadacurses@USE_CFG_SUFFIX@\-config \-\-cflags\(ga hello \e
+ \-largs \(gaadacurses@USE_CFG_SUFFIX@\-config \-\-libs\(ga
+.EE
.RE
-.PP
-or (simpler):
-.RS
-.ft CW
-gnatmake hello `adacurses-config`
-.ft
+or, more simply,
+.RS 4
+.EX
+gnatmake hello \(gaadacurses@USE_CFG_SUFFIX@\-config\(ga
+.EE
.RE
-.PP
-you will compile and link the program.
+you can compile and link the program.
.SH "SEE ALSO"
-\fBcurses\fR(3X)
-.PP
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
+\fB\%curses\fP(3X)
diff --git a/man/MKncu_config.in b/man/MKncu_config.in
index 3de772c..14690a5 100644
--- a/man/MKncu_config.in
+++ b/man/MKncu_config.in
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2010 Free Software Foundation, Inc. *
+.\" Copyright 2020-2023,2024 Thomas E. Dickey *
+.\" Copyright 2010 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 *
@@ -26,73 +27,78 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: MKncu_config.in,v 1.3 2010/03/06 22:29:17 tom Exp $
-.TH @LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config 1 ""
+.\" $Id: MKncu_config.in,v 1.24 2024/04/20 21:13:38 tom Exp $
+.TH @LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config 1 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
.SH NAME
-@LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config \- helper script for ncurses libraries
+\fB\%@LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config\fP \-
+configuration helper for \fI\%ncurses\fP libraries
.SH SYNOPSIS
-.B @LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config
-[\fIoptions\fR]
-.SH DESCRIPTION
-This is a shell script which simplifies configuring applications against
-a particular set of ncurses libraries.
-.SH OPTIONS
-.TP
-\fB\-\-prefix\fR
-echos the package\-prefix of ncurses
-.TP
-\fB\-\-exec\-prefix\fR
-echos the executable\-prefix of ncurses
-.TP
-\fB\-\-cflags\fR
-echos the C compiler flags needed to compile with ncurses
-.TP
-\fB\-\-libs\fR
-echos the libraries needed to link with ncurses
-.TP
-\fB\-\-version\fR
-echos the release+patchdate version of ncurses
-.TP
-\fB\-\-abi\-version\fR
-echos the ABI version of ncurses
-.TP
-\fB\-\-mouse\-version\fR
-echos the mouse\-interface version of ncurses
-.TP
-\fB\-\-bindir\fR
-echos the directory containing ncurses programs
-.TP
-\fB\-\-datadir\fR
-echos the directory containing ncurses data
-.TP
-\fB\-\-includedir\fR
-echos the directory containing ncurses header files
-.TP
-\fB\-\-libdir\fR
-echos the directory containing ncurses libraries
-.TP
-\fB\-\-mandir\fR
-echos the directory containing ncurses manpages
-.TP
-\fB\-\-terminfo\fR
-echos the $TERMINFO terminfo database path, e.g.,
-.RS
-@TERMINFO@
-.RE
-.TP
-\fB\-\-terminfo\-dirs\fR
-echos the $TERMINFO_DIRS directory list, e.g.,
-.RS
-@TERMINFO_DIRS@
-.RE
-.TP
-\fB\-\-termpath\fR
-echos the $TERMPATH termcap list, if support for termcap is configured.
-.TP
-\fB\-\-help\fR
-prints this message
-.SH "SEE ALSO"
-\fBcurses\fR(3X)
+.B @LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config
+.I option
+\&.\|.\|.
.PP
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
+.B "@LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config \-\-version"
+.PP
+.B "@LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config \-\-help"
+.SH DESCRIPTION
+This program development aid simplifies the process of configuring
+applications against a particular set of \fI\%ncurses\fP libraries.
+.SH OPTIONS
+.TP 18 \" "--mouse-version" + 2n + adjustment for PDF
+\fB\-\-prefix\fP
+reports the package prefix of \fI\%ncurses\fP.
+.TP
+\fB\-\-exec\-prefix\fP
+reports the executable prefix of \fI\%ncurses\fP.
+.TP
+\fB\-\-cflags\fP
+reports the C compiler flags needed to compile with \fI\%ncurses\fP.
+.TP
+\fB\-\-libs\fP
+reports the libraries needed to link with \fI\%ncurses\fP.
+.TP
+\fB\-\-abi\-version\fP
+reports the ABI version of \fI\%ncurses\fP.
+.TP
+\fB\-\-mouse\-version\fP
+reports the mouse\-interface version of \fI\%ncurses\fP.
+.TP
+\fB\-\-bindir\fP
+reports the directory containing \fI\%ncurses\fP programs.
+.TP
+\fB\-\-datadir\fP
+reports the directory containing \fI\%ncurses\fP data.
+.TP
+\fB\-\-includedir\fP
+reports the directory containing \fI\%ncurses\fP header files.
+.TP
+\fB\-\-libdir\fP
+reports the directory containing \fI\%ncurses\fP libraries.
+.TP
+\fB\-\-mandir\fP
+reports the directory containing \fI\%ncurses\fP man pages.
+.TP
+\fB\-\-terminfo\fP
+reports the \fI\%TERMINFO\fP \fIterminfo\fP database path,
+for example \fI\%@TERMINFO@\fP.
+.TP
+\fB\-\-terminfo\-dirs\fP
+reports the \fI\%TERMINFO_DIRS\fP supplemental search path for the
+\fIterminfo\fP database,
+for example \fI\%@TERMINFO_DIRS@\fP.
+.TP
+\fB\-\-termpath\fP
+reports the \fI\%TERMPATH\fP supplemental search path for the
+\fItermcap\fP database,
+if support for \fItermcap\fP is configured.
+.PP
+The following options cause all others to be ignored.
+.TP 11 .\" "--version" + 2n
+\fB\-\-help\fP
+issues a usage message and exits successfully.
+.TP
+\fB\-\-version\fP
+issues the release and patch date information of \fI\%ncurses\fP and
+exits successfully.
+.SH "SEE ALSO"
+\fB\%curses\fP(3X)
diff --git a/man/MKterminfo.sh b/man/MKterminfo.sh
index 3a99609..882ef2a 100755
--- a/man/MKterminfo.sh
+++ b/man/MKterminfo.sh
@@ -1,10 +1,11 @@
#!/bin/sh
-# $Id: MKterminfo.sh,v 1.12 2003/01/11 21:42:12 tom Exp $
+# $Id: MKterminfo.sh,v 1.20 2024/01/13 20:37:40 tom Exp $
#
# MKterminfo.sh -- generate terminfo.5 from Caps tabular data
#
#***************************************************************************
-# Copyright (c) 1998,2002,2003 Free Software Foundation, Inc. *
+# Copyright 2018-2020,2022 Thomas E. Dickey *
+# Copyright 1998-2003,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 *
@@ -49,31 +50,42 @@
if test "${LC_COLLATE+set}" = set; then LC_COLLATE=C; export LC_COLLATE; fi
#
-head=$1
-caps=$2
-tail=$3
-cat <<'EOF'
-'\" t
-.\" DO NOT EDIT THIS FILE BY HAND!
-.\" It is generated from terminfo.head, Caps, and terminfo.tail.
-.\"
-.\" Note: this must be run through tbl before nroff.
-.\" The magic cookie on the first line triggers this under some man programs.
+head="$1"
+shift 1
+caps=
+while test $# -gt 1
+do
+ caps="$caps $1"
+ shift 1
+done
+tail="$1"
+cat <<EOF
+'\\" t
+.\\" DO NOT EDIT THIS FILE BY HAND!
+.\\" It is generated from terminfo.head, $caps, and terminfo.tail.
+.\\"
+.\\" Note: this must be run through tbl before nroff.
+.\\" The magic cookie on the first line triggers this under some man programs.
EOF
-cat $head
+cat "$head"
temp=temp$$
sorted=sorted$$
unsorted=unsorted$$
-trap "rm -f $sorted $temp $unsorted; exit 99" 1 2 5 15
+trap 'code=$?; rm -f $sorted $temp $unsorted; exit $code' EXIT HUP INT QUIT TERM
+rm -f $sorted $temp $unsorted
-sed -n <$caps "\
+cat $caps | sed -n "\
/%%-STOP-HERE-%%/q
+/^#%center/s, expand,,
+/^#%lw25/s, lw6 , lw7 ,
/^#%/s/#%//p
/^#/d
s/[ ][ ]*/ /g
s/$/T}/
-s/ [A-Z0-9_()\-][A-Z0-9_()\-]* [0-9\-][0-9\-]* [Y\-][B\-][C\-][G\-][EK\-]\** / T{/
+s/ [A-Z0-9_()\-][A-Z0-9_()\-]* [0-9\-][0-9\-]* [Y\-][B\-][C\-][G\-][EK\-]\** / T{\\
+.ad l\
+/
s/ bool / /p
s/ num / /p
s/ str / /p
@@ -105,6 +117,7 @@
test $saved = yes && sort $temp >>$sorted
sed -e 's/^\.\.$//' $sorted | tr "\005\006" "\012\134"
-cat $tail
-rm -f $sorted $temp $unsorted
+sed -e '/^center expand;/s, expand,,' \
+ -e '/^\.TS/,/^\\/s, lw[1-9][0-9]*\., l.,' \
+ "$tail"
diff --git a/man/Makefile b/man/Makefile
deleted file mode 100644
index 9979da5..0000000
--- a/man/Makefile
+++ /dev/null
@@ -1,85 +0,0 @@
-# $Id: Makefile.in,v 1.48 2015/08/05 23:15:41 tom Exp $
-##############################################################################
-# Copyright (c) 1998-2013,2015 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 "Software"), #
-# to deal in the Software without restriction, including without limitation #
-# the rights to use, copy, modify, merge, publish, distribute, distribute #
-# with modifications, sublicense, and/or sell copies of the Software, and to #
-# permit persons to whom the Software is furnished to do so, subject to the #
-# following conditions: #
-# #
-# The above copyright notice and this permission notice shall be included in #
-# all copies or substantial portions of the Software. #
-# #
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR #
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, #
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL #
-# THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER #
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING #
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER #
-# DEALINGS IN THE SOFTWARE. #
-# #
-# Except as contained in this notice, the name(s) of the above copyright #
-# holders shall not be used in advertising or otherwise to promote the sale, #
-# use or other dealings in this Software without prior written #
-# authorization. #
-##############################################################################
-#
-# Author: Thomas E. Dickey 1996,1997
-#
-# Makefile for ncurses manual pages.
-#
-# NOTE: When you add or rename a man page, make sure you update both
-# the top-level MANIFEST and any man/*.renames files!
-
-SHELL = /bin/sh
-
-
-DESTDIR =
-srcdir = .
-prefix = /system
-exec_prefix = ${prefix}
-datarootdir = ${prefix}/share
-datadir = ${datarootdir}
-mandir = ${datarootdir}/man
-includesubdir = /ncurses
-
-INCLUDEDIR = $(DESTDIR)$(includedir)$(includesubdir)
-
-INSTALL = /usr/bin/install -c
-INSTALL_DATA = ${INSTALL} -m 644
-
-all \
-sources : terminfo.5
-depend :
-tags :
-
-$(DESTDIR)$(mandir) :
- mkdir -p $@
-
-EDITARGS = $(DESTDIR)$(mandir) $(srcdir) terminfo.5 *-config.1 $(srcdir)/*.[0-9]*
-
-install install.man : terminfo.5 $(DESTDIR)$(mandir)
- $(SHELL) ../edit_man.sh normal installing $(EDITARGS)
-
-uninstall uninstall.man :
- -$(SHELL) ../edit_man.sh normal removing $(EDITARGS)
-
-# We compose terminfo.5 from the real sources...
-CAPLIST=$(srcdir)/../include/Caps
-terminfo.5: $(srcdir)/terminfo.head $(CAPLIST) $(srcdir)/terminfo.tail Makefile $(srcdir)/MKterminfo.sh
- $(SHELL) $(srcdir)/MKterminfo.sh $(srcdir)/terminfo.head $(CAPLIST) $(srcdir)/terminfo.tail >terminfo.5
-
-mostlyclean :
- -rm -f core tags TAGS *~ *.bak *.ln *.atac trace
-
-clean: mostlyclean
- rm -f terminfo.5
-
-../edit_man.sed : make_sed.sh /home/shade/dev/cm/13/external/libncurses/man/man_db.renames
- $(SHELL) $(srcdir)/make_sed.sh /home/shade/dev/cm/13/external/libncurses/man/man_db.renames >../edit_man.sed
-
-distclean realclean: clean
- rm -f Makefile *-config.1 ../edit_man.* ../man_alias.*
diff --git a/man/Makefile.in b/man/Makefile.in
index 478c398..9d08a7e 100644
--- a/man/Makefile.in
+++ b/man/Makefile.in
@@ -1,6 +1,7 @@
-# $Id: Makefile.in,v 1.48 2015/08/05 23:15:41 tom Exp $
+# $Id: Makefile.in,v 1.54 2022/10/22 16:36:40 tom Exp $
##############################################################################
-# Copyright (c) 1998-2013,2015 Free Software Foundation, Inc. #
+# Copyright 2019-2021,2022 Thomas E. Dickey #
+# Copyright 1998-2013,2015 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 "Software"), #
@@ -51,6 +52,21 @@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
+################################################################################
+
+@MAKE_PHONY@.PHONY : all
+@MAKE_PHONY@.PHONY : clean
+@MAKE_PHONY@.PHONY : depend
+@MAKE_PHONY@.PHONY : distclean
+@MAKE_PHONY@.PHONY : install
+@MAKE_PHONY@.PHONY : install.man
+@MAKE_PHONY@.PHONY : libs
+@MAKE_PHONY@.PHONY : mostlyclean
+@MAKE_PHONY@.PHONY : realclean
+@MAKE_PHONY@.PHONY : sources
+@MAKE_PHONY@.PHONY : uninstall
+@MAKE_PHONY@.PHONY : uninstall.man
+
all \
sources : terminfo.5
depend :
@@ -68,8 +84,13 @@
-$(SHELL) ../edit_man.sh normal removing $(EDITARGS)
# We compose terminfo.5 from the real sources...
-CAPLIST=$(srcdir)/../include/@TERMINFO_CAPS@
-terminfo.5: $(srcdir)/terminfo.head $(CAPLIST) $(srcdir)/terminfo.tail Makefile $(srcdir)/MKterminfo.sh
+CAPLIST = \
+ $(srcdir)/../include/@TERMINFO_CAPS@ \
+ $(srcdir)/../include/Caps-ncurses
+terminfo.5: $(srcdir)/terminfo.head \
+ $(CAPLIST) \
+ $(srcdir)/terminfo.tail \
+ Makefile $(srcdir)/MKterminfo.sh
$(SHELL) $(srcdir)/MKterminfo.sh $(srcdir)/terminfo.head $(CAPLIST) $(srcdir)/terminfo.tail >terminfo.5
mostlyclean :
@@ -78,8 +99,8 @@
clean: mostlyclean
rm -f terminfo.5
-../edit_man.sed : make_sed.sh @MANPAGE_RENAMES@
+../edit_man.sed : make_sed.sh
$(SHELL) $(srcdir)/make_sed.sh @MANPAGE_RENAMES@ >../edit_man.sed
distclean realclean: clean
- rm -f Makefile *-config.1 ../edit_man.* ../man_alias.*
+ -rm -f Makefile *-config.1 ../edit_man.* ../man_alias.* man_db.renames
diff --git a/man/captoinfo.1m b/man/captoinfo.1m
index c7a3364..4693b06 100644
--- a/man/captoinfo.1m
+++ b/man/captoinfo.1m
@@ -1,6 +1,7 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2016 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 *
@@ -27,64 +28,76 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: captoinfo.1m,v 1.25 2010/12/04 18:36:44 tom Exp $
-.TH @CAPTOINFO@ 1M ""
-.ds n 5
-.ds d @TERMINFO@
+.\" $Id: captoinfo.1m,v 1.63 2024/03/23 20:37:25 tom Exp $
+.TH @CAPTOINFO@ 1M 2024-03-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-\fB@CAPTOINFO@\fR \- convert a \fItermcap\fR description into a \fIterminfo\fR description
+\fB\%@CAPTOINFO@\fP \-
+convert a \fItermcap\fP description into a \fI\%term\%info\fP description
.SH SYNOPSIS
-\fB@CAPTOINFO@\fR [\fB\-v\fR\fIn\fR \fIwidth\fR] [\fB\-V\fR] [\fB\-1\fR] [\fB\-w\fR \fIwidth\fR] \fIfile\fR . . .
+.B @CAPTOINFO@
+.RI [ tic-option ]
+.RI [ file
+\&.\|.\|.]
+.P
+.B "@CAPTOINFO@ \-V"
.SH DESCRIPTION
-\fB@CAPTOINFO@\fR looks in each given text
-\fIfile\fR for \fBtermcap\fR descriptions.
-For each
-one found, an equivalent \fBterminfo\fR description is written to standard
-output.
-Termcap \fBtc\fR capabilities are translated directly to terminfo
-\fBuse\fR capabilities.
+\fB\%@CAPTOINFO@\fP translates terminal descriptions.
+It looks in each given text \fIfile\fP for \fI\%termcap\fP entries and,
+for each one found,
+writes an equivalent \fI\%\%term\%info\fP description to the standard
+output stream.
+\fI\%termcap\fP \fBtc\fP capabilities translate to \fI\%\%term\%info\fP
+\*(``\fBuse\fP\*('' capabilities.
.PP
-If no \fIfile\fR is given, then the environment variable \fBTERMCAP\fR is used
-for the filename or entry.
-If \fBTERMCAP\fR is a full pathname to a file, only
-the terminal whose name is specified in the environment variable \fBTERM\fR is
-extracted from that file.
-If the environment variable \fBTERMCAP\fR is not
-set, then the file \fB\*d\fR is read.
-.TP 5
-\fB\-v\fR
-print out tracing information on standard error as the program runs.
-.TP 5
-\fB\-V\fR
-print out the version of the program in use on standard error and exit.
-.TP 5
-\fB\-1\fR
-cause the fields to print out one to a line.
-Otherwise, the fields
-will be printed several to a line to a maximum width of 60
-characters.
-.TP 5
-\fB\-w\fR
-change the output to \fIwidth\fR characters.
-.SH FILES
-.TP 20
-\*d
-Compiled terminal description database.
-.SH TRANSLATIONS FROM NONSTANDARD CAPABILITIES
+If no \fIfile\fPs are specified,
+\fB\%@CAPTOINFO@\fP interprets the content of the environment variable
+\fI\%TERMCAP\fP as a file name,
+and extracts only the entry for the terminal named in the environment
+variable \fITERM\fP from it.
+If the environment variable \fI\%TERMCAP\fP is not set,
+\fB\%@CAPTOINFO@\fP reads
+.IR \%/etc/termcap .
.PP
-Some obsolete nonstandard capabilities will automatically be translated
-into standard (SVr4/XSI Curses) terminfo capabilities by \fB@CAPTOINFO@\fR.
-Whenever one of these automatic translations is done, the program
-will issue an notification to stderr, inviting the user to check that
-it has not mistakenly translated a completely unknown and random
-capability and/or syntax error.
+This utility is implemented as a link to \fB\%@TIC@\fP(1M),
+with the latter's
+.B \-I
+option implied.
+You can use other \fB\%@TIC@\fP options such as
+.BR \-1 ,
+.BR \-f ,
+.BR \-v ,
+.BR \-w ,
+and
+.BR \-x .
+The \fB\-V\fP option reports the version of \fI\%ncurses\fP associated
+with this program and exits with a successful status.
+.SS "Translations from Nonstandard Capabilities"
+\fB\%@CAPTOINFO@\fP translates some obsolete,
+nonstandard capabilities into standard
+(SVr4/XSI Curses)
+\fI\%\%term\%info\fP capabilities.
+It issues a diagnostic to the standard error stream for each,
+inviting the user to check that it has not mistakenly translated an
+unknown or mistyped capability name.
.PP
-.TS H
-c c c c
-c c c c
-l l l l.
-Nonstd Std From Terminfo
-name name capability
+.\" DWB 3.3 tbl requires the two junk "L" specifiers in the first row.
+.TS
+center;
+Cb S L L
+Cb Cb Cb Cb
+Cb Cb C Lb.
+Name
+Obsolete Standard Origin \f(BIterminfo\fP capability
_
BO mr AT&T enter_reverse_mode
CI vi AT&T cursor_invisible
@@ -105,64 +118,72 @@
PU kP XENIX key_ppage
RT @8 XENIX kent
UP ku XENIX kcuu1
-KA k; Tek key_f10
-KB F1 Tek key_f11
-KC F2 Tek key_f12
-KD F3 Tek key_f13
-KE F4 Tek key_f14
-KF F5 Tek key_f15
-BC Sb Tek set_background
-FC Sf Tek set_foreground
-HS mh Iris enter_dim_mode
+KA k; Tektronix key_f10
+KB F1 Tektronix key_f11
+KC F2 Tektronix key_f12
+KD F3 Tektronix key_f13
+KE F4 Tektronix key_f14
+KF F5 Tektronix key_f15
+BC Sb Tektronix set_background
+FC Sf Tektronix set_foreground
+HS mh IRIX enter_dim_mode
.TE
.PP
-XENIX termcap also used to have a set of extension capabilities
-for forms drawing, designed to take advantage of the IBM PC
-high-half graphics.
-They were as follows:
+XENIX \fI\%termcap\fP had a set of extension capabilities,
+corresponding to box drawing characters of CCSID
+(\*(``code page\*('') 437,
+as follows.
.PP
-.TS H
-c c
-l l.
-Cap Graphic
+.TS
+center;
+cb cb
+cb l .
+\f(BItermcap\fP Name Graphic
_
-G2 upper left
-G3 lower left
-G1 upper right
-G4 lower right
-GR pointing right
-GL pointing left
-GU pointing up
-GD pointing down
+G2 upper left corner
+G3 lower left corner
+G1 upper right corner
+G4 lower right corner
+GR tee pointing right
+GL tee pointing left
+GU tee pointing up
+GD tee pointing down
GH horizontal line
GV vertical line
GC intersection
-G6 upper left
-G7 lower left
-G5 upper right
-G8 lower right
-Gr tee pointing right
-Gr tee pointing left
-Gu tee pointing up
-Gd tee pointing down
-Gh horizontal line
-Gv vertical line
-Gc intersection
-GG acs magic cookie count
+G6 double upper left corner
+G7 double lower left corner
+G5 double upper right corner
+G8 double lower right corner
+Gr double tee pointing right
+Gr double tee pointing left
+Gu double tee pointing up
+Gd double tee pointing down
+Gh double horizontal line
+Gv double vertical line
+Gc double intersection
+.\" TODO: There are about 40 box drawing code points in CCSID 437;
+.\" were there no XENIX capabilities for the mixed single- and double-
+.\" line intersections?
+.\"
+.\" TODO: GG doesn't seem to fit with the others; explain it.
+GG ACS magic cookie count
.TE
.PP
-If the single-line capabilities occur in an entry, they will automatically
-be composed into an \fIacsc\fR string.
-The double-line capabilities and
-\fBGG\fR are discarded with a warning message.
+\fB\%@CAPTOINFO@\fP composes single-line capabilities into an \fBacsc\fP
+string,
+and discards \fBGG\fP and double-line capabilities with a warning
+diagnostic.
.PP
-IBM's AIX has a terminfo facility descended from SVr1 terminfo but incompatible
-with the SVr4 format.
-The following AIX extensions are automatically
-translated:
+IBM's AIX has a \fI\%\%term\%info\fP facility descended from SVr1
+\fI\%\%term\%info\fP,
+but which is incompatible with the SVr4 format.
+\fB\%@CAPTOINFO@\fP translates the following AIX extensions.
+.PP
.TS
-c c
-l l.
+center;
+cb cb
+l l .
IBM XSI
_
ksel kslt
@@ -173,28 +194,42 @@
font3 s3ds
.TE
.PP
-Additionally, the AIX \fIbox1\fR capability will be automatically translated to
-an \fIacsc\fR string.
+Additionally,
+this program translates the AIX \fBbox1\fP capability to an \fBacsc\fP
+string.
.PP
-Hewlett-Packard's terminfo library supports two nonstandard terminfo
-capabilities \fImeml\fR (memory lock) and \fImemu\fR (memory unlock).
-These will be discarded with a warning message.
-.SH NOTES
-This utility is actually a link to \fB@TIC@\fR(1M), running in \fI\-I\fR mode.
-You can use other \fB@TIC@\fR options such as \fB\-f\fR and \fB\-x\fR.
+The HP-UX \fI\%\%term\%info\fP library supports two nonstandard
+\fI\%\%term\%info\fP capabilities,
+\fBmeml\fP (memory lock) and \fBmemu\fP (memory unlock).
+\fB\%@CAPTOINFO@\fP discards these with a warning message.
+.SH FILES
+.TP
+.I /etc/termcap
+default \fI\%termcap\fP terminal capability database
+.SH PORTABILITY
+X/Open Curses,
+Issue 7 (2009) describes \fBtic\fP briefly,
+but omits this program.
.PP
-The trace option is not identical to SVr4's.
-Under SVr4, instead of following
-the \fB\-v\fR with a trace level n, you repeat it n times.
-.SH SEE ALSO
-\fB@INFOCMP@\fR(1M),
-\fBcurses\fR(3X),
-\fBterminfo\fR(\*n)
+SVr4 systems provide \fB\%captoinfo\fP as a separate application from
+\fBtic\fP.
+Its
+.B \-v
+option does not accept a trace level argument
+.IR n ;
+repeat
+.B \-v
+.I n
+times instead.
.PP
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
-.SH AUTHOR
+NetBSD does not provide this application.
+.SH AUTHORS
Eric S. Raymond <esr@snark.thyrsus.com>
and
.br
-Thomas E. Dickey <dickey@invisible-island.net>
+Thomas E. Dickey <dickey@invisible\-island.net>
+.SH SEE ALSO
+\fB\%@INFOCMP@\fP(1M),
+\fB\%@TIC@\fP(1M),
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(5)
diff --git a/man/clear.1 b/man/clear.1
index d8e24e5..a1034db 100644
--- a/man/clear.1
+++ b/man/clear.1
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2013 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -26,23 +27,160 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: clear.1,v 1.10 2013/06/22 22:22:11 tom Exp $
-.TH @CLEAR@ 1 ""
-.ds n 5
+.\" $Id: clear.1,v 1.48 2024/03/16 15:35:01 tom Exp $
+.TH @CLEAR@ 1 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.ds ' \(aq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.ie t .ds ' \(aq
+.el .ds ' '
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
+.
.SH NAME
-\fB@CLEAR@\fR \- clear the terminal screen
+\fB\%@CLEAR@\fP \-
+clear the terminal screen
.SH SYNOPSIS
-\fB@CLEAR@\fR
-.br
+.B @CLEAR@
+.RB [ \-x ]
+.RB [ \-T\ \c
+.IR terminal-type ]
+.PP
+.B "@CLEAR@ \-V"
.SH DESCRIPTION
-\fB@CLEAR@\fR clears your screen if this is possible,
-including its scrollback buffer (if the extended "E3" capability is defined).
-\fB@CLEAR@\fR looks in the environment for the terminal type and then in the
-\fBterminfo\fR database to determine how to clear the screen.
+\fB\%@CLEAR@\fP clears your terminal's screen and its scrollback buffer,
+if any.
+\fB\%@CLEAR@\fP retrieves the terminal type from the environment
+variable \fITERM\fP,
+then consults the \fIterminfo\fP terminal capability database entry for
+that type to determine how to perform these actions.
.PP
-\fB@CLEAR@\fR ignores any command-line parameters that may be present.
+The capabilities to clear the screen and scrollback buffer are named
+\*(``clear\*('' and \*(``E3\*('', respectively.
+The latter is a \fIuser-defined capability\fP,
+applying an extension mechanism introduced in \fI\%ncurses\fP 5.0
+(1999).
+.SH OPTIONS
+\fB\%@CLEAR@\fP recognizes the following options.
+.TP 9 \" "-T type" + 2n
+.B \-T \fItype\fP
+produces instructions suitable for the terminal \fItype\fP.
+Normally,
+this option is unnecessary,
+because the terminal type is inferred from the environment variable
+\fITERM\fP.
+If this option is specified,
+\fB\%@CLEAR@\fP ignores the environment variables \fILINES\fP and
+\fI\%COLUMNS\fP as well.
+.TP
+.B \-V
+reports the version of \fI\%ncurses\fP associated with this program and
+exits with a successful status.
+.TP
+.B \-x
+prevents \fB\%@CLEAR@\fP from attempting to clear the scrollback buffer.
+.SH PORTABILITY
+Neither IEEE Std 1003.1/The Open Group Base Specifications Issue 7
+(POSIX.1-2008) nor X/Open Curses Issue 7 documents \fB\%@CLEAR@\fP.
+.PP
+The latter documents \fBtput\fP,
+which could be used to replace this utility either via a shell script or
+by an alias
+(such as a symbolic link)
+to run \fB\%@TPUT@\fP as \fB\%@CLEAR@\fP.
+.SH HISTORY
+A \fBclear\fP command using the \fItermcap\fP database and library
+appeared in 2BSD (1979).
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/clear.c
+Eighth Edition Unix (1985) later included it.
+.PP
+The commercial Unix arm of AT&T adapted a different BSD program
+(\fBtset\fP) to make a new command,
+\fBtput\fP,
+and replaced the \fBclear\fP program with a shell script that called
+\*(``\fBtput clear\fP\*(''.
+.PP
+.RS 4
+.EX
+/usr/bin/tput ${1:+\-T$1} clear 2> /dev/null
+exit
+.EE
+.RE
+.PP
+In 1989, when Keith Bostic revised the BSD \fBtput\fP command
+to make it similar to AT&T's \fBtput\fP,
+he added a \fBclear\fP shell script as well.
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/\
+.\" tput/clear.sh
+.PP
+.RS 4
+.EX
+exec tput clear
+.EE
+.RE
+.PP
+The remainder of the script in each case is a copyright notice.
+.PP
+In 1995,
+\fI\%ncurses\fP's \fBclear\fP began by adapting BSD's original
+\fBclear\fP command to use \fIterminfo\fP.
+The \fBE3\fP extension came later.
+.bP
+In June 1999, \fIxterm\fP provided an extension to the standard control
+sequence for clearing the screen.
+Rather than clearing just the visible part of the screen using
+.RS 8
+.PP
+.EX
+printf \*'\e033[2J\*'
+.EE
+.RE
+.IP
+one could clear the scrollback buffer as well by using
+.RS 8
+.PP
+.EX
+printf \*'\e033[\fB3\fPJ\*'
+.EE
+.RE
+.IP
+instead.
+\*(``XTerm Control Sequences\fP\*('' documents this feature as
+originating with \fIxterm\fP.
+.bP
+A few other terminal emulators adopted it,
+such as PuTTY in 2006.
+.bP
+In April 2011, a Red Hat developer submitted a patch to the Linux
+kernel, modifying its console driver to do the same thing.
+Documentation of this change,
+appearing in Linux 3.0,
+did not mention \fIxterm\fP,
+although that program was cited in the Red Hat bug report (#683733)
+motivating the feature.
+.bP
+Subsequently,
+more terminal developers adopted the feature.
+The next relevant step was to change the \fI\%ncurses\fP \fBclear\fP
+program in 2013 to incorporate this extension.
+.bP
+In 2013,
+the \fBE3\fP capability was not exercised by
+\*(``\fB\%@TPUT@ clear\fP\*(''.
+That oversight was addressed in 2016 by reorganizing \fB\%@TPUT@\fP to
+share its logic with \fB\%@CLEAR@\fP and \fB\%@TSET@\fP.
.SH SEE ALSO
-\fB@TPUT@\fR(1), \fBterminfo\fR(\*n)
-.PP
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
+\fB\%@TPUT@\fP(1),
+\fB\%xterm\fP(1),
+\fB\%terminfo\fP(5)
diff --git a/man/curs_add_wch.3x b/man/curs_add_wch.3x
index 5b744db..d1eb9a3 100644
--- a/man/curs_add_wch.3x
+++ b/man/curs_add_wch.3x
@@ -1,5 +1,7 @@
+'\" t
.\"***************************************************************************
-.\" Copyright (c) 2001-2012,2015 Free Software Foundation, Inc. *
+.\" Copyright 2019-2023,2024 Thomas E. Dickey *
+.\" Copyright 2001-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 *
@@ -26,37 +28,45 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_add_wch.3x,v 1.16 2015/07/20 23:44:56 tom Exp $
-.TH curs_add_wch 3X ""
+.\" $Id: curs_add_wch.3x,v 1.62 2024/04/20 21:20:07 tom Exp $
+.TH curs_add_wch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.SH NAME
-\fBadd_wch\fP,
-\fBwadd_wch\fP,
-\fBmvadd_wch\fP,
-\fBmvwadd_wch\fP,
-\fBecho_wchar\fP,
-\fBwecho_wchar\fP \- add a complex character and rendition to a \fBcurses\fR window, then advance the cursor
+\fB\%add_wch\fP,
+\fB\%wadd_wch\fP,
+\fB\%mvadd_wch\fP,
+\fB\%mvwadd_wch\fP,
+\fB\%echo_wchar\fP,
+\fB\%wecho_wchar\fP \-
+add a \fIcurses\fR complex character to a window and advance the cursor
.SH SYNOPSIS
+.nf
+\fB#include <curses.h>
.PP
-\fB#include <curses.h>\fP
-.sp
-.B "int add_wch( const cchar_t *\fIwch\fB );"
-.br
-.B "int wadd_wch( WINDOW *\fIwin\fP, const cchar_t *\fIwch\fB );"
-.br
-.B "int mvadd_wch( int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fB );"
-.br
-.B "int mvwadd_wch( WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fB );"
-.br
-.B "int echo_wchar( const cchar_t *\fIwch\fB );"
-.br
-.B "int wecho_wchar( WINDOW *\fIwin\fP, const cchar_t *\fIwch\fB );"
-.br
+\fBint add_wch(const cchar_t *\fIwch\fP);
+\fBint wadd_wch(WINDOW *\fIwin\fP, const cchar_t *\fIwch\fP);
+\fBint mvadd_wch(int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fP);
+\fBint mvwadd_wch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fP);
+.PP
+\fBint echo_wchar(const cchar_t *\fIwch\fP);
+\fBint wecho_wchar(WINDOW *\fIwin\fP, const cchar_t *\fIwch\fP);
+.fi
.SH DESCRIPTION
.SS add_wch
-.PP
The
\fBadd_wch\fP,
\fBwadd_wch\fP,
@@ -72,25 +82,31 @@
then any previous character at that location is removed.
A new character specified by \fIwch\fP is
placed at that location with rendition specified by \fIwch\fP.
-The cursor then advances to
-the next spacing character on the screen.
+The cursor then advances after this spacing character,
+to prepare for writing the next character on the screen.
+.IP
+The newly added spacing character is the base of the active complex character.
+Subsequent non-spacing characters can be combined with this base
+until another spacing character is written to the screen,
+or the cursor is moved, e.g., using \fBwmove\fP.
.bP
If \fIwch\fP refers to a non-spacing character,
-all previous characters at that location are preserved.
-The non-spacing characters of \fIwch\fP
-are added to the spacing complex character,
-and the rendition specified by \fIwch\fP is ignored.
+it is appended to the active complex character,
+retaining the previous characters at that location.
+The rendition specified by \fIwch\fP is ignored.
+.IP
+The cursor is not advanced after adding a non-spacing character.
+Subsequent calls to add non-spacing characters will update the same position.
.bP
If the character part of \fIwch\fP is
a tab, newline, backspace or other control character,
-the window is updated and the cursor moves as if \fBaddch\fR were called.
+the window is updated and the cursor moves as if \fBaddch\fP were called.
.SS echo_wchar
-.PP
The \fBecho_wchar\fP
function is functionally equivalent to a call to
\fBadd_wch\fP
followed by a call to
-\fBrefresh\fP.
+\fB\%refresh\fP(3X).
Similarly, the
\fBwecho_wchar\fP
is functionally equivalent to a call to
@@ -101,92 +117,207 @@
that only a single character is being output is taken into consideration and,
for non-control characters, a considerable performance gain might be seen
by using the *\fBecho\fP* functions instead of their equivalents.
-.SS Line Graphics
-Like \fBaddch\fP(3X),
+.SS "Line Graphics"
+Like \fB\%addch\fP(3X),
\fBaddch_wch\fP accepts symbols which make it simple to draw lines and other
frequently used special characters.
These symbols correspond to the same VT100 line-drawing set as
-\fBaddch\fP(3X).
+\fB\%addch\fP(3X).
.PP
.TS
-l l l l
-_ _ _ _
-lw(1.5i) lw7 lw7 lw20.
-\fIName\fR \fIUnicode\fP \fIDefault\fR \fIDescription\fR
-WACS_BLOCK 0x25ae # solid square block
-WACS_BOARD 0x2592 # board of squares
-WACS_BTEE 0x2534 + bottom tee
-WACS_BULLET 0x00b7 o bullet
-WACS_CKBOARD 0x2592 : checker board (stipple)
-WACS_DARROW 0x2193 v arrow pointing down
-WACS_DEGREE 0x00b0 ' degree symbol
-WACS_DIAMOND 0x25c6 + diamond
-WACS_GEQUAL 0x2265 > greater-than-or-equal-to
-WACS_HLINE 0x2500 \- horizontal line
-WACS_LANTERN 0x2603 # lantern symbol
-WACS_LARROW 0x2190 < arrow pointing left
-WACS_LEQUAL 0x2264 < less-than-or-equal-to
-WACS_LLCORNER 0x2514 + lower left-hand corner
-WACS_LRCORNER 0x2518 + lower right-hand corner
-WACS_LTEE 0x2524 + left tee
-WACS_NEQUAL 0x2260 ! not-equal
-WACS_PI 0x03c0 * greek pi
-WACS_PLMINUS 0x00b1 # plus/minus
-WACS_PLUS 0x253c + plus
-WACS_RARROW 0x2192 > arrow pointing right
-WACS_RTEE 0x251c + right tee
-WACS_S1 0x23ba \- scan line 1
-WACS_S3 0x23bb \- scan line 3
-WACS_S7 0x23bc \- scan line 7
-WACS_S9 0x23bd \&_ scan line 9
-WACS_STERLING 0x00a3 f pound-sterling symbol
-WACS_TTEE 0x252c + top tee
-WACS_UARROW 0x2191 ^ arrow pointing up
-WACS_ULCORNER 0x250c + upper left-hand corner
-WACS_URCORNER 0x2510 + upper right-hand corner
-WACS_VLINE 0x2502 | vertical line
+Lb Lb Lb Lb Lb
+Lb Lb Lb Lb Lb
+Lb L L L Lx.
+\& Unicode ASCII acsc \&
+ACS Name Default Default Char Glyph Name
+_
+WACS_BLOCK 0x25ae # 0 T{
+solid square block
+T}
+WACS_BOARD 0x2592 # h board of squares
+WACS_BTEE 0x2534 + v bottom tee
+WACS_BULLET 0x00b7 o ~ bullet
+WACS_CKBOARD 0x2592 : a T{
+checker board (stipple)
+T}
+WACS_DARROW 0x2193 v . T{
+arrow pointing down
+T}
+WACS_DEGREE 0x00b0 ' f degree symbol
+WACS_DIAMOND 0x25c6 + \(ga diamond
+WACS_GEQUAL 0x2265 > > T{
+greater-than-or-equal-to
+T}
+WACS_HLINE 0x2500 \- q horizontal line
+WACS_LANTERN 0x2603 # i lantern symbol
+WACS_LARROW 0x2190 < , T{
+arrow pointing left
+T}
+WACS_LEQUAL 0x2264 < y T{
+less-than-or-equal-to
+T}
+WACS_LLCORNER 0x2514 + m T{
+lower left-hand corner
+T}
+WACS_LRCORNER 0x2518 + j T{
+lower right-hand corner
+T}
+WACS_LTEE 0x2524 + t left tee
+WACS_NEQUAL 0x2260 ! | not-equal
+WACS_PI 0x03c0 * { greek pi
+WACS_PLMINUS 0x00b1 # g plus/minus
+WACS_PLUS 0x253c + n plus
+WACS_RARROW 0x2192 > + T{
+arrow pointing right
+T}
+WACS_RTEE 0x251c + u right tee
+WACS_S1 0x23ba \- o scan line 1
+WACS_S3 0x23bb \- p scan line 3
+WACS_S7 0x23bc \- r scan line 7
+WACS_S9 0x23bd \&_ s scan line 9
+WACS_STERLING 0x00a3 f } T{
+pound-sterling symbol
+T}
+WACS_TTEE 0x252c + w top tee
+WACS_UARROW 0x2191 ^ \- T{
+arrow pointing up
+T}
+WACS_ULCORNER 0x250c + l T{
+upper left-hand corner
+T}
+WACS_URCORNER 0x2510 + k T{
+upper right-hand corner
+T}
+WACS_VLINE 0x2502 | x vertical line
.TE
.PP
-The wide-character configuration of ncurses also defines symbols
-for thick- and double-lines:
+The wide-character configuration of \fI\%ncurses\fP also defines symbols
+for thick lines (\fBacsc\fP \*(``J\*('' to \*(``V\*(''):
.PP
.TS
-l l l l
-_ _ _ _
-lw(1.5i) lw7 lw7 lw20.
-\fIName\fR \fIUnicode\fP \fIDefault\fR \fIDescription\fR
-WACS_T_ULCORNER 0x250f + thick upper left corner
-WACS_T_LLCORNER 0x2517 + thick lower left corner
-WACS_T_URCORNER 0x2513 + thick upper right corner
-WACS_T_LRCORNER 0x251b + thick lower right corner
-WACS_T_LTEE 0x252b + thick tee pointing right
-WACS_T_RTEE 0x2523 + thick tee pointing left
-WACS_T_BTEE 0x253b + thick tee pointing up
-WACS_T_TTEE 0x2533 + thick tee pointing down
-WACS_T_HLINE 0x2501 - thick horizontal line
-WACS_T_VLINE 0x2503 | thick vertical line
-WACS_T_PLUS 0x254b + thick large plus or crossover
-WACS_D_ULCORNER 0x2554 + double upper left corner
-WACS_D_LLCORNER 0x255a + double lower left corner
-WACS_D_URCORNER 0x2557 + double upper right corner
-WACS_D_LRCORNER 0x255d + double lower right corner
-WACS_D_RTEE 0x2563 + double tee pointing left
-WACS_D_LTEE 0x2560 + double tee pointing right
-WACS_D_BTEE 0x2569 + double tee pointing up
-WACS_D_TTEE 0x2566 + double tee pointing down
-WACS_D_HLINE 0x2550 - double horizontal line
-WACS_D_VLINE 0x2551 | double vertical line
-WACS_D_PLUS 0x256c + double large plus or crossover
+Lb Lb Lb Lb Lb
+Lb Lb Lb Lb Lb
+Lb L L L Lx.
+\& Unicode ASCII acsc \&
+ACS Name Default Default Char Glyph Name
+_
+WACS_T_BTEE 0x253b + V T{
+thick tee pointing up
+T}
+WACS_T_HLINE 0x2501 - Q T{
+thick horizontal line
+T}
+WACS_T_LLCORNER 0x2517 + M T{
+thick lower left corner
+T}
+WACS_T_LRCORNER 0x251b + J T{
+thick lower right corner
+T}
+WACS_T_LTEE 0x252b + T T{
+thick tee pointing right
+T}
+WACS_T_PLUS 0x254b + N T{
+thick large plus
+T}
+WACS_T_RTEE 0x2523 + U T{
+thick tee pointing left
+T}
+WACS_T_TTEE 0x2533 + W T{
+thick tee pointing down
+T}
+WACS_T_ULCORNER 0x250f + L T{
+thick upper left corner
+T}
+WACS_T_URCORNER 0x2513 + K T{
+thick upper right corner
+T}
+WACS_T_VLINE 0x2503 | X T{
+thick vertical line
+T}
.TE
+.PP
+and for double-lines (\fBacsc\fP \*(``A\*('' to \*(``I\*(''):
+.PP
+.TS
+Lb Lb Lb Lb Lb
+Lb Lb Lb Lb Lb
+Lb L L L Lx.
+\& Unicode ASCII acsc \&
+ACS Name Default Default Char Glyph Name
+_
+WACS_D_BTEE 0x2569 + H T{
+double tee pointing up
+T}
+WACS_D_HLINE 0x2550 - R T{
+double horizontal line
+T}
+WACS_D_LLCORNER 0x255a + D T{
+double lower left corner
+T}
+WACS_D_LRCORNER 0x255d + A T{
+double lower right corner
+T}
+WACS_D_LTEE 0x2560 + F T{
+double tee pointing right
+T}
+WACS_D_PLUS 0x256c + E T{
+double large plus
+T}
+WACS_D_RTEE 0x2563 + G T{
+double tee pointing left
+T}
+WACS_D_TTEE 0x2566 + I T{
+double tee pointing down
+T}
+WACS_D_ULCORNER 0x2554 + C T{
+double upper left corner
+T}
+WACS_D_URCORNER 0x2557 + B T{
+double upper right corner
+T}
+WACS_D_VLINE 0x2551 | Y T{
+double vertical line
+T}
+.TE
+.PP
+Unicode's descriptions for these characters differs slightly from
+\fI\%ncurses\fP,
+by introducing the term \*(``light\*('' (along with less important details).
+Here are its descriptions for the normal, thick, and double horizontal lines:
+.bP
+U+2500 BOX DRAWINGS LIGHT HORIZONTAL
+.bP
+U+2501 BOX DRAWINGS HEAVY HORIZONTAL
+.bP
+U+2550 BOX DRAWINGS DOUBLE HORIZONTAL
.SH RETURN VALUE
+All routines return the integer \fBERR\fP upon failure and \fBOK\fP on success.
.PP
-All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success.
+X/Open Curses does not specify any error conditions.
+This implementation returns an error
+.bP
+if the window pointer is null or
+.bP
+if it is not possible to add a complete character in the window.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+The latter may be due to different causes:
+.bP
+If \fB\%scrollok\fP(3X) is not enabled,
+writing a character at the lower right margin succeeds.
+However,
+an error is returned because it is not possible to wrap to a new line.
+.bP
+If an error is detected when converting a multibyte character to a sequence
+of bytes,
+or if it is not possible to add all of the resulting bytes in the window,
+an error is returned.
+.PP
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
-.PP
Note that
\fBadd_wch\fP,
\fBmvadd_wch\fP,
@@ -194,34 +325,125 @@
\fBecho_wchar\fP
may be macros.
.SH PORTABILITY
-.PP
-All of these functions are described in the XSI Curses standard, Issue 4.
+These functions are described in X/Open Curses, Issue 4.
The defaults specified for line-drawing characters apply in the POSIX locale.
-.PP
+.SS "WACS Symbols"
X/Open Curses makes it clear that the WACS_ symbols should be defined as
-a pointer to \fBcchar_t\fP data, e.g., in the discussion of \fBborder_set\fR.
+a pointer to \fBcchar_t\fP data, e.g., in the discussion of \fBborder_set\fP.
A few implementations are problematic:
.bP
NetBSD curses defines the symbols as a \fBwchar_t\fP within a \fBcchar_t\fP.
.bP
-HPUX curses equates some of the \fIACS_\fP symbols
-to the analogous \fIWACS_\fP symbols as if the \fIACS_\fP symbols were
+HP-UX curses equates some of the \fBACS_\fP symbols
+to the analogous \fBWACS_\fP symbols as if the \fBACS_\fP symbols were
wide characters.
The misdefined symbols are the arrows
and other symbols which are not used for line-drawing.
.PP
-X/Open Curses does not define symbols for thick- or double-lines.
+X/Open Curses does not specify symbols for thick- or double-lines.
SVr4 curses implementations defined their line-drawing symbols in
terms of intermediate symbols.
This implementation extends those symbols, providing new definitions
which are not in the SVr4 implementations.
-.SH SEE ALSO
-.na
.PP
-\fBcurses\fR(3X),
-\fBcurs_addch\fR(3X),
-\fBcurs_attr\fR(3X),
-\fBcurs_clear\fR(3X),
-\fBcurs_outopts\fR(3X),
-\fBcurs_refresh\fR(3X),
-\fBputwc\fR(3)
+Not all Unicode-capable terminals provide support for VT100-style
+alternate character sets (i.e., the \fBacsc\fP capability),
+with their corresponding line-drawing characters.
+X/Open Curses did not address the aspect of integrating Unicode with
+line-drawing characters.
+Existing implementations of Unix curses (AIX, HP-UX, Solaris)
+use only the \fBacsc\fP character-mapping to provide this feature.
+As a result, those implementations can only use single-byte line-drawing
+characters.
+\fI\%ncurses\fP 5.3 (2002) provided a table of Unicode values to solve
+these problems.
+NetBSD curses incorporated that table in 2010.
+.PP
+In this implementation, the Unicode values are used instead of the
+terminal description's \fBacsc\fP mapping as discussed in
+\fB\%ncurses\fP(3X) for the environment variable
+\fINCURSES_NO_UTF8_ACS\fP.
+In contrast, for the same cases, the line-drawing characters
+described in \fB\%addch\fP(3X) will use only the ASCII default values.
+.PP
+Having Unicode available does not solve all of the problems with
+line-drawing for curses:
+.bP
+The closest Unicode equivalents to the
+VT100 graphics \fIS1\fP, \fIS3\fP, \fIS7\fP and \fIS9\fP
+frequently are not displayed at
+the regular intervals which the terminal used.
+.bP
+The \fIlantern\fP is a special case.
+It originated with the AT&T 4410 terminal in the early 1980s.
+There is no accessible documentation depicting the lantern symbol
+on the AT&T terminal.
+.IP
+Lacking documentation, most readers assume that a \fIstorm lantern\fP
+was intended.
+But there are several possibilities, all with problems.
+.IP
+Unicode 6.0 (2010) does provide two lantern symbols: U+1F383 and U+1F3EE.
+Those were not available in 2002, and are irrelevant since
+they lie outside the BMP and as a result are not generally available
+in terminals.
+They are not storm lanterns, in any case.
+.IP
+Most \fIstorm lanterns\fP have a tapering glass chimney
+(to guard against tipping);
+some have a wire grid protecting the chimney.
+.IP
+For the tapering appearance, \[u2603] U+2603 was adequate.
+In use on a terminal, no one can tell what the image represents.
+Unicode calls it a snowman.
+.IP
+Others have suggested these alternatives:
+\[sc] U+00A7 (section mark),
+\[u0398] U+0398 (theta),
+\[u03A6] U+03A6 (phi),
+\[u03B4] U+03B4 (delta),
+\[u2327] U+2327 (x in a rectangle),
+\[u256C] U+256C (forms double vertical and horizontal), and
+\[u2612] U+2612 (ballot box with x).
+.SS "Complex Characters"
+The complex character type \fBcchar_t\fR
+can store more than one wide character (\fBwchar_t\fR).
+The X/Open Curses description does not mention this possibility,
+describing only the cases where \fIwch\fP is a spacing character
+or a non-spacing character.
+.PP
+This implementation assumes that \fIwch\fP is constructed using
+\fB\%setcchar\fP(3X), and in turn that the result
+.bP
+contains at most one spacing character in the beginning of its list of wide
+characters,
+and zero or more non-spacing characters
+or
+.bP
+may hold one non-spacing character.
+.PP
+In the latter case,
+\fI\%ncurses\fP adds the non-spacing character to the active
+(base) spacing character.
+.SS TABSIZE
+The
+.B TABSIZE
+variable is implemented in SVr4 and other versions of
+.IR curses ,
+but is not specified by X/Open Curses
+(see \fBcurs_variables\fP(3X)).
+.SH SEE ALSO
+\fB\%curs_addch\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its non-wide-character configuration.
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_addwstr\fP(3X),
+\fB\%curs_add_wchstr\fP(3X),
+\fB\%curs_attr\fP(3X),
+\fB\%curs_clear\fP(3X),
+\fB\%curs_getcchar\fP(3X),
+\fB\%curs_outopts\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_variables\fP(3X),
+\fB\%putwc\fP(3)
diff --git a/man/curs_add_wchstr.3x b/man/curs_add_wchstr.3x
index 37e3df6..5dd3e8f 100644
--- a/man/curs_add_wchstr.3x
+++ b/man/curs_add_wchstr.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright 2019-2023,2024 Thomas E. Dickey *
+.\" Copyright 2002-2012,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 *
@@ -26,57 +27,61 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_add_wchstr.3x,v 1.10 2012/11/03 22:54:43 tom Exp $
-.TH curs_add_wchstr 3X ""
+.\" $Id: curs_add_wchstr.3x,v 1.39 2024/04/20 21:20:07 tom Exp $
+.TH curs_add_wchstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.na
-.hy 0
.SH NAME
-\fBadd_wchstr\fR,
-\fBadd_wchnstr\fR,
-\fBwadd_wchstr\fR,
-\fBwadd_wchnstr\fR,
-\fBmvadd_wchstr\fR,
-\fBmvadd_wchnstr\fR,
-\fBmvwadd_wchstr\fR,
-\fBmvwadd_wchnstr\fR \- add an array of complex characters (and attributes) to a curses window
-.ad
-.hy
+\fB\%add_wchstr\fP,
+\fB\%add_wchnstr\fP,
+\fB\%wadd_wchstr\fP,
+\fB\%wadd_wchnstr\fP,
+\fB\%mvadd_wchstr\fP,
+\fB\%mvadd_wchnstr\fP,
+\fB\%mvwadd_wchstr\fP,
+\fB\%mvwadd_wchnstr\fP \-
+add a \fIcurses\fR complex character string to a window
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fR
+\fB#include <curses.h>
.PP
-\fBint add_wchstr(const cchar_t *\fR\fIwchstr\fR\fB);\fR
-.br
-\fBint add_wchnstr(const cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint wadd_wchstr(WINDOW *\fR \fIwin\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB);\fR
-.br
-\fBint wadd_wchnstr(WINDOW *\fR \fIwin\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint mvadd_wchstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB);\fR
-.br
-\fBint mvadd_wchnstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint mvwadd_wchstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB);\fR
-.br
-\fBint mvwadd_wchnstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR
+\fBint add_wchstr(const cchar_t *\fIwchstr\fP);
+\fBint wadd_wchstr(WINDOW * \fIwin\fP, const cchar_t *\fIwchstr\fP);
+\fBint mvadd_wchstr(int \fIy\fP, int \fIx\fP, const cchar_t *\fIwchstr\fP);
+\fBint mvwadd_wchstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwchstr\fP);
+.PP
+\fBint add_wchnstr(const cchar_t *\fIwchstr\fP, int \fIn\fP);
+\fBint wadd_wchnstr(WINDOW * \fIwin\fP, const cchar_t *\fIwchstr\fP, int \fIn\fP);
+\fBint mvadd_wchnstr(int \fIy\fP, int \fIx\fP, const cchar_t *\fIwchstr\fP, int \fIn\fP);
+\fBint mvwadd_wchnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwchstr\fP, int \fIn\fP);
.fi
.SH DESCRIPTION
These functions copy the (null-terminated)
-array of complex characters \fIwchstr\fR
+array of complex characters \fIwchstr\fP
into the window image structure
starting at the current cursor position.
-The four functions with \fIn\fR as the last
-argument copy at most \fIn\fR elements,
+.PP
+The four functions with \fIn\fP as the last
+argument copy at most \fIn\fP elements,
but no more than will fit on the line.
-If \fBn\fR=\fB\-1\fR then the whole array is copied,
+If \fBn\fP=\fB\-1\fP then the whole array is copied,
to the maximum number of characters that will fit on the line.
.PP
-The window cursor is \fInot\fR advanced.
-These functions work faster than \fBwaddnstr\fR.
+The window cursor is \fInot\fP advanced.
+These functions are faster than \fBwaddnstr\fP.
On the other hand:
.bP
they do not perform checking
@@ -90,28 +95,34 @@
rather than wrapping it around to the new line.
.PP
These functions end successfully
-on encountering a null \fIcchar_t\fR, or
+on encountering a null \fBcchar_t\fP, or
when they have filled the current line.
If a complex character cannot completely fit at the end of the current line,
the remaining columns are filled with the background character and rendition.
.SH RETURN VALUE
-All functions return the integer \fBERR\fR upon failure and \fBOK\fR on success.
+All functions return the integer \fBERR\fP upon failure and \fBOK\fP on success.
.PP
-X/Open does not define any error conditions.
+X/Open Curses does not specify any error conditions.
This implementation returns an error
-if the window pointer is null.
+.bP
+if the \fIwin\fP parameter is null or
+.bP
+if the \fIwchstr\fP parameter is null.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
-All functions except \fBwadd_wchnstr\fR may be macros.
+All functions except \fBwadd_wchnstr\fP may be macros.
.SH PORTABILITY
-These entry points are described in the XSI Curses standard, Issue 4.
+These functions are described in X/Open Curses, Issue 4.
.SH SEE ALSO
-\fBcurs_addwstr\fR(3X),
-\fBcurses\fR(3X).
+\fB\%curs_addchstr\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its non-wide-character configuration.
.PP
-Comparable functions in the narrow-character (ncurses) library are
-described in
-\fBcurs_addchstr\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_addwstr\fP(3X),
+\fB\%curs_add_wch\fP(3X)
diff --git a/man/curs_addch.3x b/man/curs_addch.3x
index 15d859b..ad54852 100644
--- a/man/curs_addch.3x
+++ b/man/curs_addch.3x
@@ -1,6 +1,7 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2014,2015 Free Software Foundation, Inc. *
+.\" 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 *
.\" copy of this software and associated documentation files (the *
@@ -27,180 +28,450 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addch.3x,v 1.36 2015/07/16 09:14:44 tom Exp $
-.TH curs_addch 3X ""
+.\" $Id: curs_addch.3x,v 1.85 2024/04/20 19:03:47 tom Exp $
+.TH curs_addch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.ds ' \(aq
+.ds ^ \(ha
+.ds ~ \(ti
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.ds ' '
+.ds ^ ^
+.ds ~ ~
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.SH NAME
-\fBaddch\fR,
-\fBwaddch\fR,
-\fBmvaddch\fR,
-\fBmvwaddch\fR,
-\fBechochar\fR,
-\fBwechochar\fR \- add a character (with attributes) to a \fBcurses\fR window, then advance the cursor
+\fB\%addch\fP,
+\fB\%waddch\fP,
+\fB\%mvaddch\fP,
+\fB\%mvwaddch\fP,
+\fB\%echochar\fP,
+\fB\%wechochar\fP \-
+add a \fIcurses\fP character to a window and advance the cursor
.SH SYNOPSIS
-\fB#include <curses.h>\fR
+.nf
+\fB#include <curses.h>
.PP
-\fBint addch(const chtype ch);\fR
-.br
-\fBint waddch(WINDOW *win, const chtype ch);\fR
-.br
-\fBint mvaddch(int y, int x, const chtype ch);\fR
-.br
-\fBint mvwaddch(WINDOW *win, int y, int x, const chtype ch);\fR
-.br
-\fBint echochar(const chtype ch);\fR
-.br
-\fBint wechochar(WINDOW *win, const chtype ch);\fR
-.br
+\fBint addch(const chtype \fIch\fP);
+\fBint waddch(WINDOW *\fIwin\fP, const chtype \fIch\fP);
+\fBint mvaddch(int \fIy\fP, int \fIx\fP, const chtype \fIch\fP);
+\fBint mvwaddch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const chtype \fIch\fP);
+.PP
+\fBint echochar(const chtype \fIch\fP);
+\fBint wechochar(WINDOW *\fIwin\fP, const chtype \fIch\fP);
+.fi
.SH DESCRIPTION
-.SS Adding characters
-The \fBaddch\fR, \fBwaddch\fR, \fBmvaddch\fR and \fBmvwaddch\fR routines put
-the character \fIch\fR into the given window at its current window position,
-which is then advanced. They are analogous to \fBputchar\fR in \fBstdio\fR(3).
-If the advance is at the right margin:
-.bP
-The cursor automatically wraps to the beginning of the next line.
-.bP
-At the bottom of the current scrolling region,
-and if \fBscrollok\fR is enabled,
-the scrolling region is scrolled up one line.
-.bP
-If \fBscrollok\fR is not enabled,
-writing a character at the lower right margin succeeds.
-However, an error is returned because
-it is not possible to wrap to a new line
+.SS "Adding Characters"
+.B \%waddch
+puts the character
+.I ch
+at the cursor position of window
+.IR win ,
+then advances the cursor position,
+analogously to the standard C library's \fI\%putchar\fP(3).
+\fB\%ncurses\fP(3X) describes the variants of this function.
.PP
-If \fIch\fR is a tab, newline, carriage return or backspace,
-the cursor is moved appropriately within the window:
+If advancement occurs at the right margin,
.bP
-Backspace moves the cursor one character left; at the left
-edge of a window it does nothing.
+the cursor automatically wraps to the beginning of the next line;
+and
.bP
-Carriage return moves the cursor to the window left margin on the current line.
-.bP
-Newline does a \fBclrtoeol\fR,
-then moves the cursor to the window left margin on the next line,
-scrolling the window if on the last line.
-.bP
-Tabs are considered to be at every eighth column.
-The tab interval may be altered by setting the \fBTABSIZE\fR variable.
+at the bottom of the current scrolling region,
+and if \fB\%scrollok\fP(3X) is enabled for
+.IR win ,
+the scrolling region scrolls up one line.
.PP
-If \fIch\fR is any other control character, it
-is drawn in \fB^\fR\fIX\fR notation. Calling \fBwinch\fR after adding a
-control character does not return the character itself, but instead returns
-the ^-representation of the control character.
+If
+.I ch
+is a
+backspace,
+carriage return,
+line feed,
+or
+tab,
+the cursor moves appropriately within the window.
+.bP
+Backspace moves the cursor one character left;
+at the left margin of a window,
+it does nothing.
+.bP
+Carriage return moves the cursor to the left margin on the current line
+of the window.
+.bP
+Line feed does a \fB\%clrtoeol\fP(3X),
+then moves the cursor to the left margin on the next line of the window,
+and if \fB\%scrollok\fP(3X) is enabled for
+.IR win ,
+scrolls the window if the cursor was already on the last line.
+.bP
+Tab advances the cursor to the next tab stop
+(possibly on the next line);
+these are placed at every eighth column by default.
+Alter the tab interval with the
+.B \%TABSIZE
+extension;
+see \fB\%curs_variables\fP(3X).
.PP
-Video attributes can be combined with a character argument passed to
-\fBaddch\fR or related functions by logical-ORing them into the character.
-(Thus, text, including attributes, can be copied from one place to another
-using \fBinch\fR and \fBaddch\fR.) See the \fBcurs_attr\fR(3X) page for
-values of predefined video attribute constants that can be usefully OR'ed
-into characters.
-.SS Echoing characters
+If
+.I ch
+is any other nonprintable character,
+it is drawn in printable form,
+using the same convention as \fB\%unctrl\fP(3X).
.PP
-The \fBechochar\fR and \fBwechochar\fR routines are equivalent to a call to
-\fBaddch\fR followed by a call to \fBrefresh\fR, or a call to \fBwaddch\fR
-followed by a call to \fBwrefresh\fR. The knowledge that only a single
-character is being output is used and, for non-control characters, a
-considerable performance gain may be seen by using these routines instead of
-their equivalents.
-.SS Line Graphics
-The following variables may be used to add line drawing characters to the
-screen with routines of the \fBaddch\fR family. The default character listed
-below is used if the \fBacsc\fR capability does not define a terminal-specific
-replacement for it.
-The names are taken from VT100 nomenclature.
+Calling \fB\%winch\fP(3X) on the location of a nonprintable character
+does not return the character itself,
+but its \fB\%unctrl\fP(3X) representation.
+.PP
+.I ch
+may contain rendering and/or color attributes,
+and others can be combined with the parameter
+by logically \*(``or\*(''ing with it.
+(A character with its attributes can be copied from place to place
+using \fB\%winch\fP(3X) and
+.BR \%waddch .)
+See \fB\%curs_attr\fP(3X) for values of predefined video attribute
+constants that can be usefully \*(``or\*(''ed with characters.
+.SS "Echoing Characters"
+.B \%echochar
+and
+.B \%wechochar
+are equivalent to calling
+.RB \%( w ) addch
+followed by
+.RB \%( w ) refresh .
+.I curses
+interprets these functions as a hint that only a single character is
+being output;
+for non-control characters,
+a considerable performance gain may be enjoyed by employing them.
+.\" TODO: Combine the following with the "Line Drawing" subsection of
+.\" terminfo(5) and replace this with a cross reference there.
+.SS "Forms-Drawing Characters"
+.I curses
+defines macros starting with
+.B \%ACS_
+that can be used with
+.B \%waddch
+to write line-drawing and other special characters to the screen.
+.I \%ncurses
+terms these
+.I "forms-drawing characters."
+The ACS default listed below is used if the
+.B \%acs_chars
+.RB ( \%acsc )
+.I \%term\%info
+capability does not define a terminal-specific replacement for it,
+or if the terminal and locale configuration requires Unicode to access
+these characters but the library is unable to use Unicode.
+The \*(``acsc char\*('' column corresponds to how the characters are
+specified in the
+.B \%acs_chars
+string capability,
+and the characters in it may appear on the screen if the terminal's
+database entry incorrectly advertises ACS support.
+The name \*(``ACS\*('' originates in the Alternate Character Set feature
+of the DEC VT100 terminal.
.PP
.TS
-l l l
-_ _ _
-l l l.
-\fIName\fR \fIDefault\fR \fIDescription\fR
-ACS_BLOCK # solid square block
-ACS_BOARD # board of squares
-ACS_BTEE + bottom tee
-ACS_BULLET o bullet
-ACS_CKBOARD : checker board (stipple)
-ACS_DARROW v arrow pointing down
-ACS_DEGREE ' degree symbol
-ACS_DIAMOND + diamond
-ACS_GEQUAL > greater-than-or-equal-to
-ACS_HLINE \- horizontal line
-ACS_LANTERN # lantern symbol
-ACS_LARROW < arrow pointing left
-ACS_LEQUAL < less-than-or-equal-to
-ACS_LLCORNER + lower left-hand corner
-ACS_LRCORNER + lower right-hand corner
-ACS_LTEE + left tee
-ACS_NEQUAL ! not-equal
-ACS_PI * greek pi
-ACS_PLMINUS # plus/minus
-ACS_PLUS + plus
-ACS_RARROW > arrow pointing right
-ACS_RTEE + right tee
-ACS_S1 \- scan line 1
-ACS_S3 \- scan line 3
-ACS_S7 \- scan line 7
-ACS_S9 \&_ scan line 9
-ACS_STERLING f pound-sterling symbol
-ACS_TTEE + top tee
-ACS_UARROW ^ arrow pointing up
-ACS_ULCORNER + upper left-hand corner
-ACS_URCORNER + upper right-hand corner
-ACS_VLINE | vertical line
+Lb Lb Lb Lb
+Lb Lb Lb Lb
+Lb L L Lx.
+\& ACS acsc \&
+Symbol Default char Glyph Name
+_
+ACS_BLOCK # 0 solid square block
+ACS_BOARD # h board of squares
+ACS_BTEE + v bottom tee
+ACS_BULLET o \*~ bullet
+ACS_CKBOARD : a checker board (stipple)
+ACS_DARROW v . arrow pointing down
+ACS_DEGREE \*' f degree symbol
+ACS_DIAMOND + \(ga diamond
+ACS_GEQUAL > > greater-than-or-equal-to
+ACS_HLINE \- q horizontal line
+ACS_LANTERN # i lantern symbol
+ACS_LARROW < , arrow pointing left
+ACS_LEQUAL < y less-than-or-equal-to
+ACS_LLCORNER + m lower left-hand corner
+ACS_LRCORNER + j lower right-hand corner
+ACS_LTEE + t left tee
+ACS_NEQUAL ! | not-equal
+ACS_PI * { greek pi
+ACS_PLMINUS # g plus/minus
+ACS_PLUS + n plus
+ACS_RARROW > + arrow pointing right
+ACS_RTEE + u right tee
+ACS_S1 \- o scan line 1
+ACS_S3 \- p scan line 3
+ACS_S7 \- r scan line 7
+ACS_S9 \&_ s scan line 9
+ACS_STERLING f } pound-sterling symbol
+ACS_TTEE + w top tee
+ACS_UARROW \*^ \- arrow pointing up
+ACS_ULCORNER + l upper left-hand corner
+ACS_URCORNER + k upper right-hand corner
+ACS_VLINE | x vertical line
.TE
.SH RETURN VALUE
-All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success
-(the SVr4 manuals specify only "an integer value other than \fBERR\fR") upon
-successful completion, unless otherwise noted in the preceding routine
-descriptions.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+In
+.IR \%ncurses ,
+.B \%waddch
+returns
+.B ERR
+if it is not possible to add a complete character at the cursor
+position,
+as when conversion of a multibyte character to a byte sequence fails,
+or at least one of the resulting bytes cannot be added to the window.
+See section \*(``PORTABILITY\*('' below regarding the use of
+.B \%waddch
+with multibyte characters.
+.PP
+.B \%waddch
+can successfully write a character at the bottom right location of the
+window.
+However,
+.I \%ncurses
+returns
+.B ERR
+if \fB\%scrollok\fP(3X) is not enabled in that event,
+because it is not possible to wrap to a new line.
+.PP
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
-Note that \fBaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR, and
-\fBechochar\fR may be macros.
+.BR \%addch ,
+.BR \%mvaddch ,
+.BR \%mvwaddch ,
+and
+.B \%echochar
+may be implemented as macros.
.SH PORTABILITY
-All these functions are described in the XSI Curses standard, Issue 4.
-The defaults specified for forms-drawing characters apply in the POSIX locale.
-.LP
-X/Open Curses states that the \fIACS_\fP definitions are \fBchar\fP constants.
-For the wide-character implementation (see \fBcurs_add_wch\fP),
-there are analogous \fIWACS_\fP definitions which are \fBcchar_t\fP constants.
-.LP
-Some ACS symbols
-(ACS_S3,
-ACS_S7,
-ACS_LEQUAL,
-ACS_GEQUAL,
-ACS_PI,
-ACS_NEQUAL,
-ACS_STERLING)
-were not documented in
-any publicly released System V. However, many publicly available terminfos
-include \fBacsc\fR strings in which their key characters (pryz{|}) are
-embedded, and a second-hand list of their character descriptions has come
-to light. The ACS-prefixed names for them were invented for \fBncurses\fR(3X).
-.LP
-The \fBTABSIZE\fR variable is implemented in some versions of curses,
-but is not part of X/Open curses.
-.LP
-If \fIch\fR is a carriage return,
-the cursor is moved to the beginning of the current row of the window.
-This is true of other implementations, but is not documented.
-.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_attr\fR(3X),
-\fBcurs_clear\fR(3X),
-\fBcurs_inch\fR(3X),
-\fBcurs_outopts\fR(3X),
-\fBcurs_refresh\fR(3X),
-\fBcurs_variables\fR(3X),
-\fBputc\fR(3).
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
.PP
-Comparable functions in the wide-character (ncursesw) library are
-described in
-\fBcurs_add_wch\fR(3X).
+SVr4
+.I curses
+describes a successful return value only as
+\*(``an integer value other than
+.BR ERR \*(''.
+.PP
+The defaults specified for forms-drawing characters apply in the POSIX
+locale.
+.SS "ACS Symbols"
+X/Open Curses states that the
+.B \%ACS_
+definitions are
+.I char
+constants.
+.PP
+Some implementations are problematic.
+.bP
+Solaris
+.IR curses ,
+for example,
+define the ACS symbols as constants;
+others define them as elements of an array.
+.IP
+This implementation uses an array,
+.BR \%acs_map ,
+as did SVr4
+.IR curses .
+NetBSD also uses an array,
+actually named
+.BR \%_acs_char ,
+with a
+.B \%#define
+for compatibility.
+.bP
+HP-UX
+.I curses
+equates some of the
+.B \%ACS_
+symbols to the analogous
+.B \%WACS_
+symbols as if the
+.B \%ACS_
+symbols were wide characters
+(see \fB\%curs_add_wch\fP(3X)).
+The misdefined symbols are the arrows and others that are not used for
+line drawing.
+.bP
+X/Open Curses
+(Issues 2 through 7)
+has a typographical error
+for the
+.B \%ACS_LANTERN
+symbol, equating its \*(``VT100+ Character\*('' to \*(``I\*(''
+(capital I),
+while the header files for SVr4
+.I curses
+and other implementations use \*(``i\*(''
+(small i).
+.IP
+None of the terminal descriptions on Unix platforms use uppercase I,
+except for Solaris
+(in its
+.I \%term\%info
+entry for \fI\%screen\fP(1),
+apparently based on the X/Open documentation around 1995).
+On the other hand,
+its
+.B \%gs6300
+(AT&T PC6300 with EMOTS Terminal Emulator)
+description uses lowercase i.
+.PP
+Some ACS symbols
+.RB ( \%ACS_S3 ,
+.BR \%ACS_S7 ,
+.BR \%ACS_LEQUAL ,
+.BR \%ACS_GEQUAL ,
+.BR \%ACS_PI ,
+.BR \%ACS_NEQUAL ,
+and
+.BR \%ACS_STERLING )
+were not documented in any publicly released System\ V.
+However,
+many publicly available
+.I \%term\%info
+entries include
+.B \%acsc
+strings in which their key characters
+.BR ( pryz{|} )
+are embedded,
+and a second-hand list of their character descriptions has come to
+light.
+The
+.I \%ncurses
+developers invented ACS-prefixed names for them.
+.PP
+The
+.I displayed
+values of
+.B \%ACS_
+constants depend on
+.bP
+the
+.I \%ncurses
+ABI\(emfor example,
+wide-character versus non-wide-character configurations
+(the former is capable of displaying Unicode while the latter is not),
+and
+.bP
+whether the locale uses UTF-8 encoding.
+.PP
+In certain cases,
+the terminal is unable to display forms-drawing characters
+.I except
+by using UTF-8;
+see the discussion of the
+.I \%NCURSES_NO_UTF8_ACS
+environment variable in \fB\%ncurses\fP(3X)).
+.SS "Character Set"
+X/Open Curses assumes that the parameter passed to
+.B \%waddch
+contains a single character.
+As discussed in \fB\%curs_attr\fP(3X),
+that character may have been more than eight bits wide in an SVr3 or
+SVr4 implementation,
+but in the X/Open Curses model,
+the details are not given.
+The important distinction between SVr4
+.I curses
+and X/Open Curses is that the latter separates non-character information
+(attributes and color)
+from the character code,
+which SVr4 packs into a
+.I \%chtype
+for passage to
+.BR \%waddch .
+.PP
+In
+.IR \%ncurses ,
+.I \%chtype
+holds an eight-bit character.
+But the library allows a multibyte character to be passed in a
+succession of calls to
+.BR \%waddch .
+Other implementations do not;
+a
+.B \%waddch
+call transmits exactly one character,
+which may be rendered in one or more screen locations depending on
+whether it is printable.
+.PP
+Depending on the locale settings,
+.I \%ncurses
+inspects the byte passed in each
+.B \%waddch
+call,
+and checks whether the latest call continues a multibyte sequence.
+When a character is
+.IR complete ,
+.I \%ncurses
+displays the character and advances the cursor.
+.PP
+If the calling application interrupts the succession of bytes in
+a multibyte character sequence by changing the current location\(emfor
+example,
+with \fB\%wmove\fP(3X)\(em\c
+.I \%ncurses
+discards the incomplete character.
+.PP
+For portability to other implementations,
+do not rely upon this behavior.
+Check whether a character can be represented as a single byte in the
+current locale.
+.bP
+If it can,
+call either
+.B \%waddch
+or \fB\%wadd_wch\fP(3X).
+.bP
+If it cannot,
+use only
+\fB\%wadd_wch\fP(3X).
+.SS TABSIZE
+SVr4 and other versions of
+.I curses
+implement the
+.B \%TABSIZE
+variable,
+but X/Open Curses does not specify it
+(see \fB\%curs_variables\fP(3X)).
+.SH SEE ALSO
+\fB\%curs_add_wch\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its wide-character configuration
+.RI ( \%ncursesw ).
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_addchstr\fP(3X),
+\fB\%curs_addstr\fP(3X),
+\fB\%curs_attr\fP(3X),
+\fB\%curs_clear\fP(3X),
+\fB\%curs_inch\fP(3X),
+\fB\%curs_outopts\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_variables\fP(3X),
+\fB\%putchar\fP(3)
diff --git a/man/curs_addchstr.3x b/man/curs_addchstr.3x
index 08536e3..25d322a 100644
--- a/man/curs_addchstr.3x
+++ b/man/curs_addchstr.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright 2019-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2012,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 *
@@ -26,57 +27,61 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addchstr.3x,v 1.16 2012/11/03 22:54:43 tom Exp $
-.TH curs_addchstr 3X ""
+.\" $Id: curs_addchstr.3x,v 1.45 2024/04/20 21:20:07 tom Exp $
+.TH curs_addchstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.na
-.hy 0
.SH NAME
-\fBaddchstr\fR,
-\fBaddchnstr\fR,
-\fBwaddchstr\fR,
-\fBwaddchnstr\fR,
-\fBmvaddchstr\fR,
-\fBmvaddchnstr\fR,
-\fBmvwaddchstr\fR,
-\fBmvwaddchnstr\fR \- add a string of characters (and attributes) to a \fBcurses\fR window
-.ad
-.hy
+\fB\%addchstr\fP,
+\fB\%addchnstr\fP,
+\fB\%waddchstr\fP,
+\fB\%waddchnstr\fP,
+\fB\%mvaddchstr\fP,
+\fB\%mvaddchnstr\fP,
+\fB\%mvwaddchstr\fP,
+\fB\%mvwaddchnstr\fP \-
+add a \fIcurses\fR character string to a window
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fR
+\fB#include <curses.h>
.PP
-\fBint addchstr(const chtype *chstr);\fR
-.br
-\fBint addchnstr(const chtype *chstr, int n);\fR
-.br
-\fBint waddchstr(WINDOW *win, const chtype *chstr);\fR
-.br
-\fBint waddchnstr(WINDOW *win, const chtype *chstr, int n);\fR
-.br
-\fBint mvaddchstr(int y, int x, const chtype *chstr);\fR
-.br
-\fBint mvaddchnstr(int y, int x, const chtype *chstr, int n);\fR
-.br
-\fBint mvwaddchstr(WINDOW *win, int y, int x, const chtype *chstr);\fR
-.br
-\fBint mvwaddchnstr(WINDOW *win, int y, int x, const chtype *chstr, int n);\fR
+\fBint addchstr(const chtype *\fIchstr\fP);
+\fBint waddchstr(WINDOW *\fIwin\fP, const chtype *\fIchstr\fP);
+\fBint mvaddchstr(int \fIy\fP, int \fIx\fP, const chtype *\fIchstr\fP);
+\fBint mvwaddchstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const chtype *\fIchstr\fP);
+.PP
+\fBint addchnstr(const chtype *\fIchstr\fP, int \fIn\fP);
+\fBint waddchnstr(WINDOW *\fIwin\fP, const chtype *\fIchstr\fP, int \fIn\fP);
+\fBint mvaddchnstr(int \fIy\fP, int \fIx\fP, const chtype *\fIchstr\fP, int \fIn\fP);
+\fBint mvwaddchnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const chtype *\fIchstr\fP, int \fIn\fP);
.fi
.SH DESCRIPTION
These functions copy the (null-terminated)
-\fIchstr\fR array
+\fIchstr\fP array
into the window image structure
starting at the current cursor position.
-The four functions with \fIn\fR as the last
-argument copy at most \fIn\fR elements,
+.PP
+The four functions with \fIn\fP as the last
+argument copy at most \fIn\fP elements,
but no more than will fit on the line.
-If \fBn\fR=\fB\-1\fR then the whole array is copied,
+If \fBn\fP=\fB\-1\fP then the whole array is copied,
to the maximum number of characters that will fit on the line.
.PP
-The window cursor is \fInot\fR advanced.
-These functions work faster than \fBwaddnstr\fR.
+The window cursor is \fInot\fP advanced.
+These functions are faster than \fBwaddnstr\fP.
On the other hand:
.bP
they do not perform checking
@@ -89,23 +94,30 @@
they truncate the string if it crosses the right margin,
rather than wrapping it around to the new line.
.SH RETURN VALUE
-All functions return the integer \fBERR\fR upon failure and \fBOK\fR on success.
+All functions return the integer \fBERR\fP upon failure and \fBOK\fP on success.
.PP
-X/Open does not define any error conditions.
+X/Open Curses does not specify any error conditions.
This implementation returns an error
-if the window pointer is null.
+.bP
+if the \fIwin\fP parameter is null or
+.bP
+if the \fIwchstr\fP parameter is null.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
-All functions except \fBwaddchnstr\fR may be macros.
+All functions except \fBwaddchnstr\fP may be macros.
.SH PORTABILITY
-These entry points are described in the XSI Curses standard, Issue 4.
+These functions are described in X/Open Curses, Issue 4.
.SH SEE ALSO
-\fBcurs_addstr\fR(3X),
-\fBcurses\fR(3X).
+\fB\%curs_add_wchstr\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its wide-character configuration
+.RI ( \%ncursesw ).
.PP
-Comparable functions in the wide-character (ncursesw) library are
-described in
-\fBcurs_add_wchstr\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_addch\fP(3X),
+\fB\%curs_addstr\fP(3X)
diff --git a/man/curs_addstr.3x b/man/curs_addstr.3x
index b1cb1cc..1244001 100644
--- a/man/curs_addstr.3x
+++ b/man/curs_addstr.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright 2019-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2012,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 *
@@ -26,76 +27,109 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addstr.3x,v 1.17 2012/11/03 22:57:31 tom Exp $
-.TH curs_addstr 3X ""
+.\" $Id: curs_addstr.3x,v 1.45 2024/04/20 19:18:18 tom Exp $
+.TH curs_addstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.na
-.hy 0
.SH NAME
-\fBaddstr\fR,
-\fBaddnstr\fR,
-\fBwaddstr\fR,
-\fBwaddnstr\fR,
-\fBmvaddstr\fR,
-\fBmvaddnstr\fR,
-\fBmvwaddstr\fR,
-\fBmvwaddnstr\fR \- add a string of characters to a \fBcurses\fR window and advance cursor
-.ad
-.hy
+\fB\%addstr\fP,
+\fB\%addnstr\fP,
+\fB\%waddstr\fP,
+\fB\%waddnstr\fP,
+\fB\%mvaddstr\fP,
+\fB\%mvaddnstr\fP,
+\fB\%mvwaddstr\fP,
+\fB\%mvwaddnstr\fP \-
+add a string to a \fIcurses\fR window and advance the cursor
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fR
+\fB#include <curses.h>
.PP
-\fBint addstr(const char *\fR\fIstr\fR\fB);\fR
-.br
-\fBint addnstr(const char *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint waddstr(WINDOW *\fR\fIwin\fR\fB, const char *\fR\fIstr\fR\fB);\fR
-.br
-\fBint waddnstr(WINDOW *\fR\fIwin\fR\fB, const char *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint mvaddstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const char *\fR\fIstr\fR\fB);\fR
-.br
-\fBint mvaddnstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const char *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint mvwaddstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const char *\fR\fIstr\fR\fB);\fR
-.br
-\fBint mvwaddnstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const char *\fR\fIstr, int \fR\fIn\fR\fB);\fR
+\fBint addstr(const char *\fIstr\fP);
+\fBint mvaddstr(int \fIy\fP, int \fIx\fP, const char *\fIstr\fP);
+\fBint mvwaddstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const char *\fIstr\fP);
+\fBint waddstr(WINDOW *\fIwin\fP, const char *\fIstr\fP);
+.PP
+\fBint addnstr(const char *\fIstr\fP, int \fIn\fP);
+\fBint mvaddnstr(int \fIy\fP, int \fIx\fP, const char *\fIstr\fP, int \fIn\fP);
+\fBint mvwaddnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const char *\fIstr\fP, int \fIn\fP);
+\fBint waddnstr(WINDOW *\fIwin\fP, const char *\fIstr\fP, int \fIn\fP);
.fi
.SH DESCRIPTION
-These functions write the (null-terminated) character string
-\fIstr\fR on the given window.
-It is similar to calling \fBwaddch\fR once for each character in the string.
+.B waddstr
+writes the characters of the (null-terminated) string
+.I str
+to the window
+.IR win .
+Its process is similar to calling \fB\%waddch\fP(3X) for each
+.I char
+in
+.IR str .
+Control characters are processed as in \fB\%waddch\fP(3X).
.PP
-The \fImv\fR functions perform cursor movement once, before writing any
-characters.
-Thereafter, the cursor is advanced as a side-effect of writing to the window.
+.B waddnstr
+writes at most
+.I n
+characters,
+or until a terminating null character occurs in
+.IR str .
+If
+.I n
+is \-1,
+.B
+.B waddnstr
+writes the entire string.
.PP
-The four functions with \fIn\fR as the last argument
-write at most \fIn\fR characters,
-or until a terminating null is reached.
-If \fIn\fR is \-1, then the entire string will be added.
+\fB\%ncurses\fP(3X) describes the variants of these functions.
.SH RETURN VALUE
-All functions return the integer \fBERR\fR upon failure and \fBOK\fR on success.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
.PP
-X/Open does not define any error conditions.
-This implementation returns an error
+X/Open Curses does not specify any error conditions.
+.I \%ncurses
+returns an error
.bP
-if the window pointer is null or
+if the window pointer is
+.BR NULL ,
.bP
-if the string pointer is null or
+if the string pointer is
+.BR NULL ,
+or
.bP
-if the corresponding calls to \fBwaddch\fP return an error.
+if an internal \fB\%waddch\fP(3X) call returns an error.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
-All of these functions except \fBwaddnstr\fR may be macros.
+All of these functions except \fBwaddnstr\fP may be macros.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
+X/Open Curses,
+Issue 4 describes these functions.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_addch\fR(3X).
+\fB\%curs_addwstr\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its wide-character configuration
+.RI ( \%ncursesw ).
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_addch\fP(3X),
+\fB\%curs_addchstr\fP(3X)
diff --git a/man/curs_addwstr.3x b/man/curs_addwstr.3x
index 835cb34..78d5788 100644
--- a/man/curs_addwstr.3x
+++ b/man/curs_addwstr.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright 2019-2023,2024 Thomas E. Dickey *
+.\" Copyright 2002-2012,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 *
@@ -26,78 +27,120 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addwstr.3x,v 1.11 2012/11/03 22:57:31 tom Exp $
-.TH curs_addwstr 3X ""
+.\" $Id: curs_addwstr.3x,v 1.37 2024/04/20 19:18:18 tom Exp $
+.TH curs_addwstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.na
-.hy 0
.SH NAME
-\fBaddwstr\fR,
-\fBaddnwstr\fR,
-\fBwaddwstr\fR,
-\fBwaddnwstr\fR,
-\fBmvaddwstr\fR,
-\fBmvaddnwstr\fR,
-\fBmvwaddwstr\fR,
-\fBmvwaddnwstr\fR \- add a string of wide characters to a \fBcurses\fR window and advance cursor
-.ad
-.hy
+\fB\%addwstr\fP,
+\fB\%addnwstr\fP,
+\fB\%waddwstr\fP,
+\fB\%waddnwstr\fP,
+\fB\%mvaddwstr\fP,
+\fB\%mvaddnwstr\fP,
+\fB\%mvwaddwstr\fP,
+\fB\%mvwaddnwstr\fP \-
+add a wide-character string to a \fIcurses\fR window and advance the cursor
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fR
+\fB#include <curses.h>
.PP
-\fBint addwstr(const wchar_t *\fR\fIwstr\fR\fB);\fR
-.br
-\fBint addnwstr(const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint waddwstr(WINDOW *\fR\fIwin\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR
-.br
-\fBint waddnwstr(WINDOW *\fR\fIwin\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint mvaddwstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR
-.br
-\fBint mvaddnwstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint mvwaddwstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR
-.br
-\fBint mvwaddnwstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
+\fBint addwstr(const wchar_t *\fIwstr\fP);
+\fBint mvaddwstr(int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP);
+\fBint mvwaddwstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP);
+\fBint waddwstr(WINDOW *\fIwin\fP, const wchar_t *\fIwstr\fP);
+.PP
+\fBint addnwstr(const wchar_t *\fIwstr\fP, int \fIn\fP);
+\fBint mvaddnwstr(int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP, int \fIn\fP);
+\fBint mvwaddnwstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP, int \fIn\fP);
+\fBint waddnwstr(WINDOW *\fIwin\fP, const wchar_t *\fIwstr\fP, int \fIn\fP);
.fi
.SH DESCRIPTION
-These functions write the characters of the
-(null-terminated) \fBwchar_t\fR character string
-\fIwstr\fR on the given window.
-It is similar to constructing a \fBcchar_t\fR for each wchar_t in the string,
-then calling \fBwadd_wch\fR for the resulting \fBcchar_t\fR.
+.B waddwstr
+writes the characters of the (wide-null-terminated) wide-character
+string
+.I wstr
+to the window
+.IR win .
+Its process is similar to constructing a
+.I cchar_t
+for each
+.I wchar_t
+in
+.IR wstr ,
+then calling \fB\%wadd_wch\fP(3X) with the resulting
+.IR cchar_t .
+.bP
+Spacing and non-spacing characters in the string
+are processed one at a time,
+and
+.bP
+control characters are processed as in \fB\%wadd_wch\fP(3X).
.PP
-The \fImv\fR functions perform cursor movement once, before writing any
-characters.
-Thereafter, the cursor is advanced as a side-effect of writing to the window.
+.B waddnwstr
+writes at most
+.I n
+wide characters,
+or until a terminating wide null character occurs in
+.IR wstr .
+If
+.I n
+is \-1,
+.B
+.B waddnwstr
+writes the entire wide string.
.PP
-The four functions with \fIn\fR as the last argument
-write at most \fIn\fR \fBwchar_t\fR characters,
-or until a terminating null is reached.
-If \fIn\fR is \-1, then the entire string will be added.
+\fB\%ncurses\fP(3X) describes the variants of these functions.
.SH RETURN VALUE
-All functions return the integer \fBERR\fR upon failure and \fBOK\fR on success.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
.PP
-X/Open does not define any error conditions.
-This implementation returns an error
+X/Open Curses does not specify any error conditions.
+.I \%ncurses
+returns an error
.bP
-if the window pointer is null or
+if the window pointer is
+.BR NULL ,
.bP
-if the string pointer is null or
+if the string pointer is
+.BR NULL ,
+or
.bP
-if the corresponding calls to \fBwadd_wch\fP return an error.
+if an internal \fB\%wadd_wch\fP(3X) call returns an error.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
-All of these functions except \fBwaddnwstr\fR may be macros.
+All of these functions except
+.B waddnwstr
+may be implemented as macros.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
+X/Open Curses,
+Issue 4 describes these functions.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_add_wch\fR(3X)
+\fB\%curs_addstr\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its non-wide-character configuration.
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_add_wch\fP(3X),
+\fB\%curs_add_wchstr\fP(3X)
diff --git a/man/curs_attr.3x b/man/curs_attr.3x
index 718417f..3777460 100644
--- a/man/curs_attr.3x
+++ b/man/curs_attr.3x
@@ -1,6 +1,7 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2013,2015 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -27,314 +28,571 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_attr.3x,v 1.40 2015/07/20 23:35:38 tom Exp $
-.TH curs_attr 3X ""
-.na
-.hy 0
+.\" $Id: curs_attr.3x,v 1.105 2024/04/27 17:54:42 tom Exp $
+.TH curs_attr 3X 2024-04-27 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
+.\" ---------------------------------------------------------------------------
.SH NAME
-\fBattroff\fR,
-\fBwattroff\fR,
-\fBattron\fR,
-\fBwattron\fR,
-\fBattrset\fR,
-\fBwattrset\fR,
-\fBcolor_set\fR,
-\fBwcolor_set\fR,
-\fBstandend\fR,
-\fBwstandend\fR,
-\fBstandout\fR,
-\fBwstandout\fR,
-\fBattr_get\fR,
-\fBwattr_get\fR,
-\fBattr_off\fR,
-\fBwattr_off\fR,
-\fBattr_on\fR,
-\fBwattr_on\fR,
-\fBattr_set\fR,
-\fBwattr_set\fR,
-\fBchgat\fR,
-\fBwchgat\fR,
-\fBmvchgat\fR,
-\fBmvwchgat\fR,
-\fBPAIR_NUMBER\fR \- \fBcurses\fR character and window attribute control routines
-.ad
-.hy
+\fB\%attr_get\fP,
+\fB\%wattr_get\fP,
+\fB\%attr_set\fP,
+\fB\%wattr_set\fP,
+\fB\%attr_off\fP,
+\fB\%wattr_off\fP,
+\fB\%attr_on\fP,
+\fB\%wattr_on\fP,
+\fB\%attroff\fP,
+\fB\%wattroff\fP,
+\fB\%attron\fP,
+\fB\%wattron\fP,
+\fB\%attrset\fP,
+\fB\%wattrset\fP,
+\fB\%chgat\fP,
+\fB\%wchgat\fP,
+\fB\%mvchgat\fP,
+\fB\%mvwchgat\fP,
+\fB\%color_set\fP,
+\fB\%wcolor_set\fP,
+\fB\%standend\fP,
+\fB\%wstandend\fP,
+\fB\%standout\fP,
+\fB\%wstandout\fP \-
+manipulate attributes of character cells in \fIcurses\fR windows
+.\" ---------------------------------------------------------------------------
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.br
-\fBint attroff(int \fP\fIattrs);\fR
-.br
-\fBint wattroff(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR
-.br
-\fBint attron(int \fP\fIattrs\fP\fB);\fR
-.br
-\fBint wattron(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR
-.br
-\fBint attrset(int \fP\fIattrs\fP\fB);\fR
-.br
-\fBint wattrset(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR
-.br
-\fBint color_set(short \fP\fIcolor_pair_number\fP\fB, void* \fP\fIopts\fP\fB);\fR
-.br
-\fBint wcolor_set(WINDOW *\fP\fIwin\fP\fB, short \fP\fIcolor_pair_number\fP\fB,\fR
- \fBvoid* \fP\fIopts);\fR
-.br
-\fBint standend(void);\fR
-.br
-\fBint wstandend(WINDOW *\fP\fIwin\fP\fB);\fR
-.br
-\fBint standout(void);\fR
-.br
-\fBint wstandout(WINDOW *\fP\fIwin\fP\fB);\fR
-.br
-\fBint attr_get(attr_t *\fP\fIattrs\fP\fB, short *\fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fR
-.br
-\fBint wattr_get(WINDOW *\fP\fIwin\fP\fB, attr_t *\fP\fIattrs\fP\fB, short *\fP\fIpair\fP\fB,\fR
- \fBvoid *\fP\fIopts\fP\fB);\fR
-.br
-\fBint attr_off(attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR
-.br
-\fBint wattr_off(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR
-.br
-\fBint attr_on(attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR
-.br
-\fBint wattr_on(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR
-.br
-\fBint attr_set(attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fR
-.br
-\fBint wattr_set(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fR
-.br
-\fBint chgat(int \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB, short \fP\fIcolor\fP\fB,\fR
- \fBconst void *\fP\fIopts\fP\fB);\fR
-.br
-\fBint wchgat(WINDOW *\fP\fIwin\fP\fB, int \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB,\fR
- \fBshort \fP\fIcolor\fP\fB, const void *\fP\fIopts\fP\fB);\fR
-.br
-\fBint mvchgat(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, int \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB,\fR
- \fBshort \fP\fIcolor\fP\fB, const void *\fP\fIopts\fP\fB);\fR
-.br
-\fBint mvwchgat(WINDOW *\fP\fIwin, int \fP\fIy, int \fP\fIx, int \fP\fIn,\fR
- \fBattr_t \fP\fIattr\fP\fB, short \fP\fIcolor\fP\fB, const void *\fP\fIopts\fP\fB);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint attr_get(attr_t *\fIattrs\fP, short *\fIpair\fP, void *\fIopts\fP);
+\fBint wattr_get(WINDOW *\fIwin\fP, attr_t *\fIattrs\fP, short *\fIpair\fP,\fR \fPvoid *\fIopts\fP);
+\fBint attr_set(attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP);
+\fBint wattr_set(WINDOW *\fIwin\fP, attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP);
+.PP
+\fBint attr_off(attr_t \fIattrs\fP, void *\fIopts\fP);
+\fBint wattr_off(WINDOW *\fIwin\fP, attr_t \fIattrs\fP, void *\fIopts\fP);
+\fBint attr_on(attr_t \fIattrs\fP, void *\fIopts\fP);
+\fBint wattr_on(WINDOW *\fIwin\fP, attr_t \fIattrs\fP, void *\fIopts\fP);
+.PP
+\fBint attroff(int \fIattrs\fP);
+\fBint wattroff(WINDOW *\fIwin\fP, int \fIattrs\fP);
+\fBint attron(int \fIattrs\fP);
+\fBint wattron(WINDOW *\fIwin\fP, int \fIattrs\fP);
+\fBint attrset(int \fIattrs\fP);
+\fBint wattrset(WINDOW *\fIwin\fP, int \fIattrs\fP);
+.PP
+\fBint chgat(int \fIn\fP, attr_t \fIattr\fP, short \fIpair\fP,\fR \fPconst void *\fIopts\fP);
+\fBint wchgat(WINDOW *\fIwin\fP,
+ \fBint \fIn\fB, attr_t \fIattr\fB,\fR \fBshort \fIpair\fB, const void *\fIopts\fB);\fR
+\fBint mvchgat(int \fIy\fB, int \fIx\fB,\fR
+ \fBint \fIn\fB, attr_t \fIattr\fB, short \fIpair\fB, const void *\fIopts\fB);\fR
+\fBint mvwchgat(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB,\fR
+ \fBint \fIn\fB, attr_t \fIattr\fB, short \fIpair\fB, const void *\fIopts\fB);\fR
+.PP
+\fBint color_set(short \fIpair\fB, void* \fIopts\fB);\fR
+\fBint wcolor_set(WINDOW *\fIwin\fB, short \fIpair\fB,\fR \fBvoid* \fIopts\fP);\fR
+.PP
+\fBint standend(void);\fP
+\fBint wstandend(WINDOW *\fIwin\fB);\fR
+\fBint standout(void);\fP
+\fBint wstandout(WINDOW *\fIwin\fB);\fR
+.fi
+.\" ---------------------------------------------------------------------------
.SH DESCRIPTION
-These routines manipulate the current attributes of the named window.
-The
-current attributes of a window apply to all characters that are written into
-the window with \fBwaddch\fR, \fBwaddstr\fR and \fBwprintw\fR.
+These routines manipulate the current attributes of the named window,
+which then apply to all characters that are written into
+the window with \fBwaddch\fP, \fBwaddstr\fP and \fBwprintw\fP.
Attributes are
a property of the character, and move with the character through any scrolling
and insert/delete line/character operations.
To the extent possible, they are
displayed as appropriate modifications to the graphic rendition of characters
put on the screen.
-.SS attrset
.PP
-The routine \fBattrset\fR sets the current attributes of the given window to
-\fIattrs\fR.
-The routine \fBattroff\fR turns off the named attributes without
-turning any other attributes on or off.
-The routine \fBattron\fR turns on the
-named attributes without affecting any others.
-The routine \fBstandout\fR is
-the same as \fBattron(A_STANDOUT)\fR.
-The routine \fBstandend\fR is the same
-as \fBattrset(A_NORMAL)\fR or \fBattrset(0)\fR, that is, it turns off all
-attributes.
-.PP
-The \fBattrset\fR and related routines do not affect the attributes used
+These routines do not affect the attributes used
when erasing portions of the window.
-See \fBcurs_bkgd\fR(3X) for functions which modify the attributes used for
+See \fBcurs_bkgd\fP(3X) for functions which modify the attributes used for
erasing and clearing.
-.SS attr_set
-The \fBattrset\fP routine is actually a legacy feature predating SVr4 curses
+.\" ---------------------------------------------------------------------------
+.SS "Window Attributes"
+There are two sets of functions:
+.bP
+functions for manipulating the window attributes and color:
+\fBwattr_set\fP and \fBwattr_get\fP.
+.bP
+functions for manipulating only the window attributes (not color):
+\fBwattr_on\fP and \fBwattr_off\fP.
+.PP
+The \fBwattr_set\fP function sets the current attributes
+of the given window to \fIattrs\fP, with color specified by \fIpair\fP.
+.PP
+Use \fBwattr_get\fP to retrieve attributes for the given window.
+.PP
+Use \fBattr_on\fP and \fBwattr_on\fP to turn on window attributes, i.e.,
+values OR'd together in \fIattr\fP,
+without affecting other attributes.
+Use \fBattr_off\fP and \fBwattr_off\fP to turn off window attributes,
+again values OR'd together in \fIattr\fP,
+without affecting other attributes.
+.\" ---------------------------------------------------------------------------
+.SS "Legacy Window Attributes"
+The X/Open window attribute routines which \fIset\fP or \fIget\fP,
+turn \fIon\fP or \fIoff\fP
+are extensions of older routines
+which assume that color pairs are OR'd into the attribute parameter.
+These newer routines use similar names, because
+X/Open simply added an underscore (\fB_\fP) for the newer names.
+.PP
+The \fBint\fP datatype used in the legacy routines is treated as if
+it is the same size as \fBchtype\fP (used by \fBaddch\fP(3X)).
+It holds the common video attributes (such as bold, reverse),
+as well as a few bits for color.
+Those bits correspond to the \fBA_COLOR\fP symbol.
+The \fBCOLOR_PAIR\fP macro provides a value which can be OR'd into
+the attribute parameter.
+For example,
+as long as that value fits into the \fBA_COLOR\fP mask,
+then these calls produce similar results:
+.PP
+.RS 4
+.EX
+attrset(A_BOLD | COLOR_PAIR(\fIpair\fP));
+attr_set(A_BOLD, \fIpair\fP, NULL);
+.EE
+.RE
+.PP
+However, if the value does not fit, then the \fBCOLOR_PAIR\fP macro
+uses only the bits that fit.
+For example,
+because in \fI\%ncurses\fP \fBA_COLOR\fP has eight (8) bits,
+then \fBCOLOR_PAIR(\fI259\fB)\fR is 4
+(i.e., 259 is 4 more than the limit 255).
+.PP
+The \fBPAIR_NUMBER\fP macro extracts a pair number from an \fBint\fP
+(or \fBchtype\fP).
+For example, the \fIinput\fP and \fIoutput\fP values in these statements
+would be the same:
+.PP
+.RS 4
+.EX
+int value = A_BOLD | COLOR_PAIR(\fIinput\fP);
+int \fIoutput\fP = PAIR_NUMBER(value);
+.EE
+.RE
+.PP
+The \fBattrset\fP routine is a legacy feature predating SVr4 curses
but kept in X/Open Curses for the same reason that SVr4 curses kept it:
-compatbility.
-The routine \fBattr_set\fP provides for passing a color-pair parameter.
+compatibility.
.PP
-The remaining \fBattr_\fR* functions operate exactly like the corresponding
-\fBattr\fR* functions, except that they take arguments of type \fBattr_t\fR
-rather than \fBint\fR.
-.SS color_set
+The remaining \fBattr\fP* functions operate exactly like the corresponding
+\fBattr_\fP* functions, except that they take arguments of type \fBint\fP
+rather than \fBattr_t\fP.
.PP
-The routine \fBcolor_set\fR sets the current color of the given window to the
-foreground/background combination described by the color_pair_number.
-The
-parameter opts is reserved for future use, applications must supply a null
-pointer.
-.SS attr_get
-.PP
-The routine \fBwattr_get\fR returns the current attribute and color pair for
-the given window; \fBattr_get\fR returns the current attribute and color pair
-for \fBstdscr\fR.
-.PP
-There is no corresponding \fBattrget\fP function as such in X/Open Curses,
-although ncurses provides \fBgetattrs\fP (see curs_legacy(3x)).
-.SS chgat
-.PP
-The routine \fBchgat\fR changes the attributes of a given number of characters
-starting at the current cursor location of \fBstdscr\fR.
+There is no corresponding \fB\%attrget\fP function as such
+in X/Open Curses,
+although \fI\%ncurses\fP provides \fB\%getattrs\fP
+(see \fB\%curs_legacy\fP(3X)).
+.\" ---------------------------------------------------------------------------
+.SS "Change Character Rendition"
+The routine \fBchgat\fP changes the attributes of a given number of characters
+starting at the current cursor location of \fBstdscr\fP.
It does not update
the cursor and does not perform wrapping.
A character count of \-1 or greater
than the remaining window width means to change attributes all the way to the
end of the current line.
-The \fBwchgat\fR function generalizes this to any
-window; the \fBmvwchgat\fR function does a cursor move before acting.
-In these
-functions, the color argument is a color-pair index (as in the first argument
-of \fIinit_pair\fR, see \fBcurs_color\fR(3X)).
-The \fBopts\fR argument is not
-presently used, but is reserved for the future (leave it \fBNULL\fR).
-.SS Attributes
-The following video attributes, defined in \fB<curses.h>\fR, can be passed to
-the routines \fBattron\fR, \fBattroff\fR, and \fBattrset\fR, or OR'd with the
-characters passed to \fBaddch\fR (see curs_addch(3x)).
+The \fBwchgat\fP function generalizes this to any window;
+the \fBmvwchgat\fP function does a cursor move before acting.
.PP
+In these functions,
+the color \fIpair\fP argument is a color pair index
+(as in the first argument of \fBinit_pair\fP, see \fBcurs_color\fP(3X)).
+.\" ---------------------------------------------------------------------------
+.SS "Change Window Color"
+The routine \fBcolor_set\fP sets the current color of the given window to the
+foreground/background combination described by the color \fIpair\fP parameter.
+.\" ---------------------------------------------------------------------------
+.SS Standout
+The routine \fBstandout\fP is
+the same as \fBattron(A_STANDOUT)\fP.
+The routine \fBstandend\fP is the same
+as \fBattrset(A_NORMAL)\fP or \fBattrset(0)\fP, that is, it turns off all
+attributes.
+.PP
+X/Open Curses does not mark these \*(``restricted\*('', because
+.bP
+they have well established legacy use, and
+.bP
+there is no ambiguity about the way the attributes
+might be combined with a color pair.
+.\" ---------------------------------------------------------------------------
+.SS "Video Attributes"
+The following video attributes, defined in \fB<curses.h>\fP, can be passed to
+the routines \fBattron\fP, \fBattroff\fP, and \fBattrset\fP, or OR'd with the
+characters passed to \fBaddch\fP (see \fBcurs_addch\fP(3X)).
+.PP
+.ne 15
.RS
.TS
-l l
-_ _ _
-l l .
-\fIName\fR \fIDescription\fR
-\fBA_NORMAL\fR Normal display (no highlight)
-\fBA_STANDOUT\fR Best highlighting mode of the terminal.
-\fBA_UNDERLINE\fR Underlining
-\fBA_REVERSE\fR Reverse video
-\fBA_BLINK\fR Blinking
-\fBA_DIM\fR Half bright
-\fBA_BOLD\fR Extra bright or bold
-\fBA_PROTECT\fR Protected mode
-\fBA_INVIS\fR Invisible or blank mode
-\fBA_ALTCHARSET\fR Alternate character set
-\fBA_ITALIC\fR Italics (non-X/Open extension)
-\fBA_CHARTEXT\fR Bit-mask to extract a character
-\fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR Color-pair number \fIn\fR
+Lb Lb
+Lb Lx.
+Name Description
+_
+A_NORMAL Normal display (no highlight)
+A_STANDOUT T{
+Best highlighting mode of the terminal
+T}
+A_UNDERLINE Underlining
+A_REVERSE Reverse video
+A_BLINK Blinking
+A_DIM Half bright
+A_BOLD Extra bright or bold
+A_PROTECT Protected mode
+A_INVIS Invisible or blank mode
+A_ALTCHARSET Alternate character set
+A_ITALIC Italics (non-X/Open extension)
+A_CHARTEXT Bit-mask to extract a character
+A_COLOR T{
+Bit-mask to extract a color (legacy routines)
+T}
.TE
.RE
.PP
These video attributes are supported by \fBattr_on\fP and related functions
(which also support the attributes recognized by \fBattron\fP, etc.):
+.PP
.RS
.TS
-l l
-_ _ _
-l l .
-\fIName\fR \fIDescription\fR
-\fBWA_HORIZONTAL\fR Horizontal highlight
-\fBWA_LEFT\fR Left highlight
-\fBWA_LOW\fR Low highlight
-\fBWA_RIGHT\fR Right highlight
-\fBWA_TOP\fR Top highlight
-\fBWA_VERTICAL\fR Vertical highlight
+Lb Lb
+Lb Lx.
+Name Description
+_
+WA_HORIZONTAL Horizontal highlight
+WA_LEFT Left highlight
+WA_LOW Low highlight
+WA_RIGHT Right highlight
+WA_TOP Top highlight
+WA_VERTICAL Vertical highlight
.TE
.RE
.PP
-For consistency
-.PP
-The following macro is the reverse of \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR:
-.PP
-.br
-\fBPAIR_NUMBER(\fR\fIattrs\fR) Returns the pair number associated
- with the \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR attribute.
-.br
-.PP
The return values of many of these routines are not meaningful (they are
implemented as macro-expanded assignments and simply return their argument).
-The SVr4 manual page claims (falsely) that these routines always return \fB1\fR.
-.SH NOTES
-Note that \fBattroff\fR, \fBwattroff\fR, \fBattron\fR, \fBwattron\fR,
-\fBattrset\fR, \fBwattrset\fR, \fBstandend\fR and \fBstandout\fR may be macros.
+The SVr4 manual page claims (falsely) that these routines always return \fB1\fP.
+.\" ---------------------------------------------------------------------------
+.SH RETURN VALUE
+All routines return the integer \fBOK\fP on success, or \fBERR\fP on failure.
.PP
-\fBCOLOR_PAIR\fP values can only be OR'd with attributes if the pair
+X/Open Curses does not specify any error conditions.
+.PP
+This implementation
+.bP
+returns an error if the window pointer is null.
+.bP
+returns an error if the color pair parameter
+for \fBwcolor_set\fP is outside the range 0..COLOR_PAIRS\-1.
+.bP
+does not return an error if either of the parameters of \fBwattr_get\fP
+used for retrieving attribute or color pair values is \fBNULL\fP.
+.PP
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
+.\" ---------------------------------------------------------------------------
+.SH NOTES
+These functions may be macros:
+.sp
+.RS
+\fBattroff\fP, \fBwattroff\fP, \fBattron\fP, \fBwattron\fP,
+\fBattrset\fP, \fBwattrset\fP, \fBstandend\fP and \fBstandout\fP.
+.RE
+.PP
+Color pair values can only be OR'd with attributes if the pair
number is less than 256.
The alternate functions such as \fBcolor_set\fP can pass a color pair
value directly.
-However, ncurses ABI 4 and 5 simply OR this value within the alternate functions.
-You must use ncurses ABI 6 to support more than 256 color pairs.
-.SH PORTABILITY
-These functions are supported in the XSI Curses standard, Issue 4.
-The
-standard defined the dedicated type for highlights, \fBattr_t\fR, which is not
-defined in SVr4 curses.
-The functions taking \fBattr_t\fR arguments are
-not supported under SVr4.
+However, \fI\%ncurses\fP ABI 4 and 5 simply OR this value
+within the alternate functions.
+You must use \fI\%ncurses\fP ABI 6 to support more than 256 color pairs.
+.\" ---------------------------------------------------------------------------
+.SH EXTENSIONS
+This implementation provides the \fBA_ITALIC\fP attribute for terminals
+which have the \fBenter_italics_mode\fP (\fBsitm\fP)
+and \fBexit_italics_mode\fP (\fBritm\fP) capabilities.
+Italics are not mentioned in X/Open Curses.
+Unlike the other video attributes, \fBA_ITALIC\fP is unrelated
+to the \fBset_attributes\fP capabilities.
+This implementation makes the assumption that
+\fBexit_attribute_mode\fP may also reset italics.
.PP
-The XSI Curses standard states that whether the traditional functions
-\fBattron\fR/\fBattroff\fR/\fBattrset\fR can manipulate attributes other than
-\fBA_BLINK\fR, \fBA_BOLD\fR, \fBA_DIM\fR, \fBA_REVERSE\fR, \fBA_STANDOUT\fR, or
-\fBA_UNDERLINE\fR is "unspecified".
+Each of the functions added by XSI Curses has a parameter \fIopts\fP,
+which X/Open Curses still (after more than twenty years) documents
+as reserved for future use, saying that it should be \fBNULL\fP.
+This implementation uses that parameter in ABI 6 for the functions which
+have a color pair parameter to support \fIextended color pairs\fP:
+.bP
+For functions which modify the color, e.g.,
+\fBwattr_set\fP and \fBwattr_on\fP,
+if \fIopts\fP is set it is treated as a pointer to \fBint\fP,
+and used to set the color pair instead of the \fBshort\fP \fIpair\fP parameter.
+.bP
+For functions which retrieve the color, e.g.,
+\fBwattr_get\fP,
+if \fIopts\fP is set it is treated as a pointer to \fBint\fP,
+and used to retrieve the color pair as an \fBint\fP value,
+in addition to
+retrieving it via the standard pointer to \fBshort\fP parameter.
+.bP
+For functions which turn attributes off, e.g.,
+\fBwattr_off\fP,
+the \fIopts\fP parameter is ignored except
+except to check that it is \fBNULL\fP.
+.\" ---------------------------------------------------------------------------
+.SH PORTABILITY
+These functions are described in X/Open Curses, Issue 4.
+The standard defined the dedicated type for highlights,
+\fBattr_t\fP, which was not defined in SVr4 curses.
+The functions taking \fBattr_t\fP arguments were not supported under SVr4.
+.PP
+Very old versions of this library did not force an update of the screen
+when changing the attributes.
+Use \fBtouchwin\fP to force the screen to match the updated attributes.
+.PP
+X/Open Curses states that whether the traditional functions
+\fBattron\fP/\fBattroff\fP/\fBattrset\fP can manipulate attributes other than
+\fBA_BLINK\fP, \fBA_BOLD\fP, \fBA_DIM\fP, \fBA_REVERSE\fP, \fBA_STANDOUT\fP, or
+\fBA_UNDERLINE\fP is \*(``unspecified\*(''.
Under this implementation as well as
SVr4 curses, these functions correctly manipulate all other highlights
-(specifically, \fBA_ALTCHARSET\fR, \fBA_PROTECT\fR, and \fBA_INVIS\fR).
+(specifically, \fBA_ALTCHARSET\fP, \fBA_PROTECT\fP, and \fBA_INVIS\fP).
.PP
-This implementation provides the \fBA_ITALIC\fP attribute for terminals
-which have the \fIenter_italics_mode\fP (sitm) and \fIexit_italics_mode\fP (ritm) capabilities.
-Italics are not mentioned in X/Open Curses.
-Unlike the other video attributes, \fBI_ITALIC\fP is unrelated
-to the \fIset_attributes\fP capabilities.
-This implementation makes the assumption that
-\fIexit_attribute_mode\fP may also reset italics.
+X/Open Curses added these entry points:
+.sp
+.RS
+\fBattr_get\fP, \fBattr_on\fP,
+\fBattr_off\fP, \fBattr_set\fP, \fBwattr_on\fP, \fBwattr_off\fP,
+\fBwattr_get\fP, \fBwattr_set\fP
+.RE
.PP
-XSI Curses added the new entry points, \fBattr_get\fR, \fBattr_on\fR,
-\fBattr_off\fR, \fBattr_set\fR, \fBwattr_on\fR, \fBwattr_off\fR,
-\fBwattr_get\fR, \fBwattr_set\fR.
-These are intended to work with
-a new series of highlight macros prefixed with \fBWA_\fR.
+The new functions are intended to work with
+a new series of highlight macros prefixed with \fBWA_\fP.
The older macros have direct counterparts in the newer set of names:
.PP
.RS
.ne 9
.TS
-l l
-_ _ _
-l l .
-\fIName\fR \fIDescription\fR
-\fBWA_NORMAL\fR Normal display (no highlight)
-\fBWA_STANDOUT\fR Best highlighting mode of the terminal.
-\fBWA_UNDERLINE\fR Underlining
-\fBWA_REVERSE\fR Reverse video
-\fBWA_BLINK\fR Blinking
-\fBWA_DIM\fR Half bright
-\fBWA_BOLD\fR Extra bright or bold
-\fBWA_ALTCHARSET\fR Alternate character set
+Lb Lb
+Lb Lx.
+Name Description
+_
+WA_NORMAL Normal display (no highlight)
+WA_STANDOUT T{
+Best highlighting mode of the terminal
+T}
+WA_UNDERLINE Underlining
+WA_REVERSE Reverse video
+WA_BLINK Blinking
+WA_DIM Half bright
+WA_BOLD Extra bright or bold
+WA_ALTCHARSET Alternate character set
.TE
.RE
.PP
-Very old versions of this library did not force an update of the screen
-when changing the attributes.
-Use \fBtouchwin\fR to force the screen to match the updated attributes.
-.PP
-The XSI curses standard specifies that each pair of corresponding \fBA_\fR
-and \fBWA_\fR-using functions operates on the same current-highlight
+X/Open Curses does not assign values to these symbols,
+nor does it state whether or not they are related to the
+similarly-named A_NORMAL, etc.:
+.bP
+X/Open Curses specifies that each pair of corresponding \fBA_\fP
+and \fBWA_\fP-using functions operates on the same current-highlight
information.
+.bP
+However, in some implementations, those symbols have unrelated values.
+.IP
+For example, the Solaris \fIxpg4\fP (X/Open) curses declares
+\fBattr_t\fP to be an unsigned short integer (16-bits),
+while \fBchtype\fP is a unsigned integer (32-bits).
+The \fBWA_\fP symbols in this case are different from the \fBA_\fP symbols
+because they are used for a smaller datatype which does not
+represent \fBA_CHARTEXT\fP or \fBA_COLOR\fP.
+.IP
+In this implementation (as in many others), the values happen to be
+the same because it simplifies copying information between
+\fBchtype\fP and \fBcchar_t\fP variables.
+.bP
+Because \fI\%ncurses\fP's \fBattr_t\fP can hold a color pair
+(in the \fBA_COLOR\fP field),
+a call to
+\fBwattr_on\fP,
+\fBwattr_off\fP, or
+\fBwattr_set\fP
+may alter the window's color.
+If the color pair information in the attribute parameter is zero,
+no change is made to the window's color.
+.IP
+This is consistent with SVr4 curses;
+X/Open Curses does not specify this.
.PP
-The XSI standard extended conformance level adds new highlights
-\fBA_HORIZONTAL\fR, \fBA_LEFT\fR, \fBA_LOW\fR, \fBA_RIGHT\fR, \fBA_TOP\fR,
-\fBA_VERTICAL\fR (and corresponding \fBWA_\fR macros for each).
+The X/Open Curses extended conformance level adds new highlights
+\fBA_HORIZONTAL\fP, \fBA_LEFT\fP, \fBA_LOW\fP, \fBA_RIGHT\fP, \fBA_TOP\fP,
+\fBA_VERTICAL\fP (and corresponding \fBWA_\fP macros for each).
As of August 2013,
no known terminal provides these highlights
(i.e., via the \fBsgr1\fP capability).
-.SH RETURN VALUE
-All routines return the integer \fBOK\fR on success, or \fBERR\fP on failure.
+.\" ---------------------------------------------------------------------------
+.SH HISTORY
+X/Open Curses is largely based on SVr4 curses,
+adding support for \*(``wide-characters\*('' (not specific to Unicode).
+Some of the X/Open differences from SVr4 curses address the way
+video attributes can be applied to wide-characters.
+But aside from that, \fBattrset\fP and \fBattr_set\fP are similar.
+SVr4 curses provided the basic features for manipulating video attributes.
+However, earlier versions of curses provided a part of these features.
.PP
-X/Open does not define any error conditions.
+As seen in 2.8BSD, curses assumed 7-bit characters,
+using the eighth bit of a byte to represent the \fIstandout\fP
+feature (often implemented as bold and/or reverse video).
+The BSD curses library provided functions \fBstandout\fP and \fBstandend\fP
+which were carried along into X/Open Curses due to their pervasive use
+in legacy applications.
.PP
-This implementation returns an error
-if the window pointer is null.
-The \fBwcolor_set\fP function returns an error if the color pair parameter
-is outside the range 0..COLOR_PAIRS\-1.
-This implementation also provides
-\fBgetattrs\fR
-for compatibility with older versions of curses.
+Some terminals in the 1980s could support a variety of video attributes,
+although the BSD curses library could do nothing with those.
+System V (1983) provided an improved curses library.
+It defined the \fBA_\fP symbols for use by applications to manipulate the
+other attributes.
+There are few useful references for the chronology.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Goodheart's book
+\fIUNIX Curses Explained\fP (1991) describes SVr3 (1987),
+commenting on several functions:
+.bP
+the \fBattron\fP, \fBattroff\fP, \fBattrset\fP functions
+(and most of the functions found in SVr4 but not in BSD curses) were
+introduced by System V,
+.bP
+the alternate character set feature with \fBA_ALTCHARSET\fP was
+added in SVr2 and improved in SVr3 (by adding \fBacs_map[]\fP),
+.bP
+\fBstart_color\fP and related color-functions were introduced by System V.3.2,
+.bP
+pads, soft-keys were added in SVr3, and
+.PP
+Goodheart did not mention the background character or the \fBcchar_t\fP type.
+Those are respectively SVr4 and X/Open features.
+He did mention the \fBA_\fP constants, but did not indicate their values.
+Those were not the same in different systems,
+even for those marked as System V.
+.PP
+Different Unix systems used different sizes for the bit-fields in \fBchtype\fP
+for \fIcharacters\fP and \fIcolors\fP, and took into account the different
+integer sizes (32-bit versus 64-bit).
+.PP
+This table showing the number of bits for \fBA_COLOR\fP
+and \fBA_CHARTEXT\fP
+was gleaned from the curses header files for
+various operating systems and architectures.
+The inferred architecture and notes reflect
+the format and size of the defined constants
+as well as clues such as the alternate character set implementation.
+A 32-bit library can be used on a 64-bit system,
+but not necessarily the reverse.
+.PP
+.TS
+Lb Lb Lb Cb S Lb
+Lb2 Lb Lb2 Lb2 Lb2 Lb
+L L L L L Lx.
+\& \& \& Bits \&
+Year System Arch Color Char Notes
+_
+1992 Solaris 5.2 32 6 17 SVr4 \fIcurses\fP
+1992 HP-UX 9 32 no 8 SVr2 \fIcurses\fP
+1992 AIX 3.2 32 no 23 SVr2 \fIcurses\fP
+1994 OSF/1 r3 32 no 23 SVr2 \fIcurses\fP
+1995 HP-UX 10.00 32 6 16 SVr3 \fIcurses_colr\fP
+1995 HP-UX 10.00 32 6 8 SVr4, X/Open \fIcurses\fP
+1995 Solaris 5.4 32/64 7 16 X/Open \fIcurses\fP
+1996 AIX 4.2 32 7 16 X/Open \fIcurses\fP
+1996 OSF/1 r4 32 6 16 X/Open \fIcurses\fP
+1997 HP-UX 11.00 32 6 8 X/Open \fIcurses\fP
+2000 U/Win 32/64 7/31 16 uses \fIchtype\fP
+.TE
+.PP
+Notes:
+.RS 3
+.PP
+Regarding HP-UX,
+.bP
+HP-UX 10.20 (1996) added support for 64-bit PA-RISC processors in 1996.
+.bP
+HP-UX 10.30 (1997) marked \*(``curses_colr\*('' obsolete.
+That version of curses was dropped with HP-UX 11.30 in 2006.
+.PP
+Regarding OSF/1 (and Tru64),
+.bP
+These used 64-bit hardware.
+Like \fI\%ncurses\fP,
+the OSF/1 curses interface is not customized for 32-bit and 64-bit
+versions.
+.bP
+Unlike other systems which evolved from AT&T code,
+OSF/1 provided a new implementation for X/Open curses.
+.PP
+Regarding Solaris,
+.bP
+The initial release of Solaris was in 1992.
+.bP
+The \fIxpg4\fP (X/Open) curses was developed by MKS from 1990 to 1995.
+Sun's copyright began in 1996.
+.bP
+Sun updated the X/Open curses interface
+after 64-bit support was introduced in 1997,
+but did not modify the SVr4 curses interface.
+.PP
+Regarding U/Win,
+.bP
+Development of the curses library began in 1991, stopped in 2000.
+.bP
+Color support was added in 1998.
+.bP
+The library uses only \fBchtype\fP (no \fBcchar_t\fP).
+.RE
+.PP
+Once X/Open curses was adopted in the mid-1990s, the constraint of
+a 32-bit interface with many colors and wide-characters for \fBchtype\fP
+became a moot point.
+The \fBcchar_t\fP structure (whose size and
+members are not specified in X/Open Curses) could be extended as needed.
+.PP
+Other interfaces are rarely used now:
+.bP
+BSD curses was improved slightly in 1993/1994 using Keith Bostic's
+modification to make the library 8-bit clean for \fBnvi\fP(1).
+He moved \fIstandout\fP attribute to a structure member.
+.IP
+The resulting 4.4BSD curses was replaced by \fI\%ncurses\fP over the
+next ten years.
+.bP
+U/Win is rarely used now.
+.\" ---------------------------------------------------------------------------
.SH SEE ALSO
-.na
-\fBcurses\fR(3X),
-\fBcurs_addch\fR(3X),
-\fBcurs_addstr\fR(3X),
-\fBcurs_bkgd\fR(3X),
-\fBcurs_printw\fR(3X),
-\fBcurs_variables\fR(3X)
+\fB\%curses\fP(3X),
+\fB\%curs_addch\fP(3X),
+\fB\%curs_addstr\fP(3X),
+\fB\%curs_bkgd\fP(3X),
+\fB\%curs_printw\fP(3X),
+\fB\%curs_variables\fP(3X)
diff --git a/man/curs_beep.3x b/man/curs_beep.3x
index c6af6f0..9806f42 100644
--- a/man/curs_beep.3x
+++ b/man/curs_beep.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2005,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2005,2010 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 *
@@ -26,32 +27,37 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_beep.3x,v 1.12 2010/12/04 18:36:44 tom Exp $
-.TH curs_beep 3X ""
+.\" $Id: curs_beep.3x,v 1.29 2024/04/20 21:20:07 tom Exp $
+.TH curs_beep 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBbeep\fR, \fBflash\fR \- \fBcurses\fR bell and screen flash routines
+\fB\%beep\fP,
+\fB\%flash\fP \-
+ring the (visual) bell of the terminal with \fIcurses\fR
.SH SYNOPSIS
-\fB#include <curses.h>\fR
+.nf
+\fB#include <curses.h>
.PP
-\fBint beep(void);\fR
-.br
-\fBint flash(void);\fR
-.br
+\fBint beep(void);
+\fBint flash(void);
+.fi
.SH DESCRIPTION
-The \fBbeep\fR and \fBflash\fR routines are used to alert the terminal user.
-The routine \fBbeep\fR sounds an audible alarm on the terminal, if possible;
-otherwise it flashes the screen (visible bell). The routine \fBflash\fR
-flashes the screen, and if that is not possible, sounds the alert. If neither
-alert is possible, nothing happens. Nearly all terminals have an audible alert
+The \fBbeep\fP and \fBflash\fP routines are used to alert the terminal user.
+The routine \fBbeep\fP sounds an audible alarm on the terminal, if possible;
+otherwise it flashes the screen (visible bell).
+The routine \fBflash\fP
+flashes the screen, and if that is not possible, sounds the alert.
+If neither
+alert is possible, nothing happens.
+Nearly all terminals have an audible alert
(bell or beep), but only some can flash the screen.
.SH RETURN VALUE
-These routines return \fBOK\fR if they succeed in beeping or flashing,
-\fBERR\fR otherwise.
+These routines return \fBOK\fP if they succeed in beeping or flashing,
+\fBERR\fP otherwise.
.SH EXTENSIONS
-SVr4's beep and flash routines always returned \fBOK\fR, so it was not
+SVr4's beep and flash routines always returned \fBOK\fP, so it was not
possible to tell when the beep or flash failed.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
-Like SVr4, it specifies that they always return \fBOK\fR.
+These functions are described in X/Open Curses, Issue 4.
+Like SVr4, it specifies that they always return \fBOK\fP.
.SH SEE ALSO
-\fBcurses\fR(3X)
+\fB\%curses\fP(3X)
diff --git a/man/curs_bkgd.3x b/man/curs_bkgd.3x
index 50c3b30..25ba1f9 100644
--- a/man/curs_bkgd.3x
+++ b/man/curs_bkgd.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2015 Free Software Foundation, Inc. *
+.\" 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 *
.\" copy of this software and associated documentation files (the *
@@ -26,78 +27,200 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_bkgd.3x,v 1.23 2015/07/21 00:11:05 tom Exp $
+.\" $Id: curs_bkgd.3x,v 1.61 2024/04/20 18:54:36 tom Exp $
+.TH curs_bkgd 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.TH curs_bkgd 3X ""
.SH NAME
-\fBbkgdset\fR, \fBwbkgdset\fR,
-\fBbkgd\fR, \fBwbkgd\fR,
-\fBgetbkgd\fR \- \fBcurses\fR window background manipulation routines
+\fB\%bkgdset\fP,
+\fB\%wbkgdset\fP,
+\fB\%bkgd\fP,
+\fB\%wbkgd\fP,
+\fB\%getbkgd\fP \-
+manipulate background of a \fIcurses\fR window of characters
.SH SYNOPSIS
-\fB#include <curses.h>\fR
+.nf
+\fB#include <curses.h>
.PP
-\fBvoid bkgdset(chtype \fP\fIch\fP\fB);\fR
-.br
-\fBvoid wbkgdset(WINDOW *\fP\fIwin, chtype \fP\fIch\fP\fB);\fR
-.br
-\fBint bkgd(chtype \fP\fIch\fP\fB);\fR
-.br
-\fBint wbkgd(WINDOW *\fP\fIwin\fP\fB, chtype \fP\fIch\fP\fB);\fR
-.br
-\fBchtype getbkgd(WINDOW *\fP\fIwin\fP\fB);\fR
-.br
+\fBint bkgd(chtype \fIch\fP);
+\fBint wbkgd(WINDOW *\fIwin\fP, chtype \fIch\fP);
+.PP
+\fBvoid bkgdset(chtype \fIch\fP);
+\fBvoid wbkgdset(WINDOW *\fIwin\fP, chtype \fIch\fP);
+.PP
+\fBchtype getbkgd(WINDOW *\fIwin\fP);
+.fi
.SH DESCRIPTION
-.SS bkgdset
-The \fBbkgdset\fR and \fBwbkgdset\fR routines manipulate the
-background of the named window.
-The window background is a \fBchtype\fR consisting of
-any combination of attributes (i.e., rendition) and a character.
-The attribute part of the background is combined (OR'ed) with all non-blank
-characters that are written into the window with \fBwaddch\fR. Both
-the character and attribute parts of the background are combined with
-the blank characters. The background becomes a property of the
-character and moves with the character through any scrolling and
-insert/delete line/character operations.
+The
+.I background
+of a
+.I curses
+window
+(in the library's non-\*(``wide\*('' configuration)
+is a
+.I \%chtype
+combining a set of attributes
+(see \fB\%curs_attr\fP(3X))
+with a character called the
+.I "blank character."
.PP
-To the extent possible on a particular terminal,
-the attribute part of the background is displayed
-as the graphic rendition of the character put on the screen.
-.SS bkgd
+The blank character is a spacing character that populates a window's
+character cells when their contents are erased without replacement.
+The background's attributes are combined with all non-blank characters
+written to the window,
+as with the \fB\%waddch\fP(3X) and \fB\%winsch\fP(3X) families of
+functions.
.PP
-The \fBbkgd\fR and \fBwbkgd\fR functions
-set the background property of the current or specified window
-and then apply this setting to every character position in that window:
+The blank character and attributes of the background combine with
+characters written to the window as described below.
+The background becomes a property of the character and moves with it
+through any scrolling and insert/delete line/character operations.
.PP
+To the extent possible on a given terminal,
+the attribute part of the background is displayed as the graphic
+rendition of the character put on the screen.
+.SS "bkgd, wbkgd"
+\fB\%bkgd\fP and \fB\%wbkgd\fP set the background property of
+\fB\%stdscr\fP or the specified window and then apply this setting to
+every character cell in that window.
.bP
-The rendition of every character on the screen is changed to
-the new background rendition.
+The rendition of every character in the window changes to the new
+background rendition.
.bP
-Wherever the former background character
-appears, it is changed to the new background character.
-.RE
+Wherever the former background character appears,
+it changes to the new background character.
+.PP
+.I \%ncurses
+updates the rendition of each character cell by comparing the character,
+non-color attributes,
+and colors.
+The library applies to following procedure to each cell in the window,
+whether or not it is blank.
+.bP
+.I \%ncurses
+first compares the cell's character to the previously specified blank
+character;
+if they match,
+.I \%ncurses
+writes the new blank character to the cell.
+.bP
+.I \%ncurses
+then checks if the cell uses color,
+that is,
+its color pair value is nonzero.
+If not,
+it simply replaces the attributes and color pair in the cell with those
+from the new background character.
+.bP
+If the cell uses color,
+and its background color matches that of the current window background,
+.I \%ncurses
+removes attributes that may have come from the current background and
+adds those from the new background.
+It finishes by setting the cell's background to use the new window
+background color.
+.bP
+If the cell uses color,
+and its background color does not match that of the current window
+background,
+.I \%ncurses
+updates only the non-color attributes,
+first removing those that may have come from the current background,
+and then adding attributes from the new background.
+.PP
+.I \%ncurses
+treats a background character value of zero (0) as a blank character.
+.PP
+If the terminal does not support color,
+or if color has not been initialized with \fB\%start_color\fP(3X),
+.I \%ncurses
+ignores the new background character's color attribute.
+.SS "bkgdset, wbkgdset"
+\fB\%bkgdset\fP and \fB\%wbkgdset\fP manipulate the background of
+the applicable window,
+without updating the character cells as \fB\%bkgd\fP and
+\fB\%wbkgd\fP do;
+only future writes reflect the updated background.
.SS getbkgd
-.PP
-The \fBgetbkgd\fR function returns the given window's current background
-character/attribute pair.
+\fB\%getbkgd\fP obtains the given window's background character and
+attribute combination.
.SH RETURN VALUE
+Functions returning an \fIint\fP return \fBOK\fP on success.
+\fB\%bkgd\fP returns \fBERR\fP if the library has not been initialized.
+\fB\%wbkgd\fP and \fB\%getbkgd\fP return \fBERR\fP if a \fI\%WINDOW\fP
+pointer argument is null.
.PP
-The routines \fBbkgd\fR and \fBwbkgd\fR return the integer \fBOK\fR.
-The SVr4.0 manual says "or a non-negative integer if \fBimmedok\fR is set",
-but this appears to be an error.
+\fB\%bkgdset\fP and \fBwbkgdset\fP do not return a value.
+.PP
+\fB\%getbkgd\fP returns a window's background character and attribute
+combination.
.SH NOTES
+Unusually,
+there is no \fB\%wgetbkgd\fP function;
+\fB\%getbkgd\fP behaves as one would expect \fB\%wgetbkgd\fP to,
+accepting a \fI\%WINDOW\fP pointer argument.
.PP
-Note that \fBbkgdset\fR and \fBbkgd\fR may be macros.
+\fB\%bkgd\fP and
+\fB\%bkgdset\fP
+may be implemented as macros.
+.PP
+X/Open Curses mentions that the character part of the background must
+be a single-byte value.
+\fI\%ncurses\fP,
+like SVr4 \fIcurses\fP,
+checks to ensure that,
+and will reuse the old background character if the check fails.
.SH PORTABILITY
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies that
+\fB\%bkgd\fP,
+\fB\%wbkgd\fP,
+and
+\fB\%getbkgd\fP
+return \fBERR\fP on failure
+(in the case of the last,
+this value is cast to
+.IR \%chtype ),
+but describes no failure conditions.
.PP
-These functions are described in the XSI Curses standard, Issue 4.
-It specifies that \fBbkgd\fR and \fBwbkgd\fR return \fBERR\fR on failure,
-but gives no failure conditions.
+The SVr4.0 manual says that \fB\%bkgd\fP and \fB\%wbkgd\fP may return
+\fBOK\fP
+\*(``or a non-negative integer if \fB\%immedok\fP is set\*('',
+which refers to the return value from \fB\%wrefresh\fP(3X),
+used to implement the immediate repainting.
+SVr4 \fIcurses\fP's \fB\%wrefresh\fP returns the number of characters
+written to the screen during the refresh.
+\fI\%ncurses\fP does not do that.
+.PP
+Neither X/Open Curses nor the SVr4 manual pages detail how the rendition
+of characters on the screen updates when \fB\%bkgd\fP or \fB\%wbkgd\fP
+changes the background character.
+.IR \%ncurses ,
+like SVr4
+.IR curses ,
+does not
+(in its non-\*(``wide\*('' configuration)
+store the background and window attribute contributions to each
+character cell separately.
.SH SEE ALSO
-.na
+\fB\%curs_bkgrnd\fP(3X) describes the corresponding functions in the
+\*(``wide\*('' configuration of
+.IR \%ncurses .
.PP
-\fBcurses\fR(3X),
-\fBcurs_addch\fR(3X),
-\fBcurs_attr\fR(3X),
-\fBcurs_outopts\fR(3X)
+\fB\%curses\fP(3X),
+\fB\%curs_addch\fP(3X),
+\fB\%curs_attr\fP(3X)
diff --git a/man/curs_bkgrnd.3x b/man/curs_bkgrnd.3x
index 2bbb4fc..2551924 100644
--- a/man/curs_bkgrnd.3x
+++ b/man/curs_bkgrnd.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2012,2015 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 2002-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 *
@@ -26,80 +27,190 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_bkgrnd.3x,v 1.6 2015/07/21 00:18:42 tom Exp $
+.\" $Id: curs_bkgrnd.3x,v 1.42 2024/04/20 18:54:36 tom Exp $
+.TH curs_bkgrnd 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.TH curs_bkgrnd 3X ""
.SH NAME
-\fBbkgrnd\fR,
-\fBwbkgrnd\fR,
-\fBbkgrndset\fR,
-\fBwbkgrndset\fR,
-\fBgetbkgrnd\fR,
-\fBwgetbkgrnd\fR \- \fBcurses\fR window complex background manipulation routines
+\fB\%bkgrnd\fP,
+\fB\%wbkgrnd\fP,
+\fB\%bkgrndset\fP,
+\fB\%wbkgrndset\fP,
+\fB\%getbkgrnd\fP,
+\fB\%wgetbkgrnd\fP \-
+manipulate background of a \fIcurses\fP window of wide characters
.SH SYNOPSIS
+.nf
+\fB#include <curses.h>
.PP
-.B #include <curses.h>
-.sp
-\fBint bkgrnd(\fR\fB const cchar_t *\fR\fIwch\fR\fB);\fR
-.br
-\fBint wbkgrnd(\fR\fB WINDOW *\fR\fIwin\fR\fB, const cchar_t *\fR\fIwch\fR\fB);\fR
-.br
-\fBvoid bkgrndset(const cchar_t *\fR\fIwch\fR \fB);\fR
-.br
-\fBvoid wbkgrndset(WINDOW *\fR\fIwin\fR\fB, const cchar_t *\fR\fIwch\fR\fB);\fR
-.br
-\fBint getbkgrnd(cchar_t *\fR\fIwch\fR\fB);\fR
-.br
-\fBint wgetbkgrnd(WINDOW *\fR\fIwin\fR\fB, cchar_t *\fR\fIwch\fR\fB);\fR
-.br
+\fBint bkgrnd(const cchar_t *\fIwch\fP);
+\fBint wbkgrnd(WINDOW *\fIwin\fP, const cchar_t *\fIwch\fP);
+.PP
+\fBvoid bkgrndset(const cchar_t *\fIwch\fP);
+\fBvoid wbkgrndset(WINDOW *\fIwin\fP, const cchar_t *\fIwch\fP);
+.PP
+\fBint getbkgrnd(cchar_t *\fIwch\fP);
+\fBint wgetbkgrnd(WINDOW *\fIwin\fP, cchar_t *\fIwch\fP);
+.fi
.SH DESCRIPTION
-.SS bkgrndset
+The
+.I background
+of a
+.I curses
+window
+(in the library's \*(``wide\*('' configuration)
+is a
+.I \%cchar_t
+combining a set of attributes
+(see \fB\%curs_attr\fP(3X))
+with a complex character called the
+.I "blank character."
.PP
-The \fBbkgrndset\fR and \fBwbkgrndset\fR routines manipulate the
-background of the named window.
-The window background is a \fBcchar_t\fR consisting of
-any combination of attributes (i.e., rendition) and a complex character.
-The attribute part of the background is combined (OR'ed) with all non-blank
-characters that are written into the window with \fBwaddch\fR. Both
-the character and attribute parts of the background are combined with
-the blank characters.
-The background becomes a property of the
-character and moves with the character through any scrolling and
-insert/delete line/character operations.
+The blank character is a spacing character that populates a window's
+character cells when their contents are erased without replacement.
+The background's attributes are combined with all non-blank characters
+written to the window,
+as with the \fB\%wadd_wch\fP(3X) and \fB\%wins_wch\fP(3X) families of
+functions.
.PP
-To the extent possible on a
-particular terminal, the attribute part of the background is displayed
-as the graphic rendition of the character put on the screen.
-.SS bkgrnd
+The blank character and attributes of the background combine with
+characters written to the window as described below.
+The background becomes a property of the character and moves with it
+through any scrolling and insert/delete line/character operations.
.PP
-The \fBbkgrnd\fR and \fBwbkgrnd\fR functions
-set the background property of the current or specified window
-and then apply this setting to every character position in that window:
+To the extent possible on a given terminal,
+the attribute part of the background is displayed as the graphic
+rendition of the character put on the screen.
+.SS "bkgrnd, wbkgrnd"
+\fB\%bkgrnd\fP and \fB\%wbkgrnd\fP set the background property of
+\fB\%stdscr\fP or the specified window and then apply this setting to
+every character cell in that window.
.bP
-The rendition of every character on the screen is changed to
-the new background rendition.
+The rendition of every character in the window changes to the new
+background rendition.
.bP
-Wherever the former background character
-appears, it is changed to the new background character.
-.SS getbkgrnd
+Wherever the former background character appears,
+it changes to the new background character.
.PP
-The \fBgetbkgrnd\fR function returns the given window's current background
-character/attribute pair via the \fBwch\fR pointer.
-.SH NOTES
-Note that
-\fBbkgrnd\fR,
-\fBbkgrndset\fR, and
-\fBgetbkgrnd\fR
-may be macros.
+.I \%ncurses
+updates the rendition of each character cell by comparing the character,
+non-color attributes,
+and colors.
+The library applies to following procedure to each cell in the window,
+whether or not it is blank.
+.bP
+.I \%ncurses
+first compares the cell's character to the previously specified blank
+character;
+if they match,
+.I \%ncurses
+writes the new blank character to the cell.
+.bP
+.I \%ncurses
+then checks if the cell uses color,
+that is,
+its color pair value is nonzero.
+If not,
+it simply replaces the attributes and color pair in the cell with those
+from the new background character.
+.bP
+If the cell uses color,
+and its background color matches that of the current window background,
+.I \%ncurses
+removes attributes that may have come from the current background and
+adds those from the new background.
+It finishes by setting the cell's background to use the new window
+background color.
+.bP
+If the cell uses color,
+and its background color does not match that of the current window
+background,
+.I \%ncurses
+updates only the non-color attributes,
+first removing those that may have come from the current background,
+and then adding attributes from the new background.
+.PP
+.I \%ncurses
+treats a background character value of zero (0) as a blank character.
+.PP
+If the terminal does not support color,
+or if color has not been initialized with \fB\%start_color\fP(3X),
+.I \%ncurses
+ignores the new background character's color attribute.
+.SS "bkgrndset, wbkgrndset"
+\fB\%bkgrndset\fP and \fB\%wbkgrndset\fP manipulate the background of
+the applicable window,
+without updating the character cells as \fB\%bkgrnd\fP and
+\fB\%wbkgrnd\fP do;
+only future writes reflect the updated background.
+.SS "getbkgrnd, wgetbkgrnd"
+The \fB\%getbkgrnd\fP and \fB\%wgetbkgrnd\fP functions obtain the
+background character and attribute pair of \fB\%stdscr\fP or the
+specified window and store it via the
+.I wch
+pointer.
.SH RETURN VALUE
+\fBbkgrndset\fP and \fBwbkgrndset\fP do not return a value.
.PP
-The \fBbkgrndset\fR and \fBwbkgrndset\fR routines do not return a value.
+The other functions return
+.B ERR
+upon failure and
+.B OK
+upon success.
+In
+.IR \%ncurses ,
+failure occurs if
+.bP
+a
+.I \%WINDOW
+pointer
+.I win
+is null, or
+.bP
+a
+.I \%cchar_t
+pointer
+.I wch
+is null.
+.SH NOTES
+\fB\%bkgrnd\fP,
+\fB\%bkgrndset\fP, and
+\fB\%getbkgrnd\fP
+may be implemented as macros.
.PP
-Upon successful completion, the other functions return \fBOK\fR.
-Otherwise, they return \fBERR\fR.
-A null window pointer is treated as an error.
+Unlike their counterparts in the non-\*(``wide\*('' configuration of
+.IR \%ncurses ,
+\fB\%getbkgrnd\fP and \fB\%wgetbkgrnd\fP supply the background character
+and attribute in a modifiable
+.I \%cchar_t
+parameter,
+not as the return value.
+.SH PORTABILITY
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+.PP
+X/Open Curses does not provide details of how the rendition is updated.
+This implementation follows the approach used in SVr4
+.IR curses .
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_bkgd\fR(3X)
+\fB\%curs_bkgd\fP(3X) describes the corresponding functions in the
+non-\*(``wide\*('' configuration of
+.IR \%ncurses .
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_add_wch\fP(3X),
+\fB\%curs_attr\fP(3X)
diff --git a/man/curs_border.3x b/man/curs_border.3x
index 5a58e9d..2a5e72c 100644
--- a/man/curs_border.3x
+++ b/man/curs_border.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2007,2010 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 *
@@ -26,128 +27,136 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_border.3x,v 1.22 2010/12/04 18:36:44 tom Exp $
-.TH curs_border 3X ""
-.na
-.hy 0
+.\" $Id: curs_border.3x,v 1.49 2024/04/20 21:20:07 tom Exp $
+.TH curs_border 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-\fBborder\fR,
-\fBwborder\fR,
-\fBbox\fR,
-\fBhline\fR,
-\fBwhline\fR,
-\fBvline\fR,
-\fBwvline\fR,
-\fBmvhline\fR,
-\fBmvwhline\fR,
-\fBmvvline\fR,
-\fBmvwvline\fR \- create \fBcurses\fR borders, horizontal and vertical lines
-.ad
-.hy
+\fB\%border\fP,
+\fB\%wborder\fP,
+\fB\%box\fP,
+\fB\%hline\fP,
+\fB\%whline\fP,
+\fB\%vline\fP,
+\fB\%wvline\fP,
+\fB\%mvhline\fP,
+\fB\%mvwhline\fP,
+\fB\%mvvline\fP,
+\fB\%mvwvline\fP \-
+draw borders and lines in a \fIcurses\fR window of characters
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.br
-\fBint border(chtype ls, chtype rs, chtype ts, chtype bs,\fR
- \fBchtype tl, chtype tr, chtype bl, chtype br);\fR
-.br
-\fBint wborder(WINDOW *win, chtype ls, chtype rs,\fR
- \fBchtype ts, chtype bs, chtype tl, chtype tr,\fR
- \fBchtype bl, chtype br);\fR
-.br
-\fBint box(WINDOW *win, chtype verch, chtype horch);\fR
-.br
-\fBint hline(chtype ch, int n);\fR
-.br
-\fBint whline(WINDOW *win, chtype ch, int n);\fR
-.br
-\fBint vline(chtype ch, int n);\fR
-.br
-\fBint wvline(WINDOW *win, chtype ch, int n);\fR
-.br
-\fBint mvhline(int y, int x, chtype ch, int n);\fR
-.br
-\fBint mvwhline(WINDOW *, int y, int x, chtype ch, int n);\fR
-.br
-\fBint mvvline(int y, int x, chtype ch, int n);\fR
-.br
-\fBint mvwvline(WINDOW *, int y, int x, chtype ch, int n);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint border(chtype \fIls\fP, chtype \fIrs\fP, chtype \fIts\fP, chtype \fIbs\fP,
+ \fBchtype \fItl\fB, chtype \fItr\fB, chtype \fIbl\fB, chtype \fIbr\fB);\fR
+\fBint wborder(WINDOW *\fIwin\fB, chtype \fIls\fB, chtype \fIrs\fB,\fR
+ \fBchtype \fIts\fB, chtype \fIbs\fB, chtype \fItl\fB, chtype \fItr\fB,\fR
+ \fBchtype \fIbl\fB, chtype \fIbr\fB);\fR
+.PP
+\fBint box(WINDOW *\fIwin\fB, chtype \fIverch\fB, chtype \fIhorch\fB);\fR
+.PP
+\fBint hline(chtype \fIch\fB, int \fIn\fB);\fR
+\fBint whline(WINDOW *\fIwin\fB, chtype \fIch\fB, int \fIn\fB);\fR
+\fBint vline(chtype \fIch\fB, int \fIn\fB);\fR
+\fBint wvline(WINDOW *\fIwin\fB, chtype \fIch\fB, int \fIn\fB);\fR
+.PP
+\fBint mvhline(int \fIy\fB, int \fIx\fB, chtype \fIch\fB, int \fIn\fB);\fR
+\fBint mvwhline(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, chtype \fIch\fB, int \fIn\fB);\fR
+\fBint mvvline(int \fIy\fB, int \fIx\fB, chtype \fIch\fB, int \fIn\fB);\fR
+\fBint mvwvline(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, chtype \fIch\fB, int \fIn\fB);\fR
+.fi
.SH DESCRIPTION
-The \fBborder\fR, \fBwborder\fR and \fBbox\fR routines
+The \fBborder\fP, \fBwborder\fP and \fBbox\fP routines
draw a box around the edges of a window.
Other than the window, each argument is a character with attributes:
.sp
.RS
-\fIls\fR \- left side,
+\fIls\fP \- left side,
.br
-\fIrs\fR \- right side,
+\fIrs\fP \- right side,
.br
-\fIts\fR \- top side,
+\fIts\fP \- top side,
.br
-\fIbs\fR \- bottom side,
+\fIbs\fP \- bottom side,
.br
-\fItl\fR \- top left-hand corner,
+\fItl\fP \- top left-hand corner,
.br
-\fItr\fR \- top right-hand corner,
+\fItr\fP \- top right-hand corner,
.br
-\fIbl\fR \- bottom left-hand corner, and
+\fIbl\fP \- bottom left-hand corner, and
.br
-\fIbr\fR \- bottom right-hand corner.
+\fIbr\fP \- bottom right-hand corner.
.RE
.PP
If any of these arguments is zero, then the corresponding
-default values (defined in \fBcurses.h\fR) are used instead:
+default values (defined in \fBcurses.h\fP) are used instead:
.sp
.RS
-\fBACS_VLINE\fR,
+\fBACS_VLINE\fP,
.br
-\fBACS_VLINE\fR,
+\fBACS_VLINE\fP,
.br
-\fBACS_HLINE\fR,
+\fBACS_HLINE\fP,
.br
-\fBACS_HLINE\fR,
+\fBACS_HLINE\fP,
.br
-\fBACS_ULCORNER\fR,
+\fBACS_ULCORNER\fP,
.br
-\fBACS_URCORNER\fR,
+\fBACS_URCORNER\fP,
.br
-\fBACS_LLCORNER\fR,
+\fBACS_LLCORNER\fP,
.br
-\fBACS_LRCORNER\fR.
+\fBACS_LRCORNER\fP.
.RE
.PP
-\fBbox(\fR\fIwin\fR\fB, \fR\fIverch\fR\fB, \fR\fIhorch\fR\fB)\fR is a shorthand
-for the following call: \fBwborder(\fR\fIwin\fR\fB,\fR \fIverch\fR\fB,\fR
-\fIverch\fR\fB,\fR \fIhorch\fR\fB,\fR \fIhorch\fR\fB, 0, 0, 0, 0)\fR.
+\fBbox(\fIwin\fB, \fIverch\fB, \fIhorch\fB)\fR is a shorthand
+for the following call: \fBwborder(\fIwin\fB,\fR \fIverch\fB,\fR
+\fIverch\fB,\fR \fIhorch\fB,\fR \fIhorch\fB, 0, 0, 0, 0)\fR.
.PP
-The \fBhline\fR and \fBwhline\fR functions draw a horizontal (left to right)
-line using \fIch\fR starting at the current cursor position in the window. The
-current cursor position is not changed. The line is at most \fIn\fR characters
+The \fBhline\fP and \fBwhline\fP functions draw a horizontal (left to right)
+line using \fIch\fP starting at the current cursor position in the window.
+The
+current cursor position is not changed.
+The line is at most \fIn\fP characters
long, or as many as fit into the window.
.PP
-The \fBvline\fR and \fBwvline\fR functions draw a vertical (top to bottom) line
-using \fIch\fR starting at the current cursor position in the window. The
-current cursor position is not changed. The line is at most \fIn\fR characters
+The \fBvline\fP and \fBwvline\fP functions draw a vertical (top to bottom) line
+using \fIch\fP starting at the current cursor position in the window.
+The
+current cursor position is not changed.
+The line is at most \fIn\fP characters
long, or as many as fit into the window.
.SH RETURN VALUE
-All routines return the integer \fBOK\fR. The SVr4.0 manual says "or a
-non-negative integer if \fBimmedok\fR is set", but this appears to be an error.
+All routines return the integer \fBOK\fP.
+The SVr4.0 manual says
+\*(``or a non-negative integer if \fB\%immedok\fP is set\*('',
+but this appears to be an error.
.PP
-X/Open does not define any error conditions.
+X/Open Curses does not specify any error conditions.
This implementation returns an error
if the window pointer is null.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
-The borders generated by these functions are \fIinside\fR borders (this
+The borders generated by these functions are \fIinside\fP borders (this
is also true of SVr4 curses, though the fact is not documented).
.PP
-Note that \fBborder\fR and \fBbox\fR may be macros.
+Note that \fBborder\fP and \fBbox\fP may be macros.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
-The standard specifies that they return \fBERR\fR on failure,
-but specifies no error conditions.
+These functions are described in X/Open Curses, Issue 4.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_outopts\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_outopts\fP(3X)
diff --git a/man/curs_border_set.3x b/man/curs_border_set.3x
index c9621ac..3077da6 100644
--- a/man/curs_border_set.3x
+++ b/man/curs_border_set.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2011,2012 Free Software Foundation, Inc. *
+.\" Copyright 2019-2023,2024 Thomas E. Dickey *
+.\" Copyright 2002-2011,2012 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 *
@@ -26,181 +27,177 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_border_set.3x,v 1.11 2012/11/03 23:03:59 tom Exp $
-.TH curs_border_set 3X ""
-.na
-.hy 0
+.\" $Id: curs_border_set.3x,v 1.36 2024/04/20 21:20:07 tom Exp $
+.TH curs_border_set 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-\fBborder_set\fR,
-\fBwborder_set\fR,
-\fBbox_set\fR,
-\fBhline_set\fR,
-\fBwhline_set\fR,
-\fBmvhline_set\fR,
-\fBmvwhline_set\fR,
-\fBvline_set\fR,
-\fBwvline_set\fR,
-\fBmvvline_set\fR,
-\fBmvwvline_set\fR \- create \fBcurses\fR borders or lines using complex characters and renditions
-.ad
-.hy
+\fB\%border_set\fP,
+\fB\%wborder_set\fP,
+\fB\%box_set\fP,
+\fB\%hline_set\fP,
+\fB\%whline_set\fP,
+\fB\%mvhline_set\fP,
+\fB\%mvwhline_set\fP,
+\fB\%vline_set\fP,
+\fB\%wvline_set\fP,
+\fB\%mvvline_set\fP,
+\fB\%mvwvline_set\fP \-
+draw borders and lines in a \fIcurses\fR window of wide characters
.SH SYNOPSIS
+.nf
+\fB#include <curses.h>
.PP
-\fB#include <curses.h>\fR
-.sp
-\fBint border_set(\fR
- \fBconst cchar_t *\fR\fIls\fR, \fBconst cchar_t *\fR\fIrs\fR,
- \fBconst cchar_t *\fR\fIts\fR, \fBconst cchar_t *\fR\fIbs\fR,
- \fBconst cchar_t *\fR\fItl\fR, \fBconst cchar_t *\fR\fItr\fR,
- \fBconst cchar_t *\fR\fIbl\fR, \fBconst cchar_t *\fR\fIbr\fR
-\fB);\fR
+\fBint border_set(
+ \fBconst cchar_t *\fIls\fB, const cchar_t *\fIrs\fP,
+ \fBconst cchar_t *\fIts\fB, const cchar_t *\fIbs\fP,
+ \fBconst cchar_t *\fItl\fB, const cchar_t *\fItr\fP,
+ \fBconst cchar_t *\fIbl\fB, const cchar_t *\fIbr\fB);\fR
.br
-\fBint wborder_set(\fR
- \fBWINDOW *win\fR,
- \fBconst cchar_t *\fR\fIls\fR, \fBconst cchar_t *\fR\fIrs\fR,
- \fBconst cchar_t *\fR\fIts\fR, \fBconst cchar_t *\fR\fIbs\fR,
- \fBconst cchar_t *\fR\fItl\fR, \fBconst cchar_t *\fR\fItr\fR,
- \fBconst cchar_t *\fR\fIbl\fR, \fBconst cchar_t *\fR\fIbr\fR\fB);\fR
-.br
-\fBint box_set(\fR
- \fBWINDOW *win\fR,
- \fBconst cchar_t *\fR\fIverch\fR,
- \fBconst cchar_t *\fR\fIhorch\fR\fB);\fR
-.br
-\fBint hline_set(\fR
- \fBconst cchar_t *\fR\fIwch\fR, \fBint \fR\fIn\fR\fB);\fR
-.br
-\fBint whline_set(\fR
- \fBWINDOW *\fR\fIwin\fR,
- \fBconst cchar_t *\fR\fIwch\fR, \fBint \fR\fIn\fR\fB);\fR
-.br
-\fBint mvhline_set(\fR
- \fBint \fR\fIy\fR, \fBint \fR\fIx\fR,
- \fBconst cchar_t *\fR\fIwch\fR, \fBint \fR\fIn\fR\fB);\fR
-.br
-\fBint mvwhline_set(\fR
- \fBWINDOW *\fR\fIwin\fR,
- \fBint \fR\fIy\fR, \fBint \fR\fIx\fR,
- \fBconst cchar_t *\fR\fIwch\fR, \fBint \fR\fIn\fR\fB);\fR
-.br
-\fBint vline_set(\fR
- \fBconst cchar_t *\fR\fIwch\fR, \fBint \fR\fIn\fR\fB);\fR
-.br
-\fBint wvline_set(\fR
- \fBWINDOW *\fR\fIwin\fR,
- \fBconst cchar_t *\fR\fIwch\fR, \fBint \fR\fIn\fR\fB);\fR
-.br
-\fBint mvvline_set(\fR
- \fBint \fR\fIy\fR, \fBint \fR\fIx\fR,
- \fBconst cchar_t *\fR\fIwch\fR, \fBint \fR\fIn\fR\fB);\fR
-.br
-\fBint mvwvline_set(\fR
- \fBWINDOW *\fR\fIwin\fR,
- \fBint \fR\fIy\fR, \fBint \fR\fIx\fR,
- \fBconst cchar_t *\fR\fIwch\fR, \fBint \fR\fIn\fR\fB);\fR
-.br
+\fBint wborder_set(\fP
+ \fBWINDOW *\fIwin\fP,
+ \fBconst cchar_t *\fIls\fB, const cchar_t *\fIrs\fP,
+ \fBconst cchar_t *\fIts\fB, const cchar_t *\fIbs\fP,
+ \fBconst cchar_t *\fItl\fB, const cchar_t *\fItr\fP,
+ \fBconst cchar_t *\fIbl\fB, const cchar_t *\fIbr\fB);\fR
+\fBint box_set(\fP
+ \fBWINDOW *\fIwin\fP,
+ \fBconst cchar_t *\fIverch\fP,
+ \fBconst cchar_t *\fIhorch\fB);\fR
+\fBint hline_set(\fP
+ \fBconst cchar_t *\fIwch\fB, int \fIn\fB);\fR
+\fBint whline_set(\fP
+ \fBWINDOW *\fIwin\fP,
+ \fBconst cchar_t *\fIwch\fB, int \fIn\fB);\fR
+\fBint mvhline_set(\fP
+ \fBint \fIy\fB, int \fIx\fP,
+ \fBconst cchar_t *\fIwch\fB, int \fIn\fB);\fR
+\fBint mvwhline_set(\fP
+ \fBWINDOW *\fIwin\fP,
+ \fBint \fIy\fB, int \fIx\fP,
+ \fBconst cchar_t *\fIwch\fB, int \fIn\fB);\fR
+\fBint vline_set(\fP
+ \fBconst cchar_t *\fIwch\fB, int \fIn\fB);\fR
+\fBint wvline_set(\fP
+ \fBWINDOW *\fIwin\fP,
+ \fBconst cchar_t *\fIwch\fB, int \fIn\fB);\fR
+\fBint mvvline_set(\fP
+ \fBint \fIy\fB, int \fIx\fP,
+ \fBconst cchar_t *\fIwch\fB, int \fIn\fB);\fR
+\fBint mvwvline_set(\fP
+ \fBWINDOW *\fIwin\fP,
+ \fBint \fIy\fB, int \fIx\fP,
+ \fBconst cchar_t *\fIwch\fB, int \fIn\fB);\fR
+.fi
.SH DESCRIPTION
-.PP
The
-\fBborder_set\fR
+\fBborder_set\fP
and
-\fBwborder_set\fR
+\fBwborder_set\fP
functions draw a border around the edges of the current or specified window.
These functions do not change the cursor position, and do not wrap.
.PP
Other than the window, each argument is a complex character with attributes:
.RS
-\fIls\fR \- left side,
+\fIls\fP \- left side,
.br
-\fIrs\fR \- right side,
+\fIrs\fP \- right side,
.br
-\fIts\fR \- top side,
+\fIts\fP \- top side,
.br
-\fIbs\fR \- bottom side,
+\fIbs\fP \- bottom side,
.br
-\fItl\fR \- top left-hand corner,
+\fItl\fP \- top left-hand corner,
.br
-\fItr\fR \- top right-hand corner,
+\fItr\fP \- top right-hand corner,
.br
-\fIbl\fR \- bottom left-hand corner, and
+\fIbl\fP \- bottom left-hand corner, and
.br
-\fIbr\fR \- bottom right-hand corner.
+\fIbr\fP \- bottom right-hand corner.
.RE
.PP
If any of these arguments is zero, then the corresponding
-default values (defined in \fBcurses.h\fR) are used instead:
+default values (defined in \fBcurses.h\fP) are used instead:
.RS
-\fBWACS_VLINE\fR,
+\fBWACS_VLINE\fP,
.br
-\fBWACS_VLINE\fR,
+\fBWACS_VLINE\fP,
.br
-\fBWACS_HLINE\fR,
+\fBWACS_HLINE\fP,
.br
-\fBWACS_HLINE\fR,
+\fBWACS_HLINE\fP,
.br
-\fBWACS_ULCORNER\fR,
+\fBWACS_ULCORNER\fP,
.br
-\fBWACS_URCORNER\fR,
+\fBWACS_URCORNER\fP,
.br
-\fBWACS_LLCORNER\fR, and
+\fBWACS_LLCORNER\fP, and
.br
-\fBWACS_LRCORNER\fR.
+\fBWACS_LRCORNER\fP.
.RE
.PP
-\fBbox_set(\fR\fIwin\fR, \fIverch\fR\fB, \fR\fIhorch\fR\fB);\fR
+\fBbox_set(\fIwin\fR, \fIverch\fB, \fIhorch\fB);\fR
is a shorthand for the following call:
.PP
-\fBwborder_set(\fR\fIwin\fR\fB, \fR\fIverch\fR\fB, \fR\fIverch\fR\fB,\fR
- \fIhorch\fR\fB, \fR\fIhorch\fR\fB, NULL, NULL, NULL, NULL);\fR
+\fBwborder_set(\fIwin\fB, \fIverch\fB, \fIverch\fB,\fR
+ \fIhorch\fB, \fIhorch\fB, NULL, NULL, NULL, NULL);\fR
.PP
The
-\fB*line_set\fR
+\fB*line_set\fP
functions use
-\fIwch\fR
+\fIwch\fP
to draw a line starting at the current cursor position in the window.
-The line is at most \fIn\fR characters long or as many as fit into the window.
+The line is at most \fIn\fP characters long or as many as fit into the window.
The current cursor position is not changed.
.PP
The
-\fBhline_set\fR,
-\fBmvhline_set\fR,
-\fBmvwhline_set\fR, and
-\fBwhline_set\fR
+\fBhline_set\fP,
+\fBmvhline_set\fP,
+\fBmvwhline_set\fP, and
+\fBwhline_set\fP
functions draw a line proceeding toward the last column of the same line.
.PP
The
-\fBvline_set\fR,
-\fBmvvline_set\fR,
-\fBmvwvline_set\fR, and
-\fBwvline_set\fR
+\fBvline_set\fP,
+\fBmvvline_set\fP,
+\fBmvwvline_set\fP, and
+\fBwvline_set\fP
functions draw a line proceeding toward the last line of the window.
-.br
-.SH NOTES
-.PP
-Note that
-\fBborder_set\fR,
-\fBhline_set\fR,
-\fBmvhline_set\fR,
-\fBmvvline_set\fR,
-\fBmvwhline_set\fR,
-\fBmvwvline_set\fR, and
-\fBvline_set\fR
-may be macros.
-.br
.SH RETURN VALUE
-.PP
Upon successful completion, these functions return
-\fBOK\fR.
+\fBOK\fP.
Otherwise, they return
-\fBERR\fR.
+\fBERR\fP.
.PP
Functions using a window parameter return an error if it is null.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
+.SH NOTES
+Note that
+\fBborder_set\fP,
+\fBhline_set\fP,
+\fBmvhline_set\fP,
+\fBmvvline_set\fP,
+\fBmvwhline_set\fP,
+\fBmvwvline_set\fP, and
+\fBvline_set\fP
+may be macros.
+.SH PORTABILITY
+These functions are described in X/Open Curses, Issue 4.
.SH SEE ALSO
-\fBncurses\fR(3X),
-\fBcurs_add_wch\fR(3X),
-\fBcurs_border\fR(3X),
-\fBcurs_outopts\fR(3X)
+\fB\%curses\fP(3X),
+\fB\%curs_add_wch\fP(3X),
+\fB\%curs_border\fP(3X),
+\fB\%curs_outopts\fP(3X)
diff --git a/man/curs_clear.3x b/man/curs_clear.3x
index 305c608..0ab0064 100644
--- a/man/curs_clear.3x
+++ b/man/curs_clear.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2016 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 *
@@ -26,82 +27,100 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_clear.3x,v 1.14 2010/12/04 18:36:44 tom Exp $
-.TH curs_clear 3X ""
-.na
-.hy 0
+.\" $Id: curs_clear.3x,v 1.48 2024/04/20 21:20:07 tom Exp $
+.TH curs_clear 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBerase\fR,
-\fBwerase\fR,
-\fBclear\fR,
-\fBwclear\fR,
-\fBclrtobot\fR,
-\fBwclrtobot\fR,
-\fBclrtoeol\fR,
-\fBwclrtoeol\fR \- clear all or part of a \fBcurses\fR window
-.ad
-.hy
+\fB\%erase\fP,
+\fB\%werase\fP,
+\fB\%clear\fP,
+\fB\%wclear\fP,
+\fB\%clrtobot\fP,
+\fB\%wclrtobot\fP,
+\fB\%clrtoeol\fP,
+\fB\%wclrtoeol\fP \-
+clear all or part of a \fIcurses\fR window
.SH SYNOPSIS
-\fB# include <curses.h>\fR
-.sp
-\fBint erase(void);\fR
-.br
-\fBint werase(WINDOW *win);\fR
-.br
-\fBint clear(void);\fR
-.br
-\fBint wclear(WINDOW *win);\fR
-.br
-\fBint clrtobot(void);\fR
-.br
-\fBint wclrtobot(WINDOW *win);\fR
-.br
-\fBint clrtoeol(void);\fR
-.br
-\fBint wclrtoeol(WINDOW *win);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint erase(void);
+\fBint werase(WINDOW *\fIwin\fP);
+.PP
+\fBint clear(void);
+\fBint wclear(WINDOW *\fIwin\fP);
+.PP
+\fBint clrtobot(void);
+\fBint wclrtobot(WINDOW *\fIwin\fP);
+.PP
+\fBint clrtoeol(void);
+\fBint wclrtoeol(WINDOW *\fIwin\fP);
+.fi
.SH DESCRIPTION
-The \fBerase\fR and \fBwerase\fR routines copy blanks to every
+.SS "erase, werase"
+The \fBerase\fP and \fBwerase\fP routines copy blanks to every
position in the window, clearing the screen.
.PP
-The \fBclear\fR and \fBwclear\fR routines are like \fBerase\fR and
-\fBwerase\fR, but they also call \fBclearok\fR, so that the screen is
-cleared completely on the next call to \fBwrefresh\fR for that window
-and repainted from scratch.
-.PP
-The \fBclrtobot\fR and \fBwclrtobot\fR routines erase from the cursor to the
-end of screen. That is, they erase all lines below the cursor in the window.
-Also, the current line to the right of the cursor, inclusive, is erased.
-.PP
-The \fBclrtoeol\fR and \fBwclrtoeol\fR routines erase the current line
-to the right of the cursor, inclusive, to the end of the current line.
-.PP
Blanks created by erasure have the current background rendition (as set
-by \fBwbkgdset\fR) merged into them.
+by \fBwbkgdset\fP(3X)) merged into them.
+.SS "clear, wclear"
+The \fBclear\fP and \fBwclear\fP routines are like \fBerase\fP and
+\fBwerase\fP, but they also call \fBclearok\fP(3X), so that the screen is
+cleared completely on the next call to \fBwrefresh\fP for that window
+and repainted from scratch.
+.SS "clrtobot, wclrtobot"
+The \fBclrtobot\fP and \fBwclrtobot\fP routines erase from the cursor to the
+end of screen.
+That is, they erase all lines below the cursor in the window.
+Also, the current line to the right of the cursor, inclusive, is erased.
+.SS "clrtoeol, wclrtoeol"
+The \fBclrtoeol\fP and \fBwclrtoeol\fP routines erase the current line
+to the right of the cursor, inclusive, to the end of the current line.
.SH RETURN VALUE
-All routines return the integer \fBOK\fR on success and \fBERR\fP on failure.
-The SVr4.0 manual says "or a
-non-negative integer if \fBimmedok\fR is set", but this appears to be an error.
+All routines return the integer \fBOK\fP on success and \fBERR\fP on failure.
.PP
X/Open defines no error conditions.
In this implementation,
-functions using a window pointer parameter return an error if it is null.
+.bP
+functions using a window pointer parameter return an error if it is null
+.bP
+\fBwclrtoeol\fP returns an error
+if the cursor position is about to wrap.
.SH NOTES
-Note that \fBerase\fR, \fBwerase\fR, \fBclear\fR, \fBwclear\fR,
-\fBclrtobot\fR, and \fBclrtoeol\fR may be macros.
+Note that \fBerase\fP, \fBwerase\fP, \fBclear\fP, \fBwclear\fP,
+\fBclrtobot\fP, and \fBclrtoeol\fP may be macros.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4. The
-standard specifies that they return \fBERR\fR on failure, but specifies no
-error conditions.
+These functions are described in X/Open Curses, Issue 4.
+.PP
+The SVr4.0 manual says that these functions could return
+\*(``or a non-negative integer if \fB\%immedok\fP is set\*('',
+referring to the return-value of \fBwrefresh\fP.
+In that implementation, \fBwrefresh\fP would return a count of
+the number of characters written to the terminal.
.PP
Some historic curses implementations had, as an undocumented feature, the
-ability to do the equivalent of \fBclearok(..., 1)\fR by saying
-\fBtouchwin(stdscr)\fR or \fBclear(stdscr)\fR. This will not work under
-ncurses.
+ability to do the equivalent of \fBclearok(..., 1)\fP by saying
+\fBtouchwin(stdscr)\fP or \fBclear(stdscr)\fP.
+This will not work under
+\fI\%ncurses\fP.
.PP
This implementation, and others such as Solaris,
sets the current position to 0,0 after erasing
-via \fBwerase()\fP and \fBwclear()\fP.
+via \fBwerase\fP and \fBwclear\fP.
That fact is not documented in other implementations,
and may not be true of implementations
which were not derived from SVr4 source.
@@ -112,7 +131,7 @@
If you do not want to clear the screen during the next \fBwrefresh\fP,
use \fBwerase\fP instead.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_outopts\fR(3X),
-\fBcurs_refresh\fR(3X),
-\fBcurs_variables\fR(3X)
+\fB\%curses\fP(3X),
+\fB\%curs_outopts\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_variables\fP(3X)
diff --git a/man/curs_color.3x b/man/curs_color.3x
index 46af844..7a5a02f 100644
--- a/man/curs_color.3x
+++ b/man/curs_color.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2015 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -26,165 +27,262 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_color.3x,v 1.39 2015/06/06 23:29:02 tom Exp $
-.TH curs_color 3X ""
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: curs_color.3x,v 1.100 2024/04/20 21:24:19 tom Exp $
+.TH curs_color 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.ds n 5
-.na
-.hy 0
+.
.SH NAME
-\fBstart_color\fR,
-\fBinit_pair\fR,
-\fBinit_color\fR,
-\fBhas_colors\fR,
-\fBcan_change_color\fR,
-\fBcolor_content\fR,
-\fBpair_content\fR,
-\fBCOLOR_PAIR\fR \- \fBcurses\fR color manipulation routines
-.ad
-.hy
+\fB\%start_color\fP,
+\fB\%has_colors\fP,
+\fB\%can_change_color\fP,
+\fB\%init_pair\fP,
+\fB\%init_color\fP,
+\fB\%init_extended_pair\fP,
+\fB\%init_extended_color\fP,
+\fB\%color_content\fP,
+\fB\%pair_content\fP,
+\fB\%extended_color_content\fP,
+\fB\%extended_pair_content\fP,
+\fB\%reset_color_pairs\fP,
+\fB\%COLOR_PAIR\fP,
+\fB\%PAIR_NUMBER\fP,
+\fB\%COLORS\fP,
+\fB\%COLOR_PAIRS\fP,
+\fB\%COLOR_BLACK\fP,
+\fB\%COLOR_RED\fP,
+\fB\%COLOR_GREEN\fP,
+\fB\%COLOR_YELLOW\fP,
+\fB\%COLOR_BLUE\fP,
+\fB\%COLOR_MAGENTA\fP,
+\fB\%COLOR_CYAN\fP,
+\fB\%COLOR_WHITE\fP \-
+manipulate terminal colors with \fIcurses\fR
.SH SYNOPSIS
-\fB# include <curses.h>\fR
-.sp
-\fBint start_color(void);\fR
-.br
-\fBint init_pair(short pair, short f, short b);\fR
-.br
-\fBint init_color(short color, short r, short g, short b);\fR
-.br
-\fBbool has_colors(void);\fR
-.br
-\fBbool can_change_color(void);\fR
-.br
-\fBint color_content(short color, short *r, short *g, short *b);\fR
-.br
-\fBint pair_content(short pair, short *f, short *b);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fI/* variables */
+\fBint COLOR_PAIRS;
+\fBint COLORS;
+.PP
+\fBint start_color(void);
+.PP
+\fBbool has_colors(void);
+\fBbool can_change_color(void);
+.PP
+\fBint init_pair(short \fIpair\fP, short \fIf\fP, short \fIb\fP);
+\fBint init_color(short \fIcolor\fP, short \fIr\fP, short \fIg\fP, short \fIb\fP);
+\fI/* extensions */
+\fBint init_extended_pair(int \fIpair\fP, int \fIf\fP, int \fIb\fP);
+\fBint init_extended_color(int \fIcolor\fP, int \fIr\fP, int \fIg\fP, int \fIb\fP);
+.PP
+\fBint color_content(short \fIcolor\fP, short *\fIr\fP, short *\fIg\fP, short *\fIb\fP);
+\fBint pair_content(short \fIpair\fP, short *\fIf\fP, short *\fIb\fP);
+\fI/* extensions */
+\fBint extended_color_content(int \fIcolor\fP, int *\fIr\fP, int *\fIg\fP, int *\fIb\fP);
+\fBint extended_pair_content(int \fIpair\fP, int *\fIf\fP, int *\fIb\fP);
+.PP
+\fI/* extension */
+\fBvoid reset_color_pairs(void);
+.PP
+\fBint COLOR_PAIR(int \fIn\fP);
+\fBPAIR_NUMBER(int \fIattr\fP);
+.fi
.SH DESCRIPTION
.SS Overview
-\fBcurses\fR supports color attributes on terminals with that capability.
-To use these routines \fBstart_color\fR must be called, usually right after
-\fBinitscr\fR.
-Colors are always used in pairs (referred to as color-pairs).
-A color-pair consists of a foreground color (for characters) and a background
-color (for the blank field on which the characters are displayed).
-A programmer initializes a color-pair with the routine \fBinit_pair\fR.
-After it has been initialized, \fBCOLOR_PAIR\fR(\fIn\fR), a macro defined in
-\fB<curses.h>\fR, can be used as a new video attribute.
+\fIcurses\fP supports color attributes on terminals with that
+capability.
+Call \fB\%start_color\fP
+(typically right after \fB\%initscr\fP(3X))
+to enable this feature.
+Colors are always used in pairs.
+A
+.I "color pair"
+couples a foreground color for characters with a background color for
+the blank field on which characters are rendered.
+\fB\%init_pair\fP initializes a color pair.
+The macro \fB\%COLOR_PAIR\fP(\fIn\fP) can then convert the pair to a
+video attribute.
.PP
-If a terminal is capable of redefining colors, the programmer can use the
-routine \fBinit_color\fR to change the definition of a color.
-The routines \fBhas_colors\fR and \fBcan_change_color\fR
-return \fBTRUE\fR or \fBFALSE\fR,
-depending on whether the terminal has color capabilities and whether the
+If a terminal has the relevant capability,
+\fB\%init_color\fP permits (re)definition of a color.
+\fB\%has_colors\fP and \fB\%can_change_color\fP
+return \fBTRUE\fP or \fBFALSE\fP,
+depending on whether the terminal has color capability and whether the
programmer can change the colors.
-The routine \fBcolor_content\fR allows a
-programmer to extract the amounts of red, green, and blue components in an
-initialized color.
-The routine \fBpair_content\fR allows a programmer to find
-out how a given color-pair is currently defined.
-.SS Color Rendering
-The \fBcurses\fP library combines these inputs to produce the
-actual foreground and background colors shown on the screen:
+\fB\%color_content\fP permits extraction of the
+red,
+green,
+and blue components of an initialized color.
+\fB\%pair_content\fP permits discovery of a color pair's current
+definition.
+.SS Rendering
+.I curses
+combines the following data to render a character cell.
+Any of them can include color information.
.bP
-per-character video attributes (e.g., via \fBwaddch\fP),
+.I curses
+character attributes,
+as from \fB\%waddch\fP(3X) or \fB\%wadd_wch\fP(3X)
.bP
-the window attribute (e.g., by \fBwattrset\fP), and
+window attributes,
+as from \fB\%wattrset\fP(3X) or \fB\%wattr_set\fP(3X)
.bP
-the background character (e.g., \fBwbkgdset\fP).
+window background character attributes,
+as from \fB\%wbkgdset\fP(3X) or \fB\%wbkgrndset\fP(3X)
.PP
-Per-character and window attributes are usually set by a parameter containing
-video attributes including a \fBCOLOR_PAIR\fP value.
-Some functions such as \fBwattr_set\fP use a separate parameter which
-is the color pair number.
+Per-character and window attributes are usually set through a function
+parameter containing attributes including a color pair value.
+Some functions,
+such as \fB\%wattr_set\fP,
+use a separate color pair number parameter.
.PP
-The background character is a special case: it includes a character value,
-just as if it were passed to \fBwaddch\fP.
+The background character is a special case:
+it includes a character code,
+just as if it were passed to \fB\%waddch\fP.
.PP
-The \fBcurses\fP library does the actual work of combining these color
-pairs in an internal function called from \fBwaddch\fP:
+The \fIcurses\fP library does the actual work of combining these color
+pairs in an internal function called from \fB\%waddch\fP:
.bP
-If the parameter passed to \fBwaddch\fP is \fIblank\fP,
+If the parameter passed to \fB\%waddch\fP is \fIblank\fP,
and it uses the special color pair 0,
.RS
.bP
-\fBcurses\fP next checks the window attribute.
+\fIcurses\fP next checks the window attribute.
.bP
If the window attribute does not use color pair 0,
-\fBcurses\fP uses the color pair from the window attribute.
+\fIcurses\fP uses the color pair from the window attribute.
.bP
-Otherwise, \fBcurses\fP uses the background character.
+Otherwise, \fIcurses\fP uses the background character.
.RE
.bP
-If the parameter passed to \fBwaddch\fP is \fInot blank\fP,
+If the parameter passed to \fB\%waddch\fP is \fInot blank\fP,
or it does not use the special color pair 0,
-\fBcurses\fP prefers the color pair from the parameter,
+\fIcurses\fP prefers the color pair from the parameter,
if it is nonzero.
Otherwise, it tries the window attribute next, and finally the
background character.
.PP
-Some \fBcurses\fP functions such as \fBwprintw\fP call \fBwaddch\fP.
+Some \fIcurses\fP functions such as \fB\%wprintw\fP call \fB\%waddch\fP.
Those do not combine its parameter with a color pair.
Consequently those calls use only the window attribute or
the background character.
-.SS Routine Descriptions
-The \fBstart_color\fR routine requires no arguments.
+.SH CONSTANTS
+In \fB\%<curses.h>\fP the following macros are defined.
+These are the standard colors (ISO-6429).
+\fIcurses\fP also assumes that \fB\%COLOR_BLACK\fP is the default
+background color for all terminals.
+.PP
+.nf
+ \fBCOLOR_BLACK\fP
+ \fBCOLOR_RED\fP
+ \fBCOLOR_GREEN\fP
+ \fBCOLOR_YELLOW\fP
+ \fBCOLOR_BLUE\fP
+ \fBCOLOR_MAGENTA\fP
+ \fBCOLOR_CYAN\fP
+ \fBCOLOR_WHITE\fP
+.fi
+.PP
+Some terminals support more than the eight (8) \*(``ANSI\*('' colors.
+There are no standard names for those additional colors.
+.SH VARIABLES
+.SS COLORS
+is initialized by \fB\%start_color\fP to the maximum number of colors
+the terminal can support.
+.SS COLOR_PAIRS
+is initialized by \fB\%start_color\fP to the maximum number of color
+pairs the terminal can support.
+Often,
+its value is the product \fB\%COLORS\fP \(mu \fB\%COLORS\fP,
+but this is not always true.
+.bP
+A few terminals use the HLS color space
+(see \fB\%start_color\fP below),
+ignoring this rule;
+and
+.bP
+terminals supporting a large number of colors are limited to the number
+of color pairs that a
+.I "signed short"
+value can represent.
+.SH FUNCTIONS
+.SS start_color
+The \fB\%start_color\fP routine requires no arguments.
It must be called if the programmer wants to use colors, and before any other
color manipulation routine is called.
-It is good practice to call this routine right after \fBinitscr\fR.
-\fBstart_color\fR does this:
+It is good practice to call this routine right after \fB\%initscr\fP.
+\fB\%start_color\fP does this:
.bP
-It initializes two global variables, \fBCOLORS\fR and
-\fBCOLOR_PAIRS\fR (respectively defining the maximum number of colors
-and color-pairs the terminal can support).
+It initializes two global variables, \fB\%COLORS\fP and
+\fB\%COLOR_PAIRS\fP (respectively defining the maximum number of colors
+and color pairs the terminal can support).
.bP
-It initializes the special color pair \fB0\fP to the default foreground
+It initializes the special color pair \fB\%0\fP to the default foreground
and background colors.
No other color pairs are initialized.
.bP
It restores the colors on the terminal to the values
they had when the terminal was just turned on.
.bP
-If the terminal supports the \fBinitc\fP (\fBinitialize_color\fP) capability,
-\fBstart_color\fP
+If the terminal supports the \fBinitc\fP \%(\fBinitialize_color\fP) capability,
+\fB\%start_color\fP
initializes its internal table representing the
-red, green and blue components of the color palette.
+red, green, and blue components of the color palette.
.IP
The components depend on whether the terminal uses
-CGA (aka "ANSI") or
-HLS (i.e., the \fBhls\fP (\fBhue_lightness_saturation\fP) capability is set).
+CGA (aka \*(``ANSI\*('') or
+HLS (i.e., the \fBhls\fP \%(\fBhue_lightness_saturation\fP) capability is set).
The table is initialized first for eight basic colors
(black, red, green, yellow, blue, magenta, cyan, and white),
-and after that (if the terminal supports more than eight colors)
-the components are initialized to \fB1000\fP.
+using weights that depend upon the CGA/HLS choice.
+For \*(``ANSI\*('' colors the weights are \fB680\fP or \fB0\fP
+depending on whether the corresponding
+red, green, or blue component is used or not.
+That permits using \fB1000\fP to represent bold/bright colors.
+After the initial eight colors
+(if the terminal supports more than eight colors)
+the components are initialized using the same pattern,
+but with weights of \fB1000\fP.
+SVr4 uses a similar scheme, but uses \fB1000\fP
+for the components of the initial eight colors.
.IP
-\fBstart_color\fP does not attempt to set the terminal's color palette
+\fB\%start_color\fP does not attempt to set the terminal's color palette
to match its built-in table.
-An application may use \fBinit_color\fP to alter the internal table
+An application may use \fB\%init_color\fP to alter the internal table
along with the terminal's color.
.PP
These limits apply to color values and color pairs.
-Values outside these limits are not legal, and may result in a runtime error:
+Values outside these limits are not valid, and may result in a runtime error:
.bP
-\fBCOLORS\fP corresponds to the terminal database's \fBmax_colors\fP capability,
-which is typically a signed 16-bit integer (see \fBterminfo\fR(\*n)).
+\fBCOLORS\fP corresponds to the terminal database's \fB\%max_colors\fP capability,
+(see \fB\%terminfo\fP(5)).
.bP
-color values are expected to be in the range \fB0\fP to \fBCOLORS\-1\fP,
-inclusive (including \fB0\fP and \fBCOLORS\-1\fP).
+color values are expected to be in the range \fB0\fP to \fB\%COLORS\-1\fP,
+inclusive (including \fB0\fP and \fB\%COLORS\-1\fP).
.bP
a special color value \fB\-1\fP is used in certain extended functions
-to denote the \fIdefault color\fP (see \fBuse_default_colors\fP).
+to denote the \fIdefault color\fP (see \fB\%use_default_colors\fP(3X)).
.bP
-\fBCOLOR_PAIRS\fP corresponds to the terminal database's \fBmax_pairs\fP capability,
-which is typically a signed 16-bit integer (see \fBterminfo\fR(\*n)).
+\fB\%COLOR_PAIRS\fP corresponds to
+the terminal database's \fB\%max_pairs\fP capability,
+(see \fB\%terminfo\fP(5)).
.bP
-legal color pair values are in the range \fB1\fP to \fBCOLOR_PAIRS\-1\fP,
+valid color pair values are in the range \fB1\fP to \fB\%COLOR_PAIRS\-1\fP,
inclusive.
.bP
color pair \fB0\fP is special; it denotes \*(``no color\*(''.
@@ -192,164 +290,300 @@
Color pair \fB0\fP is assumed to be white on black,
but is actually whatever the terminal implements before color is initialized.
It cannot be modified by the application.
-.PP
-The \fBinit_pair\fR routine changes the definition of a color-pair.
-It takes three arguments: the number of the color-pair to be changed, the foreground
-color number, and the background color number.
-For portable applications:
-.bP
-The first argument must be a legal color pair value.
-If default colors are used (see \fBuse_default_colors\fP)
-the upper limit is adjusted to allow for extra pairs which use
-a default color in foreground and/or background.
-.bP
-The second and third arguments must be legal color values.
-.PP
-If the color-pair was previously initialized,
-the screen is refreshed and all occurrences of that color-pair
-are changed to the new definition.
-.PP
-As an extension, ncurses allows you to set color pair \fB0\fP via
-the \fBassume_default_colors\fR routine, or to specify the use of
-default colors (color number \fB\-1\fR) if you first invoke the
-\fBuse_default_colors\fR routine.
-.PP
-The \fBinit_color\fR routine changes the definition of a color.
-It takes four arguments: the number of the color to be changed followed by three RGB values
-(for the amounts of red, green, and blue components).
-The first argument must be a legal color value;
-default colors are not allowed here.
-(See the section \fBColors\fR for the default color index.)
-Each of the last three arguments
-must be a value in the range \fB0\fP through \fB1000\fP.
-When \fBinit_color\fR is used, all
-occurrences of that color on the screen immediately change to the new
-definition.
-.PP
-The \fBhas_colors\fR routine requires no arguments.
-It returns \fBTRUE\fR if
-the terminal can manipulate colors; otherwise, it returns \fBFALSE\fR.
+.SS has_colors
+The \fB\%has_colors\fP routine requires no arguments.
+It returns \fBTRUE\fP if
+the terminal can manipulate colors; otherwise, it returns \fBFALSE\fP.
This routine facilitates writing terminal-independent programs.
For example, a programmer can use it to decide
whether to use color or some other video attribute.
-.PP
-The \fBcan_change_color\fR routine requires no arguments.
-It returns \fBTRUE\fR if the terminal supports colors
+.SS can_change_color
+The \fB\%can_change_color\fP routine requires no arguments.
+It returns \fBTRUE\fP if the terminal supports colors
and can change their definitions;
-other, it returns \fBFALSE\fR.
+other, it returns \fBFALSE\fP.
This routine facilitates writing terminal-independent programs.
+.SS init_pair
+The \fB\%init_pair\fP routine changes the definition of a color pair.
+It takes three arguments:
+the number of the color pair to be changed, the foreground
+color number, and the background color number.
+For portable applications:
+.bP
+The first argument must be a valid color pair value.
+If default colors are used (see \fB\%use_default_colors\fP(3X))
+the upper limit is adjusted to allow for extra pairs which use
+a default color in foreground and/or background.
+.bP
+The second and third arguments must be valid color values.
.PP
-The \fBcolor_content\fR routine gives programmers a way to find the intensity
+If the color pair was previously initialized,
+the screen is refreshed and all occurrences of that color pair
+are changed to the new definition.
+.PP
+As an extension,
+\fI\%ncurses\fP allows you to set color pair \fB0\fP via the
+\fB\%assume_default_colors\fP(3X) routine, or to specify the use of
+default colors (color number \fB\-1\fP) if you first invoke the
+\fB\%use_default_colors\fP(3X) routine.
+.SS init_extended_pair
+Because \fB\%init_pair\fP uses signed \fBshort\fPs for its parameters,
+that limits color pairs and color-values
+to 32767 on modern hardware.
+The extension \fB\%init_extended_pair\fP uses \fBint\fPs
+for the color pair and color-value,
+allowing a larger number of colors to be supported.
+.SS init_color
+The \fB\%init_color\fP routine changes the definition of a color.
+It takes four arguments:
+the number of the color to be changed followed by three RGB values
+(for the amounts of red, green, and blue components).
+.bP
+The first argument must be a valid color value;
+default colors are not allowed here.
+(See the section \fB\%Colors\fP for the default color index.)
+.bP
+Each of the last three arguments
+must be a value in the range \fB0\fP through \fB1000\fP.
+.PP
+When \fB\%init_color\fP is used, all
+occurrences of that color on the screen immediately change to the new
+definition.
+.SS init_extended_color
+Because \fB\%init_color\fP uses signed \fBshort\fPs for its parameters,
+that limits color-values and their red, green, and blue components
+to 32767 on modern hardware.
+The extension \fB\%init_extended_color\fP uses \fBint\fPs
+for the color value and
+for setting the red, green, and blue components,
+allowing a larger number of colors to be supported.
+.SS color_content
+The \fB\%color_content\fP routine gives programmers a way to find the intensity
of the red, green, and blue (RGB) components in a color.
It requires four arguments: the color number, and three addresses
of \fBshort\fRs for storing
the information about the amounts of red, green, and blue components in the
given color.
-The first argument must be a legal color value, i.e.,
-\fB0\fP through \fBCOLORS\-1\fP, inclusive.
+.bP
+The first argument must be a valid color value, i.e.,
+\fB0\fP through \fB\%COLORS\-1\fP, inclusive.
+.bP
The values that are stored at the addresses pointed to by the
last three arguments are in the range
-\fB0\fP (no component) through \fB1000\fP (maximum amount of component), inclusive.
-.PP
-The \fBpair_content\fR routine allows programmers to find out what colors a
-given color-pair consists of.
-It requires three arguments: the color-pair
+\fB0\fP (no component) through \fB1000\fP
+(maximum amount of component), inclusive.
+.SS extended_color_content
+Because \fB\%color_content\fP uses signed \fBshort\fPs for its parameters,
+that limits color-values and their red, green, and blue components
+to 32767 on modern hardware.
+The extension \fB\%extended_color_content\fP uses \fBint\fPs
+for the color value and
+for returning the red, green, and blue components,
+allowing a larger number of colors to be supported.
+.SS pair_content
+The \fB\%pair_content\fP routine allows programmers to find out what colors a
+given color pair consists of.
+It requires three arguments: the color pair
number, and two addresses of \fBshort\fRs for storing the foreground and the
background color numbers.
-The first argument must be a legal color value,
-i.e., in the range \fB1\fP through \fBCOLOR_PAIRS\-1\fR, inclusive.
+.bP
+The first argument must be a valid color value,
+i.e., in the range \fB1\fP through \fB\%COLOR_PAIRS\-1\fP, inclusive.
+.bP
The values that are stored at the addresses pointed
to by the second and third arguments are in the
-range \fB0\fP through \fBCOLORS\fR, inclusive.
-.SS Colors
-In \fB<curses.h>\fR the following macros are defined.
-These are the standard colors (ISO-6429).
-\fBcurses\fR also assumes that \fBCOLOR_BLACK\fR is the default
-background color for all terminals.
-.PP
-.nf
- \fBCOLOR_BLACK\fR
- \fBCOLOR_RED\fR
- \fBCOLOR_GREEN\fR
- \fBCOLOR_YELLOW\fR
- \fBCOLOR_BLUE\fR
- \fBCOLOR_MAGENTA\fR
- \fBCOLOR_CYAN\fR
- \fBCOLOR_WHITE\fR
-.fi
+range \fB0\fP through \fB\%COLORS\fP, inclusive.
+.SS extended_pair_content
+Because \fB\%pair_content\fP uses signed \fBshort\fPs for its parameters,
+that limits color pair and color-values to 32767 on modern hardware.
+The extension \fB\%extended_pair_content\fP uses \fBint\fPs
+for the color pair and
+for returning the foreground and background colors,
+allowing a larger number of colors to be supported.
+.SS reset_color_pairs
+The extension \fB\%reset_color_pairs\fP tells \fI\%ncurses\fP to discard
+all of the color pair information which was set with \fB\%init_pair\fP.
+It also touches the current- and standard-screens, allowing an application to
+switch color palettes rapidly.
+.SS COLOR_PAIR
+\fB\%COLOR_PAIR(\fIn\fB)\fR converts a color pair number to an
+attribute.
+Attributes can hold color pairs in the range 0 to 255.
+If you need a color pair larger than that,
+you must use functions such as \fB\%attr_set\fP
+(which pass the color pair as a separate parameter)
+rather than the legacy functions such as \fB\%attrset\fP.
+.SS PAIR_NUMBER
+\fB\%PAIR_NUMBER(\fIattr\fR) extracts the color information from its
+\fIattr\fP parameter and returns it as a color pair number;
+it is the inverse operation of \fB\%COLOR_PAIR\fP.
.SH RETURN VALUE
-The routines \fBcan_change_color()\fR and \fBhas_colors()\fR return \fBTRUE\fR
-or \fBFALSE\fR.
+The routines \fB\%can_change_color\fP and \fB\%has_colors\fP return \fBTRUE\fP
+or \fBFALSE\fP.
.PP
-All other routines return the integer \fBERR\fR upon failure and an \fBOK\fR
-(SVr4 specifies only "an integer value other than \fBERR\fR") upon successful
-completion.
+All other routines return the integer \fBERR\fP upon failure and an \fBOK\fP
+(SVr4 specifies only \*(``an integer value
+other than \fBERR\fP\*('') upon successful completion.
.PP
X/Open defines no error conditions.
-This implementation will return \fBERR\fR on attempts to
-use color values outside the range \fB0\fP to COLORS\-1
+SVr4 does document some error conditions which apply in general:
+.bP
+This implementation will return \fBERR\fP on attempts to
+use color values outside the range \fB0\fP to \fB\%COLORS\fP\-1
(except for the default colors extension),
-or use color pairs outside the range \fB0\fP to \fBCOLOR_PAIRS\-1\fP.
-Color values used in \fBinit_color\fP must be in the range \fB0\fP to \fB1000\fP.
+or use color pairs outside the range \fB0\fP to \fB\%COLOR_PAIRS\-1\fP.
+.IP
+Color values used in \fB\%init_color\fP must be
+in the range \fB0\fP to \fB1000\fP.
+.IP
An error is returned from all functions
if the terminal has not been initialized.
-An error is returned from secondary functions such as \fBinit_pair\fP
-if \fBstart_color\fP was not called.
+.IP
+An error is returned from secondary functions such as \fB\%init_pair\fP
+if \fB\%start_color\fP was not called.
+.bP
+SVr4 does much the same, except that
+it returns \fBERR\fP from \fB\%pair_content\fP if the pair was not initialized
+using \fB\%init_pairs\fP
+and
+it returns \fBERR\fP from \fB\%color_content\fP
+if the terminal does not support changing colors.
+.IP
+This implementation does not return \fBERR\fP for either case.
+.PP
+Specific functions make additional checks:
.RS 3
.TP 5
-\fBinit_color\fP
+\fB\%init_color\fP
returns an error if the terminal does not support
-this feature, e.g., if the \fIinitialize_color\fP capability is absent
+this feature, e.g., if the \fB\%initialize_color\fP capability is absent
from the terminal description.
.TP 5
-\fBstart_color\fP
+\fB\%start_color\fP
returns an error if the color table cannot be allocated.
.RE
.SH NOTES
-In the \fIncurses\fR implementation, there is a separate color activation flag,
-color palette, color pairs table, and associated COLORS and COLOR_PAIRS counts
-for each screen; the \fBstart_color\fR function only affects the current
+In the \fI\%ncurses\fP implementation,
+there is a separate color activation flag,
+color palette, color pairs table,
+and associated \fB\%COLORS\fP and \fB\%COLOR_PAIRS\fP counts
+for each screen; the \fB\%start_color\fP function only affects the current
screen.
The SVr4/XSI interface is not really designed with this in mind, and
historical implementations may use a single shared color palette.
.PP
-Note that setting an implicit background color via a color pair affects only
+Setting an implicit background color via a color pair affects only
character cells that a character write operation explicitly touches.
To change
the background color used when parts of a window are blanked by erasing or
-scrolling operations, see \fBcurs_bkgd\fR(3X).
+scrolling operations, see \fB\%curs_bkgd\fP(3X).
.PP
-Several caveats apply on 386 and 486 machines with VGA-compatible graphics:
+Several caveats apply on older x86 machines
+(e.g., i386, i486) with VGA-compatible graphics:
.bP
COLOR_YELLOW is actually brown.
-To get yellow, use COLOR_YELLOW combined with the \fBA_BOLD\fR attribute.
+To get yellow, use COLOR_YELLOW combined with the \fBA_BOLD\fP attribute.
.bP
The A_BLINK attribute should in theory cause the background to go bright.
This often fails to work, and even some cards for which it mostly works
(such as the
Paradise and compatibles) do the wrong thing when you try to set a bright
-"yellow" background (you get a blinking yellow foreground instead).
+\*(``yellow\*('' background (you get a blinking yellow foreground instead).
.bP
Color RGB values are not settable.
+.SH EXTENSIONS
+The functions marked as extensions were designed for
+\fB\%ncurses\fP(3X),
+and are not found in SVr4
+.IR curses ,
+4.4BSD
+.IR curses ,
+or any other previous curses implementation.
.SH PORTABILITY
-This implementation satisfies XSI Curses's minimum maximums
-for \fBCOLORS\fR and \fBCOLOR_PAIRS\fR.
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
.PP
-The \fBinit_pair\fP routine accepts negative values of foreground
-and background color to support the \fBuse_default_colors\fP extension,
+This implementation satisfies X/Open Curses's minimum maximums
+for \fB\%COLORS\fP and \fB\%COLOR_PAIRS\fP.
+.PP
+The \fB\%init_pair\fP routine accepts negative values of foreground
+and background color to support the \fB\%use_default_colors\fP(3X) extension,
but only if that routine has been first invoked.
.PP
-The assumption that \fBCOLOR_BLACK\fR is the default
+The assumption that \fB\%COLOR_BLACK\fP is the default
background color for all terminals can be modified using the
-\fBassume_default_colors\fP extension.
+\fB\%assume_default_colors\fP(3X) extension.
.PP
This implementation checks the pointers,
e.g., for the values returned by
-\fBcolor_content\fP and \fBpair_content\fP,
+\fB\%color_content\fP and \fB\%pair_content\fP,
and will treat those as optional parameters when null.
+.PP
+X/Open Curses does not specify a limit for the number of colors and
+color pairs which a terminal can support.
+However, in its use of \fBshort\fP for the parameters,
+it carries over SVr4's implementation detail for the compiled
+terminfo database, which uses signed 16-bit numbers.
+This implementation provides extended versions of those functions
+which use \fBshort\fP parameters,
+allowing applications to use larger color- and pair-numbers.
+.PP
+The \fB\%reset_color_pairs\fP function is an extension of
+\fI\%ncurses\fP.
+.SH HISTORY
+SVr3.2 introduced color support to curses in 1987.
+.PP
+SVr4 made internal changes,
+e.g., moving the storage for the color state
+from \fBSP\fP (the \fISCREEN\fP structure)
+to \fB\%cur_term\fP (the \fI\%TERMINAL\fP structure),
+but provided the same set of library functions.
+.PP
+SVr4 curses limits the number of color pairs to 64,
+reserving color pair zero (0) as the terminal's initial uncolored state.
+This limit arises because the color pair information is a bitfield
+in the \fB\%chtype\fP data type (denoted by \fB\%A_COLOR\fP).
+.PP
+Other implementations of curses had different limits:
+.bP
+PCCurses (1987-1990) provided for only eight (8) colors.
+.bP
+PDCurses (1992-present) inherited the 8-color limitation from PCCurses,
+but changed this to 256 in version 2.5 (2001),
+along with changing \fB\%chtype\fP from 16-bits to 32-bits.
+.bP
+X/Open Curses (1992-present)
+added a new structure \fB\%cchar_t\fP to store the character,
+attributes and color pair values, allowing increased range of color pairs.
+Both color pairs and color-values used a signed \fBshort\fP,
+limiting values to 15 bits.
+.bP
+\fI\%ncurses\fP (1992-present) uses eight bits
+for \fB\%A_COLOR\fP in \fB\%chtype\fP values.
+.IP
+Version 5.3 provided a wide-character interface (2002),
+but left color pairs as part of the attributes-field.
+.IP
+Since version 6 (2015),
+ncurses uses a separate \fBint\fP for color pairs in the \fB\%cchar_t\fP values.
+When those color pair values fit in 8 bits,
+ncurses allows color pairs to be manipulated
+via the functions using \fB\%chtype\fP values.
+.bP
+NetBSD curses used 6 bits from
+2000 (when colors were first supported) until 2004.
+At that point, NetBSD changed to use 10 bits.
+As of 2021, that size is unchanged.
+Like \fI\%ncurses\fP before version 6,
+the NetBSD color pair information is stored in
+the attributes field of \fB\%cchar_t\fP, limiting the number of color pairs
+by the size of the bitfield.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_initscr\fR(3X),
-\fBcurs_attr\fR(3X),
-\fBcurs_variables\fR(3X),
-\fBdefault_colors\fR(3X)
+\fB\%curses\fP(3X),
+\fB\%curs_attr\fP(3X),
+\fB\%curs_initscr\fP(3X),
+\fB\%curs_variables\fP(3X),
+\fB\%default_colors\fP(3X)
diff --git a/man/curs_delch.3x b/man/curs_delch.3x
index 6dfc0a0..e62ecc1 100644
--- a/man/curs_delch.3x
+++ b/man/curs_delch.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2006,2010 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 *
@@ -26,43 +27,87 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_delch.3x,v 1.11 2010/12/04 18:36:44 tom Exp $
-.TH curs_delch 3X ""
+.\" $Id: curs_delch.3x,v 1.34 2024/04/20 19:24:14 tom Exp $
+.TH curs_delch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-\fBdelch\fR,
-\fBwdelch\fR,
-\fBmvdelch\fR,
-\fBmvwdelch\fR \- delete character under the cursor in a \fBcurses\fR window
+\fB\%delch\fP,
+\fB\%wdelch\fP,
+\fB\%mvdelch\fP,
+\fB\%mvwdelch\fP \-
+delete a character from a \fIcurses\fR window
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint delch(void);\fR
-.br
-\fBint wdelch(WINDOW *win);\fR
-.br
-\fBint mvdelch(int y, int x);\fR
-.br
-\fBint mvwdelch(WINDOW *win, int y, int x);\fR
-.br
-.SH DESCRIPTION
-These routines delete the character under the cursor; all characters to the
-right of the cursor on the same line are moved to the left one position and the
-last character on the line is filled with a blank. The cursor position does
-not change (after moving to \fIy\fR, \fIx\fR, if specified). (This does not
-imply use of the hardware delete character feature.)
-.SH RETURN VALUE
-All routines return the integer \fBERR\fR upon failure and an \fBOK\fR (SVr4
-specifies only "an integer value other than \fBERR\fR") upon successful
-completion.
+.nf
+\fB#include <curses.h>
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+\fBint delch(void);
+\fBint wdelch(WINDOW *\fIwin\fP);
+\fBint mvdelch(int \fIy\fP, int \fIx\fP);
+\fBint mvwdelch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
+.fi
+.SH DESCRIPTION
+.B \%wdelch
+deletes the character at the cursor position in
+.IR win .
+\fB\%ncurses\fP(3X) describes the variants of this function.
+.PP
+.B \%wdelch
+moves all characters to the right of the cursor on the same line to the
+left one position and replaces the contents of the rightmost position on
+the line with the window's blank character;
+see \fB\%bkgd\fP(3X)
+(wide-character API users may consult \fB\%bkgrnd\fP(3X) instead).
+The cursor position does not change
+(after moving to
+.RI ( y ,
+.IR x ),
+if specified).
+.SH RETURN VALUE
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
+.PP
+Functions taking a
+.I \%WINDOW
+pointer argument fail if the pointer is
+.BR NULL .
+.PP
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
-Note that \fBdelch\fR, \fBmvdelch\fR, and \fBmvwdelch\fR may be macros.
+.BR \%delch ,
+.BR \%mvdelch ,
+and
+.B \%mvwdelch
+may be implemented as macros.
+.PP
+A terminal's
+.B \%delete_character
+.RB ( dch1 )
+capability
+is not necessarily employed.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4. The
-standard specifies that they return \fBERR\fR on failure, but specifies no
-error conditions.
+X/Open Curses,
+Issue 4 describes these functions.
+.PP
+SVr4
+.I curses
+describes a successful return value only as
+\*(``an integer value other than
+.BR ERR \*(''.
.SH SEE ALSO
-\fBcurses\fR(3X)
+\fB\%curses\fP(3X)
diff --git a/man/curs_deleteln.3x b/man/curs_deleteln.3x
index 83cbdec..6d70a43 100644
--- a/man/curs_deleteln.3x
+++ b/man/curs_deleteln.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2007,2010 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 *
@@ -26,60 +27,78 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_deleteln.3x,v 1.13 2010/12/04 18:36:44 tom Exp $
-.TH curs_deleteln 3X ""
+.\" $Id: curs_deleteln.3x,v 1.38 2024/04/20 21:20:07 tom Exp $
+.TH curs_deleteln 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.SH NAME
-\fBdeleteln\fR,
-\fBwdeleteln\fR,
-\fBinsdelln\fR,
-\fBwinsdelln\fR,
-\fBinsertln\fR,
-\fBwinsertln\fR \- delete and insert lines in a \fBcurses\fR window
+\fB\%deleteln\fP,
+\fB\%wdeleteln\fP,
+\fB\%insdelln\fP,
+\fB\%winsdelln\fP,
+\fB\%insertln\fP,
+\fB\%winsertln\fP \-
+delete or insert lines in a \fIcurses\fR window
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint deleteln(void);\fR
-.br
-\fBint wdeleteln(WINDOW *win);\fR
-.br
-\fBint insdelln(int n);\fR
-.br
-\fBint winsdelln(WINDOW *win, int n);\fR
-.br
-\fBint insertln(void);\fR
-.br
-\fBint winsertln(WINDOW *win);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint deleteln(void);
+\fBint wdeleteln(WINDOW *\fIwin\fP);
+.PP
+\fBint insdelln(int \fIn\fP);
+\fBint winsdelln(WINDOW *\fIwin\fP, int \fIn\fP);
+.PP
+\fBint insertln(void);
+\fBint winsertln(WINDOW *\fIwin\fP);
+.fi
.SH DESCRIPTION
-The \fBdeleteln\fR and \fBwdeleteln\fR routines delete the line under the
+The \fBdeleteln\fP and \fBwdeleteln\fP routines delete the line under the
cursor in the window; all lines below the current line are moved up one line.
-The bottom line of the window is cleared. The cursor position does not change.
+The bottom line of the window is cleared.
+The cursor position does not change.
.PP
-The \fBinsdelln\fR and \fBwinsdelln\fR routines, for positive \fIn\fR, insert
-\fIn\fR lines into the specified window above the current line. The \fIn\fR
-bottom lines are lost. For negative \fIn\fR, delete \fIn\fR lines (starting
-with the one under the cursor), and move the remaining lines up. The bottom
-\fIn\fR lines are cleared. The current cursor position remains the same.
+The \fBinsdelln\fP and \fBwinsdelln\fP routines, for positive \fIn\fP, insert
+\fIn\fP lines into the specified window above the current line.
+The \fIn\fP
+bottom lines are lost.
+For negative \fIn\fP, delete \fIn\fP lines (starting
+with the one under the cursor), and move the remaining lines up.
+The bottom
+\fIn\fP lines are cleared.
+The current cursor position remains the same.
.PP
-The \fBinsertln\fR and \fBwinsertln\fR routines insert a blank line above the
+The \fBinsertln\fP and \fBwinsertln\fP routines insert a blank line above the
current line and the bottom line is lost.
.SH RETURN VALUE
-All routines return the integer \fBERR\fR upon failure and an \fBOK\fR (SVr4
-specifies only "an integer value other than \fBERR\fR") upon successful
-completion.
+These routines return the integer \fBERR\fP upon failure and an \fBOK\fP
+(SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('')
+upon successful completion.
.PP
X/Open defines no error conditions.
In this implementation,
if the window parameter is null, an error is returned.
-.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4. The
-standard specifies that they return \fBERR\fR on failure, but specifies no
-error conditions.
.SH NOTES
-Note that all but \fBwinsdelln\fR may be macros.
+Note that all but \fBwinsdelln\fP may be macros.
.PP
These routines do not require a hardware line delete or insert feature in the
-terminal. In fact, they will not use hardware line delete/insert unless
-\fBidlok(..., TRUE)\fR has been set on the current window.
+terminal.
+In fact, they will not use hardware line delete/insert unless
+\fBidlok(..., TRUE)\fP has been set on the current window.
+.SH PORTABILITY
+These functions are described in X/Open Curses, Issue 4.
+The
+standard specifies that they return \fBERR\fP on failure, but specifies no
+error conditions.
.SH SEE ALSO
-\fBcurses\fR(3X)
+\fB\%curses\fP(3X)
diff --git a/man/curs_extend.3x b/man/curs_extend.3x
index 9a52f93..01cf9d2 100644
--- a/man/curs_extend.3x
+++ b/man/curs_extend.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1999-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1999-2010,2016 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 *
@@ -28,29 +29,42 @@
.\"
.\" Author: Thomas E. Dickey 1999-on
.\"
-.\" $Id: curs_extend.3x,v 1.19 2010/12/04 18:36:44 tom Exp $
-.TH curs_extend 3X ""
+.\" $Id: curs_extend.3x,v 1.46 2024/03/16 15:35:01 tom Exp $
+.TH curs_extend 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-\fBcurses_version\fP,
-\fBuse_extended_names\fP \- miscellaneous curses extensions
-.
+\fB\%curses_version\fP,
+\fB\%use_extended_names\fP \-
+miscellaneous \fIcurses\fR extensions
.SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-\fBconst char * curses_version(void);\fP
-.br
-\fBint use_extended_names(bool enable);\fP
+.nf
+\fB#include <curses.h>
+.PP
+\fBconst char * curses_version(void);
+\fBint use_extended_names(bool \fIenable\fP);
+.fi
.SH DESCRIPTION
These functions are extensions to the curses library
which do not fit easily into other categories.
-.PP
-Use
-.I curses_version()
-to get the version number, including patch level of the library, e.g.,
-.B 5.0.19991023
-.PP
-The
-.I use_extended_names()
+.SS curses_version
+Use \fBcurses_version\fP
+to get the version number, including patch level of the library,
+prefixed by \*(``ncurses\*('', e.g.,
+.RS
+.sp
+.B ncurses 5.0.19991023
+.RE
+.SS use_extended_names
+The \fBuse_extended_names\fP
function controls whether the calling application
is able to use user-defined or nonstandard names
which may be compiled into the terminfo
@@ -60,20 +74,35 @@
extended terminal definitions.
However you can disable this feature
to ensure compatibility with other implementations of curses.
+.SH RETURN VALUE
+\fBcurses_version\fP returns a pointer to static memory; you should not free
+this in your application.
+.PP
+\fBuse_extended_names\fP returns the previous state, allowing you to
+save this and restore it.
+.SH EXTENSIONS
+These functions are \fB\%ncurses\fP(3X) extensions,
+and are not found in SVr4
+.IR curses ,
+4.4BSD
+.IR curses ,
+or any other previous curses implementation.
.SH PORTABILITY
-These routines are specific to ncurses. They were not supported on
-Version 7, BSD or System V implementations. It is recommended that
-any code depending on them be conditioned using NCURSES_VERSION.
-.SH SEE ALSO
-\fBcurs_getch\fR(3X),
-\fBcurs_mouse\fR(3X),
-\fBcurs_print\fR(3X),
-\fBcurs_util\fR(3X),
-\fBdefault_colors\fR(3X),
-\fBdefine_key\fR(3X),
-\fBkeybound\fR(3X),
-\fBkeyok\fR(3X),
-\fBresizeterm\fR(3X),
-\fBwresize\fR(3X).
-.SH AUTHOR
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
+.SH AUTHORS
Thomas Dickey.
+.SH SEE ALSO
+\fB\%curs_getch\fP(3X),
+\fB\%curs_mouse\fP(3X),
+\fB\%curs_print\fP(3X),
+\fB\%curs_util\fP(3X),
+\fB\%default_colors\fP(3X),
+\fB\%define_key\fP(3X),
+\fB\%keybound\fP(3X),
+\fB\%keyok\fP(3X),
+\fB\%resizeterm\fP(3X),
+\fB\%wresize\fP(3X)
diff --git a/man/curs_get_wch.3x b/man/curs_get_wch.3x
index df9bc6a..02932b9 100644
--- a/man/curs_get_wch.3x
+++ b/man/curs_get_wch.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 2002-2016,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 *
@@ -26,140 +27,233 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_get_wch.3x,v 1.8 2012/11/03 23:03:59 tom Exp $
-.TH curs_get_wch 3X ""
+.\" $Id: curs_get_wch.3x,v 1.40 2024/04/20 19:23:03 tom Exp $
+.TH curs_get_wch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBget_wch\fR,
-\fBwget_wch\fR,
-\fBmvget_wch\fR,
-\fBmvwget_wch\fR,
-\fBunget_wch\fR \- get (or push back) a wide character from curses terminal keyboard
+\fB\%get_wch\fP,
+\fB\%wget_wch\fP,
+\fB\%mvget_wch\fP,
+\fB\%mvwget_wch\fP,
+\fB\%unget_wch\fP \-
+get (or push back) a wide character from \fIcurses\fR terminal keyboard
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint get_wch(wint_t *\fR\fIwch\fR\fB);\fR
-.br
-\fBint wget_wch(WINDOW *\fR\fIwin\fR\fB, wint_t *\fR\fIwch\fR\fB);\fR
-.br
-\fBint mvget_wch(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwch\fR\fB);\fR
-.br
-\fBint mvwget_wch(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwch\fR\fB);\fR
-.br
-\fBint unget_wch(const wchar_t \fR\fIwch\fR\fB);\fR
+.nf
+\fB#include <curses.h>
+.PP
+\fBint get_wch(wint_t *\fIwch\fP);
+\fBint wget_wch(WINDOW *\fIwin\fP, wint_t *\fIwch\fP);
+\fBint mvget_wch(int \fIy\fP, int \fIx\fP, wint_t *\fIwch\fP);
+\fBint mvwget_wch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, wint_t *\fIwch\fP);
+.PP
+\fBint unget_wch(const wchar_t \fIwc\fP);
+.fi
.SH DESCRIPTION
-The
-\fBget_wch\fR,
-\fBwget_wch\fR,
-\fBmvget_wch\fR, and
-\fBmvwget_wch\fR
-functions read a character
-from the terminal associated with the current or specified window.
-In no-delay mode,
-if no input is waiting, the value \fBERR\fR is returned.
-In delay mode,
-the program waits until the system passes text through to the program.
-Depending on the setting of \fBcbreak\fR,
-this is after one character (cbreak mode),
-or after the first newline (nocbreak mode).
-In half-delay mode,
-the program waits until the user types a character or the specified
-timeout interval has elapsed.
+.SS "Reading Characters"
+.B \%wget_wch
+gathers a key stroke
+.I wch
+from the terminal keyboard associated with a
+.I curses
+window
+.IR win ,
+returning
+.B OK
+if a wide character is read,
+.B \%KEY_CODE_YES
+if a function key is read,
+and
+.B ERR
+if no key event is available.
+\fB\%ncurses\fP(3X) describes the variants of this function.
.PP
-Unless \fBnoecho\fR has been set,
-these routines echo the character into the designated window.
+When input is pending,
+.B \%wget_wch
+stores an integer
+identifying the key stroke in
+.IR wch ;
+for alphanumeric and punctuation keys,
+this value corresponds to the character encoding used by the terminal.
+Use of the control key as a modifier often results in a distinct code.
+The behavior of other keys depends on whether
+.I win
+is in keypad mode;
+see subsections \*(``Keypad Mode\*('' and \*(``Predefined Key Codes\*(''
+in \fB\%getch\fP(3X).
.PP
-If the window is not a pad and has been moved or modified since the
-last call to \fBwrefresh\fR,
-\fBwrefresh\fR will be called before another character is read.
+If no input is pending,
+then if the no-delay flag is set in the window
+(see \fB\%nodelay\fP(3X)),
+the function returns
+.BR ERR ;
+otherwise,
+.I curses
+waits until the terminal has input.
+If \fB\%cbreak\fP(3X)
+has been called,
+this happens after one character is read.
+If \fB\%nocbreak\fP(3X)
+has been called,
+it occurs when the next newline is read.
+If \fB\%halfdelay\fP(3X)
+has been called,
+.I curses
+waits until a character is typed or the specified delay elapses.
.PP
-If \fBkeypad\fR is enabled,
-these functions respond to
-the pressing of a function key by setting the object pointed to by
-\fIwch\fR
-to the corresponding
-\fBKEY_\fR
-value defined
+If \fB\%echo\fP(3X) has been called,
+and the window is not a pad,
+.I curses
+writes
+.I wch
+to the window
+(at the cursor position)
+per the following rules.
+.bP
+If
+.I wch
+matches the terminal's erase character,
+the cursor moves leftward one position
+and the new position is erased
+as if \fB\%wmove\fP(3X) and then \fB\%wdelch\fP(3X) were called.
+When the window's keypad mode is enabled
+(see below),
+.B \%KEY_LEFT
+and
+.B \%KEY_BACKSPACE
+are handled the same way.
+.bP
+.I curses
+writes any other
+.I wch
+to the window,
+as with \fB\%wecho_wchar\fP(3X).
+.bP
+If the window has been moved or modified since the last call to
+\fB\%wrefresh\fP(3X),
+.I curses
+calls
+.BR \%wrefresh .
+.PP
+If
+.I wch
+is a carriage return and \fBnl\fP(3X) has been called,
+.B \%wgetch
+stores the the character code for newline
+(line feed)
in
-\fB<curses.h>\fR
-and returning
-\fBKEY_CODE_YES\fR.
-If a character (such as escape) that could be the
-beginning of a function key is received, curses sets a timer.
-If the remainder
-of the sequence does arrive within the designated time, curses passes through
-the character; otherwise, curses returns the function key value.
-For this
-reason, many terminals experience a delay between the time a user presses
-the escape key and the time the escape is returned to the program.
-.PP
-The
-\fBunget_wch\fR
-function pushes the wide character
-\fIwch\fR
-back onto the head of the input queue, so the wide character
-is returned by the next call to
-\fBget_wch\fR.
-The pushback of
-one character is guaranteed.
-If the program calls
-\fBunget_wch\fR
-too many times without an intervening call to
-\fBget_wch\fR,
-the operation may fail.
-.SH NOTES
-The header file
-\fB<curses.h>\fR
-automatically
-includes the header file
-\fB<stdio.h>\fR.
-.PP
-Applications should not define the escape key by itself as a single-character
-function.
-.PP
-When using
-\fBget_wch\fR,
-\fBwget_wch\fR,
-\fBmvget_wch\fR, or
-\fBmvwget_wch\fR, applications should
-not use
-\fBnocbreak\fR
-mode and
-\fBecho\fR
-mode
-at the same time.
-Depending on the state of the tty driver when each character
-is typed, the program may produce undesirable results.
-.PP
-All functions except \fBwget_wch\fR and \fBunget_wch\fR
-may be macros.
+.I wch
+instead.
+.SS "Ungetting Characters"
+.B \%unget_wch
+places
+.I wch
+into the input queue to be returned by the next call to
+.BR \%wget_wch .
+A single input queue serves all windows.
.SH RETURN VALUE
-When
-\fBget_wch\fR,
-\fBwget_wch\fR,
-\fBmvget_wch\fR, and
-\fBmvwget_wch\fR
-functions successfully
-report the pressing of a function key, they return
-\fBKEY_CODE_YES\fR.
-When they successfully report a wide character, they return
-\fBOK\fR.
-Otherwise, they return
-\fBERR\fR.
-.PP
-Upon successful completion,
-\fBunget_wch\fR
+.B \%wget_wch
returns
-\fBOK\fR.
-Otherwise, the function returns
-\fBERR\fR.
+.B OK
+when it reads a wide character and
+.B \%KEY_CODE_YES
+when it reads a function key code.
+It returns
+.B ERR
+if
+.bP
+the
+.I \%WINDOW
+pointer is
+.BR NULL ,
+or
+.bP
+its timeout expires without any data arriving,
+or
+.bP
+execution was interrupted by a signal,
+in which case
+.B \%errno
+is set to
+.BR \%EINTR .
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
+.PP
+.B \%unget_wch
+returns
+.B OK
+on success and
+.B ERR
+if there is no more room in the input queue.
+.SH NOTES
+See the \*(``NOTES\*('' section of \fB\%wgetch\fP(3X).
+.PP
+All of these functions except
+.B \%wget_wch
+and
+.B \%unget_wch
+may be implemented as macros.
+.PP
+Unlike \fB\%wgetch\fP(3X),
+.B \%wget_wch
+and its variants store the value of the input character in an additional
+.I wch
+parameter instead of the return value.
+.PP
+Unlike
+.BR \%ungetch ,
+.B \%unget_wch
+cannot distinguish function key codes
+.B \%wget_wch
+from conventional character codes.
+An application can overcome this limitation by pushing function key
+codes with
+.B \%ungetch
+and subsequently checking the return value of
+.B \%wget_wch
+for a match with
+.BR \%KEY_CODE_YES .
+.SH EXTENSIONS
+See the \*(``EXTENSIONS\*('' section of \fB\%wgetch\fP(3X).
+.SH PORTABILITY
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
+.PP
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+.PP
+See the \*(``PORTABILITY\*('' section of \fB\%wgetch\fP(3X) regarding
+the interaction of
+.B \%wget_wch
+with signal handlers.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_getch\fR(3X),
-\fBcurs_ins_wch\fR(3X),
-\fBcurs_inopts\fR(3X),
-\fBcurs_move\fR(3X),
-\fBcurs_refresh\fR(3X)
+\fB\%curs_getch\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its non-wide-character configuration.
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_add_wch\fP(3X),
+\fB\%curs_inopts\fP(3X),
+\fB\%curs_move\fP(3X),
+\fB\%curs_refresh\fP(3X)
diff --git a/man/curs_get_wstr.3x b/man/curs_get_wstr.3x
index 2a3fb3c..32ae541 100644
--- a/man/curs_get_wstr.3x
+++ b/man/curs_get_wstr.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 2002-2012,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 *
@@ -26,151 +27,200 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_get_wstr.3x,v 1.9 2012/11/03 23:03:59 tom Exp $
-.TH curs_get_wstr 3X ""
-.na
-.hy 0
+.\" $Id: curs_get_wstr.3x,v 1.48 2024/04/20 19:18:18 tom Exp $
+.TH curs_get_wstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBget_wstr\fR,
-\fBgetn_wstr\fR,
-\fBwget_wstr\fR,
-\fBwgetn_wstr\fR,
-\fBmvget_wstr\fR,
-\fBmvgetn_wstr\fR,
-\fBmvwget_wstr\fR,
-\fBmvwgetn_wstr\fR \- get an array of wide characters from a curses terminal keyboard
-.ad
-.hy
+\fB\%get_wstr\fP,
+\fB\%getn_wstr\fP,
+\fB\%wget_wstr\fP,
+\fB\%wgetn_wstr\fP,
+\fB\%mvget_wstr\fP,
+\fB\%mvgetn_wstr\fP,
+\fB\%mvwget_wstr\fP,
+\fB\%mvwgetn_wstr\fP \-
+get a wide-character string from a \fIcurses\fR terminal keyboard
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fR
-.sp
-\fBint get_wstr(wint_t *\fR\fIwstr\fR\fB);\fR
-.br
-\fBint getn_wstr(wint_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint wget_wstr(WINDOW *\fR\fIwin\fR\fB, wint_t *\fR\fIwstr\fR\fB);\fR
-.br
-\fBint wgetn_wstr(WINDOW *\fR\fIwin\fR\fB, wint_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint mvget_wstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwstr\fR\fB);\fR
-.br
-\fBint mvgetn_wstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint mvwget_wstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwstr\fR\fB);\fR
-.br
-\fBint mvwgetn_wstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
+\fB#include <curses.h>
+.PP
+\fBint get_wstr(wint_t *\fIwstr\fP);
+\fBint getn_wstr(wint_t *\fIwstr\fP, int \fIn\fP);
+\fBint wget_wstr(WINDOW *\fIwin\fP, wint_t *\fIwstr\fP);
+\fBint wgetn_wstr(WINDOW *\fIwin\fP, wint_t *\fIwstr\fP, int \fIn\fP);
+.PP
+\fBint mvget_wstr(int \fIy\fP, int \fIx\fP, wint_t *\fIwstr\fP);
+\fBint mvgetn_wstr(int \fIy\fP, int \fIx\fP, wint_t *\fIwstr\fP, int \fIn\fP);
+\fBint mvwget_wstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, wint_t *\fIwstr\fP);
+\fBint mvwgetn_wstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, wint_t *\fIwstr\fP, int \fIn\fP);
.fi
.SH DESCRIPTION
-The effect of
-\fBget_wstr\fR
-is as though a series of calls
-to
-\fBget_wch\fR
-were made, until a newline, other end-of-line, or end-of-file condition is processed.
-An end-of-file condition is represented by \fBWEOF\fR, as defined in \fB<wchar.h>\fR.
-The newline and end-of-line conditions are represented by the \fB\\n\fR \fBwchar_t\fR value.
-In all instances, the end of the string is terminated by a null \fBwchar_t\fR.
-The routine places resulting values in the area pointed to by \fIwstr\fR.
+The function
+\fBwgetn_wstr\fP
+is equivalent to a series of calls to
+\fBwget_wch\fP(3X)
+until a newline or carriage return terminates the series:
+.bP
+The terminating character is not included in the returned string.
+.bP
+An end-of-file condition is represented by \fBWEOF\fP,
+as defined in \fB<wchar.h>\fP.
+.bP
+In all instances, the end of the string is terminated
+by a null \fBwchar_t\fP.
+.bP
+The function stores the result in the area pointed to
+by the \fIwstr\fP parameter.
+.bP
+The function reads at most \fIn\fP characters,
+thus preventing a possible overflow of the input buffer.
+.IP
+Any attempt to enter more characters
+(other than the terminating newline or carriage return)
+causes a beep.
+.IP
+Function keys also cause a beep and are ignored.
.PP
-The user's erase and kill characters are interpreted. If keypad
-mode is on for the window, \fBKEY_LEFT\fR and \fBKEY_BACKSPACE\fR
-are both considered equivalent to the user's kill character.
+The user's \fIerase\fP and \fIkill\fP characters are interpreted:
+.bP
+The \fIerase\fP character (e.g., \fB^H\fP) erases the character
+at the end of the buffer, moving the cursor to the left.
+.IP
+If \fIkeypad\fP mode is on for the window,
+\fBKEY_LEFT\fP and \fBKEY_BACKSPACE\fP
+are both considered equivalent to the user's \fIerase\fP character.
+.bP
+The \fIkill\fP character (e.g., \fB^U\fP) erases the entire buffer,
+leaving the cursor at the beginning of the buffer.
.PP
-Characters input are echoed only if \fBecho\fR is currently on. In that case,
-backspace is echoed as deletion of the previous character (typically a left
-motion).
-.PP
-The effect of
-\fBwget_wstr\fR
-is as though a series of
-calls to
-\fBwget_wch\fR
-were made.
-.PP
-The effect of
-\fBmvget_wstr\fR
-is as though a call to
-\fBmove\fR
-and then a series of calls to
-\fBget_wch\fR
-were
-made.
-.PP
-The effect of
-\fBmvwget_wstr\fR
-is as though a call to
-\fBwmove\fR
-and then a series of calls to
-\fBwget_wch\fR
-were made.
+Characters input are echoed only if \fBecho\fP is currently on.
+In that case,
+backspace is echoed as deletion of the previous character
+(typically a left motion).
.PP
The
-\fBgetn_wstr\fR,
-\fBmvgetn_wstr\fR,
-\fBmvwgetn_wstr\fR, and
-\fBwgetn_wstr\fR
+\fBgetn_wstr\fP,
+\fBmvgetn_wstr\fP,
+\fBmvwgetn_wstr\fP, and
+\fBwgetn_wstr\fP
functions are identical
to the
-\fBget_wstr\fR,
-\fBmvget_wstr\fR,
-\fBmvwget_wstr\fR, and
-\fBwget_wstr\fR
+\fBget_wstr\fP,
+\fBmvget_wstr\fP,
+\fBmvwget_wstr\fP, and
+\fBwget_wstr\fP
functions, respectively,
except that the
-\fB*n_*\fR
+\fB*n_*\fP
versions read at most
-\fIn\fR
+\fIn\fP
characters, letting the application prevent overflow of the
input buffer.
+.SH RETURN VALUE
+All of these functions return the integer \fBOK\fP upon successful completion.
+If unsuccessful, they return \fBERR\fP.
+.PP
+X/Open defines no error conditions.
+.PP
+In this implementation,
+these functions return an error
+.bP
+if the window pointer is null,
+.bP
+if its timeout expires without having any data, or
+.bP
+if the associated call to
+\fBwget_wch\fP
+failed.
+.PP
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
+Any of these functions other than
+\fBwgetn_wstr\fP
+may be macros.
+.PP
Using
-\fBget_wstr\fR,
-\fBmvget_wstr\fR,
-\fBmvwget_wstr\fR, or
-\fBwget_wstr\fR
+\fBget_wstr\fP,
+\fBmvget_wstr\fP,
+\fBmvwget_wstr\fP, or
+\fBwget_wstr\fP
to read a line that
overflows the array pointed to by
-\fBwstr\fR
+\fBwstr\fP
causes undefined
results.
The use of
-\fBgetn_wstr\fR,
-\fBmvgetn_wstr\fR,
-\fBmvwgetn_wstr\fR, or
-\fBwgetn_wstr\fR, respectively, is recommended.
+\fBgetn_wstr\fP,
+\fBmvgetn_wstr\fP,
+\fBmvwgetn_wstr\fP, or
+\fBwgetn_wstr\fP,
+respectively, is recommended.
.PP
-These functions cannot return \fBKEY_\fR values because there
-is no way to distinguish a \fBKEY_\fR value from a valid \fBwchar_t\fR value.
-.PP
-All of these routines except \fBwgetn_wstr\fR may be macros.
-.SH RETURN VALUE
-All of these functions return \fBOK\fR upon successful completion.
-Otherwise, they return \fBERR\fR.
-.PP
-Functions using a window parameter return an error if it is null.
-.RS
-.TP 5
-\fBwgetn_wstr\fP
-returns an error if the associated call to \fBwget_wch\fP failed.
-.RE
-.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+These functions cannot return \fBKEY_\fP values because there
+is no way to distinguish a \fBKEY_\fP value from a valid \fBwchar_t\fP value.
.SH PORTABILITY
These functions are described in The Single Unix Specification, Version 2.
No error conditions are defined.
-This implementation returns ERR if the window pointer is null,
-or if the lower-level \fBwget_wch\fR call returns an ERR.
-In the latter case,
-an ERR return without other data is treated as an end-of-file condition,
-and the returned array contains a \fBWEOF\fR followed by a null \fBwchar_t\fR.
.PP
-X/Open curses documents these functions to pass an array of \fBwchar_t\fR,
-but all of the vendors implement this using \fBwint_t\fR.
+This implementation returns \fBERR\fP if the window pointer is null,
+or if the lower-level \fBwget_wch\fP call returns an \fBERR\fP.
+In the latter case,
+an \fBERR\fP return without other data is treated as an end-of-file condition,
+and the returned array contains a \fBWEOF\fP followed by a null \fBwchar_t\fP.
+.PP
+X/Open curses documented these functions to pass an array of \fBwchar_t\fP
+in 1997, but that was an error because of this part of the description:
+.RS
+.PP
+The effect of \fBget_wstr\fP is as though a series of calls to
+\fBget_wch\fP were made, until a newline character, end-of-line character, or
+end-of-file character is processed.
+.RE
+.PP
+The latter function \fIget_wch\fP can return a negative value,
+while \fBwchar_t\fP is a unsigned type.
+All of the vendors implement this using \fBwint_t\fP, following the standard.
+.PP
+X/Open Curses, Issue 7 (2009) is unclear regarding whether
+the terminating \fInull \fBwchar_t\fR
+value is counted in the length parameter \fIn\fP.
+X/Open Curses, Issue 7 revised the corresponding description
+of \fBwgetnstr\fP to address this issue.
+The unrevised description of \fBwget_nwstr\fP can be interpreted either way.
+This implementation counts the terminator in the length.
+.PP
+X/Open Curses does not specify what happens if the length \fIn\fP is negative.
+.bP
+For analogy with \fBwgetnstr\fP,
+\fI\%ncurses\fP 6.2 uses a limit (based on \fBLINE_MAX\fP).
+.bP
+Some other implementations (such as Solaris xcurses) do the same,
+while others (PDCurses) do not allow this.
+.bP
+NetBSD 7 curses imitates \fI\%ncurses\fP 6.1 in this regard,
+treating a \fB\-1\fP as an indefinite number of characters.
.SH SEE ALSO
-Functions:
-\fBcurses\fR(3X),
-\fBcurs_get_wch\fR(3X),
-\fBcurs_getstr\fR(3X).
+\fB\%curs_getstr\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its non-wide-character configuration.
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_get_wch\fP(3X)
diff --git a/man/curs_getcchar.3x b/man/curs_getcchar.3x
index 4c5b229..523cc99 100644
--- a/man/curs_getcchar.3x
+++ b/man/curs_getcchar.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2001-2012,2015 Free Software Foundation, Inc. *
+.\" Copyright 2019-2023,2024 Thomas E. Dickey *
+.\" Copyright 2001-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 *
@@ -26,72 +27,64 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getcchar.3x,v 1.17 2015/07/21 09:30:38 tom Exp $
-.TH curs_getcchar 3X ""
+.\" $Id: curs_getcchar.3x,v 1.49 2024/04/20 18:55:09 tom Exp $
+.TH curs_getcchar 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.SH NAME
-\fBgetcchar\fP,
-\fBsetcchar\fP \- Get a wide character string and rendition from a \fBcchar_t\fP or set a \fBcchar_t\fP from a wide-character string
+\fB\%getcchar\fP,
+\fB\%setcchar\fP \-
+convert between a wide-character string and a \fIcurses\fR complex character
.SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-\fBint getcchar(\fP
-.br
-.B " const cchar_t *\fIwcval\fP,"
-.br
-.B " wchar_t *\fIwch\fP,"
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint getcchar(
+.B " const cchar_t *\fIwch\fP,"
+.B " wchar_t *\fIwc\fP,"
.B " attr_t *\fIattrs\fP,"
-.br
.B " short *\fIcolor_pair\fP,"
-.br
.B " void *\fIopts\fP );"
-.sp
+.PP
.B "int setcchar("
-.br
-.B " cchar_t *\fIwcval\fP,"
-.br
-.B " const wchar_t *\fIwch\fP,"
-.br
+.B " cchar_t *\fIwch\fP,"
+.B " const wchar_t *\fIwc\fP,"
.B " const attr_t \fIattrs\fP,"
-.br
.B " short \fIcolor_pair\fP,"
-.br
-.B " void *\fIopts\fP );"
+.B " const void *\fIopts\fP );"
+.fi
.SH DESCRIPTION
.SS getcchar
-.PP
The \fBgetcchar\fP function gets a wide-character string
and rendition from a \fBcchar_t\fP argument.
-When \fIwch\fP is not a null pointer,
+When \fIwc\fP is not a null pointer,
the \fBgetcchar\fP function does the following:
.bP
-Extracts information from a \fBcchar_t\fP value \fIwcval\fP
+Extracts information from a \fBcchar_t\fP value \fIwch\fP
.bP
Stores the character attributes in the location pointed to by \fIattrs\fP
.bP
-Stores the color-pair in the location pointed to by \fIcolor_pair\fP
+Stores the color pair in the location pointed to by \fIcolor_pair\fP
.bP
Stores the wide-character string,
-characters referenced by \fIwcval\fP, into the array pointed to by \fIwch\fP.
+characters referenced by \fIwch\fP, into the array pointed to by \fIwc\fP.
.PP
When
-\fIwch\fP
+\fIwc\fP
is a null pointer, the
\fBgetcchar\fP
function does the following:
.bP
-Obtains the number of wide characters pointed to by \fIwcval\fP
+Obtains the number of wide characters pointed to by \fIwch\fP
.bP
Does not change the data referenced by
\fIattrs\fP
or
\fIcolor_pair\fP
.SS setcchar
-.PP
-The \fBsetcchar\fP function initializes the location pointed to by \fIwcval\fP
+The \fBsetcchar\fP function initializes the location pointed to by \fIwch\fP
by using:
.bP
The character attributes in
@@ -100,41 +93,96 @@
The color pair in
\fIcolor_pair\fP
.bP
-The wide-character string pointed to by \fIwch\fP.
-The string must be L'\\0' terminated,
+The wide-character string pointed to by \fIwc\fP.
+The string must be L'\e0' terminated,
contain at most one spacing character,
which must be the first.
.IP
-Up to \fBCCHARW_MAX\fP\-1 nonspacing characters may follow.
-Additional nonspacing characters are ignored.
+Up to \fBCCHARW_MAX\fP\-1 non-spacing characters may follow.
+Additional non-spacing characters are ignored.
.IP
The string may contain a single control character instead.
-In that case, no nonspacing characters are allowed.
-.SH NOTES
-.PP
-The \fIopts\fP argument is reserved for future use.
-Currently, an application must provide a null pointer as \fIopts\fP.
-.PP
-The \fIwcval\fP argument may be a value generated by a call to
-\fBsetcchar\fP or by a function that has a \fBcchar_t\fP output argument.
-If \fIwcval\fP is constructed by any other means, the effect is unspecified.
+In that case, no non-spacing characters are allowed.
.SH RETURN VALUE
-.PP
-When \fIwch\fP is a null pointer,
+When \fIwc\fP is a null pointer,
\fBgetcchar\fP returns the number of wide characters referenced by
-\fIwcval\fP,
+\fIwch\fP,
including one for a trailing null.
.PP
-When \fIwch\fP is not a null pointer,
+When \fIwc\fP is not a null pointer,
\fBgetcchar\fP returns \fBOK\fP upon successful completion,
and \fBERR\fP otherwise.
.PP
Upon successful completion, \fBsetcchar\fP returns \fBOK\fP.
Otherwise, it returns \fBERR\fP.
-.SH SEE ALSO
+.SH NOTES
+The \fIwch\fP argument may be a value generated by a call to
+\fBsetcchar\fP or by a function that has a \fBcchar_t\fP output argument.
+If \fIwch\fP is constructed by any other means, the effect is unspecified.
+.SH EXTENSIONS
+X/Open Curses documents the \fIopts\fP argument as reserved for future use,
+saying that it must be null.
+This implementation
+uses that parameter in ABI 6 for the functions which have a color pair
+parameter to support extended color pairs:
+.bP
+For functions which modify the color, e.g., \fBsetcchar\fP,
+if \fIopts\fP is set it is treated as a pointer to \fBint\fP,
+and used to set the color pair instead of the \fBshort\fP pair parameter.
+.bP
+For functions which retrieve the color, e.g., \fBgetcchar\fP,
+if \fIopts\fP is set it is treated as a pointer to \fBint\fP,
+and used to retrieve the color pair as an \fBint\fP value,
+in addition retrieving it via the standard pointer to \fBshort\fP parameter.
+.SH PORTABILITY
+The \fBCCHARW_MAX\fP symbol is specific to \fI\%ncurses\fP.
+X/Open Curses does not provide details for the layout of the \fBcchar_t\fP
+structure.
+It tells what data are stored in it:
+.bP
+a spacing character (\fBwchar_t\fP, i.e., 32-bits).
+.bP
+non-spacing characters (again, \fBwchar_t\fP's).
+.bP
+attributes (at least 16 bits, inferred from the various ACS- and WACS-flags).
+.bP
+color pair (at least 16 bits, inferred from the \fBunsigned short\fP type).
.PP
-Functions:
-\fBcurs_attr\fR(3X),
-\fBcurs_color\fR(3X),
-\fBcurses\fR(3X),
-\fBwcwidth\fR(3).
+The non-spacing characters are optional,
+in the sense that zero or more may be stored in a \fBcchar_t\fP.
+XOpen/Curses specifies a limit:
+.RS 4
+.PP
+Implementations may limit the number of non-spacing characters that can be
+associated with a spacing character, provided any limit is at least 5.
+.RE
+.PP
+The Unix implementations at the time follow that limit:
+.bP
+AIX\ 4 and OSF1\ 4 use the same declaration with an array of 5 non-spacing
+characters \fIz\fP and a single spacing character \fIc\fP.
+.bP
+HP-UX\ 10 uses an opaque structure with 28 bytes,
+which is large enough for the 6 \fBwchar_t\fP values.
+.bP
+Solaris \fIxpg4\fP curses uses a single array of 6 \fBwchar_t\fP values.
+.PP
+This implementation's \fBcchar_t\fP was defined in 1995
+using \fB5\fP for the total of spacing and non-spacing characters
+(\fBCCHARW_MAX\fP).
+That was probably due to a misreading of the AIX\ 4 header files,
+because the X/Open Curses document was not generally available at that time.
+Later (in 2002), this detail was overlooked when beginning to implement
+the functions using the structure.
+.PP
+In practice, even four non-spacing characters may seem enough.
+X/Open Curses documents possible uses for non-spacing characters,
+including using them for ligatures between characters
+(a feature apparently not supported by any curses implementation).
+Unicode does not limit the (analogous) number of combining characters,
+so some applications may be affected.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%curs_attr\fP(3X),
+\fB\%curs_color\fP(3X),
+\fB\%wcwidth\fP(3)
diff --git a/man/curs_getch.3x b/man/curs_getch.3x
index 8d94e0a..9433c61 100644
--- a/man/curs_getch.3x
+++ b/man/curs_getch.3x
@@ -1,6 +1,7 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2014,2015 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -27,345 +28,670 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getch.3x,v 1.42 2015/07/21 08:44:04 tom Exp $
-.TH curs_getch 3X ""
-.na
-.hy 0
+.\" $Id: curs_getch.3x,v 1.87 2024/04/20 19:18:18 tom Exp $
+.TH curs_getch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.ds ^ \(ha
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.ds ^ ^
+.\}
+.
+.ie \n(.g .ds : \:
+.el .ds : \" empty
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.SH NAME
-\fBgetch\fR,
-\fBwgetch\fR,
-\fBmvgetch\fR,
-\fBmvwgetch\fR,
-\fBungetch\fR,
-\fBhas_key\fR \- get (or push back) characters from \fBcurses\fR terminal keyboard
-.ad
-.hy
+\fB\%getch\fP,
+\fB\%wgetch\fP,
+\fB\%mvgetch\fP,
+\fB\%mvwgetch\fP,
+\fB\%ungetch\fP,
+\fB\%has_key\fP \-
+get (or push back) characters from \fIcurses\fR terminal keyboard
.SH SYNOPSIS
-\fB#include <curses.h>\fR
+.nf
+.B #include <curses.h>
.PP
-\fBint getch(void);\fR
-.br
-\fBint wgetch(WINDOW *\fP\fIwin);\fR
-.br
-\fBint mvgetch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR
-.br
-\fBint mvwgetch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR
-.br
-\fBint ungetch(int \fP\fIch\fP\fB);\fR
-.br
-\fBint has_key(int \fP\fIch\fP\fB);\fR
-.br
+.B int getch(void);
+.B int wgetch(WINDOW *\fIwin\fP);
+.B int mvgetch(int \fIy\fP, int \fIx\fP);
+.B int mvwgetch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
+.PP
+.B int ungetch(int \fIc\fP);
+.PP
+.\" XXX: Move has_key into its own page like define_key and key_defined?
+\fI/* extension */\fP
+.B int has_key(int \fIc\fP);
+.fi
.SH DESCRIPTION
-.SS Reading characters
-The \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR and \fBmvwgetch\fR, routines read
-a character from the window.
-In no-delay mode, if no input is waiting, the value \fBERR\fR is returned.
-In delay mode, the program waits until the system
-passes text through to the program.
-Depending on the setting of \fBcbreak\fR,
-this is after one character (cbreak mode),
-or after the first newline (nocbreak mode).
-In half-delay mode,
-the program waits until a character is typed or the
-specified timeout has been reached.
+.SS "Reading Characters"
+.B \%wgetch
+gathers a key stroke from the terminal keyboard associated with a
+.I curses
+window
+.IR win .
+\fB\%ncurses\fP(3X) describes the variants of this function.
.PP
-If \fBecho\fR is enabled, and the window is not a pad,
-then the character will also be echoed into the
-designated window according to the following rules:
+When input is pending,
+.B \%wgetch
+returns an integer identifying the key stroke;
+for alphanumeric and punctuation keys,
+this value corresponds to the character encoding used by the terminal.
+Use of the control key as a modifier often results in a distinct code.
+The behavior of other keys depends on whether
+.I win
+is in keypad mode;
+see subsection \*(``Keypad Mode\*('' below.
+.PP
+If no input is pending,
+then if the no-delay flag is set in the window
+(see \fB\%nodelay\fP(3X)),
+the function returns
+.BR ERR ;
+otherwise,
+.I curses
+waits until the terminal has input.
+If \fB\%cbreak\fP(3X)
+has been called,
+this happens after one character is read.
+If \fB\%nocbreak\fP(3X)
+has been called,
+it occurs when the next newline is read.
+If \fB\%halfdelay\fP(3X)
+has been called,
+.I curses
+waits until a character is typed or the specified delay elapses.
+.PP
+If \fB\%echo\fP(3X) has been called,
+and the window is not a pad,
+.I curses
+writes the returned character
+.I c
+to the window
+(at the cursor position)
+per the following rules.
.bP
-If the character is the current erase character, left arrow, or backspace,
-the cursor is moved one space to the left and that screen position is erased
-as if \fBdelch\fR had been called.
+If
+.I c
+matches the terminal's erase character,
+the cursor moves leftward one position
+and the new position is erased
+as if \fB\%wmove\fP(3X) and then \fB\%wdelch\fP(3X) were called.
+When the window's keypad mode is enabled
+(see below),
+.B \%KEY_LEFT
+and
+.B \%KEY_BACKSPACE
+are handled the same way.
.bP
-If the character value is any other \fBKEY_\fR define, the user is alerted
-with a \fBbeep\fR call.
+.I curses
+writes any other
+.I c
+to the window,
+as with \fB\%wechochar\fP(3X).
.bP
-If the character is a carriage-return,
-and if \fBnl\fP is enabled,
-it is translated to a line-feed after echoing.
+If the window has been moved or modified since the last call to
+\fB\%wrefresh\fP(3X),
+.I curses
+calls
+.BR \%wrefresh .
+.PP
+If
+.I c
+is a carriage return and \fBnl\fP(3X) has been called,
+.B \%wgetch
+returns the character code for line feed instead.
+.SS "Keypad Mode"
+To
+.IR curses ,
+key strokes not from the alphabetic section of the keyboard
+(those corresponding to the ECMA-6 character set\(emsee
+\fIascii\fP(7)\(emoptionally modified by either the control or shift
+keys)
+are treated as
+.I function
+keys.
+(In
+.IR curses ,
+the term \*(``function key\*('' includes but is not limited to keycaps
+engraved with \*(``F1\*('',
+\*(``PF1\*('',
+and so on.)
+If the window is in keypad mode,
+these produce a numeric code corresponding to the
+.B KEY_
+symbols listed in subsection \*(``Predefined Key Codes\*('' below;
+otherwise,
+they transmit a sequence of codes typically starting with the escape
+character,
+and which must be collected with multiple
+.B \%wgetch
+calls.
.bP
-Otherwise the character is simply output to the screen.
+The
+.I \%curses.h
+header file declares many
+.I "predefined function keys"
+whose names begin with
+.BR KEY_ ;
+these object-like macros have values outside the range of eight-bit
+character codes.
+.bP
+In
+.IR \%ncurses ,
+.I "user-defined function keys"
+are configured with \fB\%define_key\fP(3X);
+they have no names,
+but are also expected to have values outside the range of eight-bit
+codes.
.PP
-If the window is not a pad, and it has been moved or modified since the last
-call to \fBwrefresh\fR, \fBwrefresh\fR will be called before another character
-is read.
-.SS Keypad mode
+A variable intended to hold a function key code must thus be of type
+.I short
+or larger.
.PP
-If \fBkeypad\fR is \fBTRUE\fR, and a function key is pressed, the token for
-that function key is returned instead of the raw characters.
-Possible function
-keys are defined in \fB<curses.h>\fR as macros with values outside the range
-of 8-bit characters whose names begin with \fBKEY_\fR.
-Thus, a variable
-intended to hold the return value of a function key must be of short size or
-larger.
-.PP
-When a character that could be the beginning of a function key is received
-(which, on modern terminals, means an escape character),
-\fBcurses\fR sets a timer.
-If the remainder of the sequence does not come in within the designated
-time, the character is passed through;
-otherwise, the function key value is returned.
-For this reason, many terminals experience a delay between the time
-a user presses the escape key and the escape is returned to the program.
-.SS Ungetting characters
-.PP
-The \fBungetch\fR routine places \fIch\fR back onto the input queue to be
-returned by the next call to \fBwgetch\fR.
-There is just one input queue for all windows.
-.PP
-.SS Predefined key-codes
-The following special keys, defined in \fB<curses.h>\fR, may be returned by
-\fBgetch\fR if \fBkeypad\fR has been enabled.
+Most terminals one encounters follow the ECMA-48 standard insofar as
+their function keys produce character sequences prefixed with the
+escape character ESC.
+This fact implies that
+.I curses
+cannot know whether the terminal has sent an ESC key stroke or the
+beginning of a function key's character sequence without waiting to see
+if,
+and how soon,
+further input arrives.
+When
+.I curses
+reads such an ambiguous character,
+it sets a timer.
+If the remainder of the sequence does not arrive within the designated
+time,
+.B \%wgetch
+returns the prefix character;
+otherwise,
+it returns the function key code corresponding to the unique sequence
+defined by the terminal.
+Consequently,
+a user of a
+.I curses
+application may experience a delay after pressing ESC while
+.I curses
+disambiguates the input;
+see section \*(``EXTENSIONS\*('' below.
+If the window is in \*(``no time-out\*('' mode,
+the timer does not expire;
+it is an infinite
+(or very large)
+value.
+See \fB\%notimeout\fP(3X).
+Because function key sequences usually begin with an escape character,
+the terminal may appear to hang in no time-out mode after the user has
+pressed ESC.
+Generally,
+further typing \*(``awakens\*(''
+.IR curses .
+.SS "Ungetting Characters"
+.B \%ungetch
+places
+.I c
+into the input queue to be returned by the next call to
+.BR \%wgetch .
+A single input queue serves all windows.
+.SS "Predefined Key Codes"
+The header file
+.I \%curses.h
+defines the following function key codes.
+.bP
+Except for the special case of
+.BR \%KEY_RESIZE ,
+a window's keypad mode must be enabled for
+.B \%wgetch
+to read these codes from it.
+.bP
Not all of these are necessarily supported on any particular terminal.
+.bP
+The naming convention may seem obscure,
+with some apparent misspellings
+(such as \*(``RSUME\*('' for \*(``resume\*('');
+the names correspond to the
+.I \%term\%info
+capability names for the keys,
+and were standardized before the IBM PC/AT keyboard layout achieved a
+dominant position in industry.
.PP
+.RS
+.\" XXX: Move this list into ncurses(3X), rather than duplicating it in
+.\" get_wch(3X) or having that page cross reference this one?
.TS
-center tab(/) ;
-l l .
-\fIName\fR/\fIKey\fR \fIname\fR
+Lb Lb
+Lb Lx.
+Symbol Key name
+=
+KEY_BREAK Break key
+KEY_DOWN Arrow keys
+KEY_UP \^
+KEY_LEFT \^
+KEY_RIGHT \^
+KEY_HOME Home key (upward+left arrow)
+KEY_BACKSPACE Backspace
+KEY_F0 T{
+Function keys; space for 64 keys is reserved
+T}
+KEY_F(\fIn\fP) T{
+Function key \fIn\fP where 0 \(<= \fIn\fP \(<= 63
+T}
+KEY_DL Delete line
+KEY_IL Insert line
+KEY_DC Delete character
+KEY_IC Insert character/Enter insert mode
+KEY_EIC Exit insert character mode
+KEY_CLEAR Clear screen
+KEY_EOS Clear to end of screen
+KEY_EOL Clear to end of line
+KEY_SF Scroll one line forward
+KEY_SR Scroll one line backward (reverse)
+KEY_NPAGE Next page/Page up
+KEY_PPAGE Previous page/Page down
+KEY_STAB Set tab
+KEY_CTAB Clear tab
+KEY_CATAB Clear all tabs
+KEY_ENTER Enter/Send
+KEY_SRESET Soft (partial) reset
+KEY_RESET (Hard) reset
+KEY_PRINT Print/Copy
+KEY_LL Home down/Bottom (lower left)
+KEY_A1 Upper left of keypad
+KEY_A3 Upper right of keypad
+KEY_B2 Center of keypad
+KEY_C1 Lower left of keypad
+KEY_C3 Lower right of keypad
+KEY_BTAB Back tab key
+KEY_BEG Beg(inning) key
+KEY_CANCEL Cancel key
+KEY_CLOSE Close key
+KEY_COMMAND Cmd (command) key
+KEY_COPY Copy key
+KEY_CREATE Create key
+KEY_END End key
+KEY_EXIT Exit key
+KEY_FIND Find key
+KEY_HELP Help key
+KEY_MARK Mark key
+KEY_MESSAGE Message key
+KEY_MOUSE Mouse event occurred
+KEY_MOVE Move key
+KEY_NEXT Next object key
+KEY_OPEN Open key
+KEY_OPTIONS Options key
+KEY_PREVIOUS Previous object key
+KEY_REDO Redo key
+KEY_REFERENCE Ref(erence) key
+KEY_REFRESH Refresh key
+KEY_REPLACE Replace key
+KEY_RESIZE Screen resized
+KEY_RESTART Restart key
+KEY_RESUME Resume key
+KEY_SAVE Save key
+KEY_SELECT Select key
+KEY_SUSPEND Suspend key
+KEY_UNDO Undo key
_
-KEY_BREAK/Break key
-KEY_DOWN/The four arrow keys ...
-KEY_UP
-KEY_LEFT
-KEY_RIGHT
-KEY_HOME/Home key (upward+left arrow)
-KEY_BACKSPACE/Backspace
-KEY_F0/T{
-Function keys; space for 64 keys is reserved.
-T}
-KEY_F(\fIn\fR)/T{
-For 0 \(<= \fIn\fR \(<= 63
-T}
-KEY_DL/Delete line
-KEY_IL/Insert line
-KEY_DC/Delete character
-KEY_IC/Insert char or enter insert mode
-KEY_EIC/Exit insert char mode
-KEY_CLEAR/Clear screen
-KEY_EOS/Clear to end of screen
-KEY_EOL/Clear to end of line
-KEY_SF/Scroll 1 line forward
-KEY_SR/Scroll 1 line backward (reverse)
-KEY_NPAGE/Next page
-KEY_PPAGE/Previous page
-KEY_STAB/Set tab
-KEY_CTAB/Clear tab
-KEY_CATAB/Clear all tabs
-KEY_ENTER/Enter or send
-KEY_SRESET/Soft (partial) reset
-KEY_RESET/Reset or hard reset
-KEY_PRINT/Print or copy
-KEY_LL/Home down or bottom (lower left)
-KEY_A1/Upper left of keypad
-KEY_A3/Upper right of keypad
-KEY_B2/Center of keypad
-KEY_C1/Lower left of keypad
-KEY_C3/Lower right of keypad
-KEY_BTAB/Back tab key
-KEY_BEG/Beg(inning) key
-KEY_CANCEL/Cancel key
-KEY_CLOSE/Close key
-KEY_COMMAND/Cmd (command) key
-KEY_COPY/Copy key
-KEY_CREATE/Create key
-KEY_END/End key
-KEY_EXIT/Exit key
-KEY_FIND/Find key
-KEY_HELP/Help key
-KEY_MARK/Mark key
-KEY_MESSAGE/Message key
-KEY_MOUSE/Mouse event read
-KEY_MOVE/Move key
-KEY_NEXT/Next object key
-KEY_OPEN/Open key
-KEY_OPTIONS/Options key
-KEY_PREVIOUS/Previous object key
-KEY_REDO/Redo key
-KEY_REFERENCE/Ref(erence) key
-KEY_REFRESH/Refresh key
-KEY_REPLACE/Replace key
-KEY_RESIZE/Screen resized
-KEY_RESTART/Restart key
-KEY_RESUME/Resume key
-KEY_SAVE/Save key
-KEY_SBEG/Shifted beginning key
-KEY_SCANCEL/Shifted cancel key
-KEY_SCOMMAND/Shifted command key
-KEY_SCOPY/Shifted copy key
-KEY_SCREATE/Shifted create key
-KEY_SDC/Shifted delete char key
-KEY_SDL/Shifted delete line key
-KEY_SELECT/Select key
-KEY_SEND/Shifted end key
-KEY_SEOL/Shifted clear line key
-KEY_SEXIT/Shifted exit key
-KEY_SFIND/Shifted find key
-KEY_SHELP/Shifted help key
-KEY_SHOME/Shifted home key
-KEY_SIC/Shifted input key
-KEY_SLEFT/Shifted left arrow key
-KEY_SMESSAGE/Shifted message key
-KEY_SMOVE/Shifted move key
-KEY_SNEXT/Shifted next key
-KEY_SOPTIONS/Shifted options key
-KEY_SPREVIOUS/Shifted prev key
-KEY_SPRINT/Shifted print key
-KEY_SREDO/Shifted redo key
-KEY_SREPLACE/Shifted replace key
-KEY_SRIGHT/Shifted right arrow
-KEY_SRSUME/Shifted resume key
-KEY_SSAVE/Shifted save key
-KEY_SSUSPEND/Shifted suspend key
-KEY_SUNDO/Shifted undo key
-KEY_SUSPEND/Suspend key
-KEY_UNDO/Undo key
+KEY_SBEG Shifted beginning key
+KEY_SCANCEL Shifted cancel key
+KEY_SCOMMAND Shifted command key
+KEY_SCOPY Shifted copy key
+KEY_SCREATE Shifted create key
+KEY_SDC Shifted delete character key
+KEY_SDL Shifted delete line key
+KEY_SEND Shifted end key
+KEY_SEOL Shifted clear line key
+KEY_SEXIT Shifted exit key
+KEY_SFIND Shifted find key
+KEY_SHELP Shifted help key
+KEY_SHOME Shifted home key
+KEY_SIC Shifted insert key
+KEY_SLEFT Shifted left arrow key
+KEY_SMESSAGE Shifted message key
+KEY_SMOVE Shifted move key
+KEY_SNEXT Shifted next object key
+KEY_SOPTIONS Shifted options key
+KEY_SPREVIOUS Shifted previous object key
+KEY_SPRINT Shifted print key
+KEY_SREDO Shifted redo key
+KEY_SREPLACE Shifted replace key
+KEY_SRIGHT Shifted right arrow key
+KEY_SRSUME Shifted resume key
+KEY_SSAVE Shifted save key
+KEY_SSUSPEND Shifted suspend key
+KEY_SUNDO Shifted undo key
.TE
+.RE
.PP
-Keypad is arranged like this:
-.br
+Many keyboards feature a nine-key directional pad.
+.PP
+.RS
.TS
-center allbox tab(/) ;
-c c c .
-\fBA1\fR/\fBup\fR/\fBA3\fR
-\fBleft\fR/\fBB2\fR/\fBright\fR
-\fBC1\fR/\fBdown\fR/\fBC3\fR
+allbox center;
+C C C.
+A1 up A3
+left B2 right
+C1 down C3
.TE
+.RE
.sp
-A few of these predefined values do \fInot\fP correspond to a real key:
+Two of the symbols in the list above do
+.I not
+correspond to a physical key.
.bP
-.B KEY_RESIZE
-is returned when the \fBSIGWINCH\fP signal has been detected
-(see \fBinitscr\fP(3X) and \fBresizeterm\fR(3X)).
+.B \%wgetch
+returns
+.BR \%KEY_RESIZE ,
+even if the window's keypad mode is disabled,
+when
+.I \%ncurses
+handles a
+.B \%SIGWINCH
+signal;
+see \fB\%initscr\fP(3X) and \fB\%resizeterm\fP(3X).
.bP
-.B KEY_MOUSE
-is returned for mouse-events (see \fBcurs_mouse\fR(3X)).
-.SS Testing key-codes
-.PP
-The \fBhas_key\fR routine takes a key-code value from the above list, and
-returns \fBTRUE\fP or \fBFALSE\fP according to whether
-the current terminal type recognizes a key with that value.
-.PP
-The library also supports these extensions:
-.RS 3
-.TP 5
-.B define_key
-defines a key-code for a given string (see \fBdefine_key\fP(3X)).
-.TP 5
-.B key_defined
-checks if there is a key-code defined for a given
-string (see \fBkey_defined\fP(3X)).
-.RE
-.PP
+.B \%wgetch
+returns
+.B \%KEY_MOUSE
+to indicate that a mouse event is pending collection;
+see \fB\%curs_mouse\fP(3X).
+Receipt of this code requires a window's keypad mode to be enabled,
+because to interpret mouse input
+(as with with \fI\%xterm\fP(1)'s mouse prototocol),
+.I \%ncurses
+must read an escape sequence,
+as with a function key.
+.SS "Testing Key Codes"
+In
+.IR \%ncurses ,
+.B \%has_key
+returns a Boolean value indicating whether the terminal type recognizes
+its parameter as a key code value.
+See also
+\fB\%define_key\fP(3X) and \fB\%key_defined\fP(3X).
.SH RETURN VALUE
-All routines return the integer \fBERR\fR upon failure and an integer value
-other than \fBERR\fR (\fBOK\fR in the case of ungetch()) upon successful
-completion.
-.RS 3
-.TP 5
-\fBungetch\fP
-returns ERR
-if there is no more room in the FIFO.
-.TP
-\fBwgetch\fP
-returns ERR
-if the window pointer is null, or
-if its timeout expires without having any data.
-.RE
+Except for
+.BR \%has_key ,
+these functions return
+.B OK
+on success and
+.B ERR
+on failure.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions taking a
+.I \%WINDOW
+pointer argument fail if the pointer is
+.BR NULL .
+.PP
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
+.PP
+.B \%wgetch
+also fails if
+.bP
+its timeout expires without any data arriving,
+or
+.bP
+execution was interrupted by a signal,
+in which case
+.B \%errno
+is set to
+.BR \%EINTR .
+.PP
+.B \%ungetch
+fails if there is no more room in the input queue.
+.PP
+.B \%has_key
+returns
+.B TRUE
+or
+.BR FALSE .
.SH NOTES
-Use of the escape key by a programmer for a single character function is
-discouraged, as it will cause a delay of up to one second while the
-keypad code looks for a following function-key sequence.
+.I curses
+discourages assignment of the ESC key to a discrete function by the
+programmer because the library requires a delay while it awaits the
+potential remainder of a terminal escape sequence.
.PP
-Some keys may be the same as commonly used control
-keys, e.g., \fBKEY_ENTER\fP versus control/M, \fBKEY_BACKSPACE\fP versus control/H.
-Some curses implementations may differ according to whether they
-treat these control keys specially (and ignore the terminfo), or
-use the terminfo definitions.
-\fBNcurses\fR uses the terminfo definition.
-If it says that \fBKEY_ENTER\fP is control/M,
-\fBgetch\fR will return \fBKEY_ENTER\fP
-when you press control/M.
+Some key strokes are indistinguishable from control characters;
+for example,
+.B \%KEY_ENTER
+may be the same as
+.BR \*^M ,
+.\" as with att630 or pccon+keys
+and
+.B \%KEY_BACKSPACE
+may be the same as
+.B \*^H
+.\" as with att505 or vt52-basic
+or
+.BR \*^? .
+.\" as with pccon+keys or vt320
+Consult the terminal's
+.I \%term\%info
+entry to determine whether this is the case;
+see \fB\%infocmp\fP(1).
+Some
+.I curses
+implementations,
+including
+.IR \%ncurses ,
+honor the
+.I \%term\%info
+key definitions;
+others treat such control characters specially.
.PP
-Generally, \fBKEY_ENTER\fP denotes the character(s) sent by the \fIEnter\fP
-key on the numeric keypad:
+.I curses
+distinguishes the Enter keys in the alphabetic and numeric keypad
+sections of a keyboard because (most) terminals do.
+.B \%KEY_ENTER
+refers to the key on the numeric keypad and,
+like other function keys,
+and is reliably recognized only if the window's keypad mode is enabled.
.bP
-the terminal description lists the most useful keys,
+The
+.I \%term\%info
+.B \%key_enter
+.RB ( kent )
+capability describes the character (sequence) sent by the Enter key of
+a terminal's numeric
+(or similar)
+keypad.
.bP
-the \fIEnter\fP key on the regular keyboard is already handled by
-the standard ASCII characters for carriage-return and line-feed,
+\*(``Enter or send\*('' is X/Open Curses's description of this key.
+.PP
+.I curses
+treats the Enter or Return key in the
+.I alphabetic
+section of the keyboard differently.
.bP
-depending on whether \fBnl\fP or \fBnonl\fP was called,
-pressing "Enter" on the regular keyboard may return either a carriage-return
-or line-feed, and finally
+It usually produces a control code for carriage return
+.RB ( \*^M )
+or line feed
+.RB ( \*^J ).
.bP
-"Enter or send" is the standard description for this key.
+Depending on the terminal mode
+(raw,
+cbreak,
+or
+\*(``cooked\*(''),
+and whether \fB\%nl\fP(3X) or \fB\%nonl\fP(3X) has been called,
+.B \%wgetch
+may return either a carriage return or line feed upon an Enter or Return
+key stroke.
.PP
-When using \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR, or
-\fBmvwgetch\fR, nocbreak mode (\fBnocbreak\fR) and echo mode
-(\fBecho\fR) should not be used at the same time.
-Depending on the
-state of the tty driver when each character is typed, the program may
-produce undesirable results.
+Use of
+.B \%wgetch
+with \fB\%echo\fP(3X) and neither \fB\%cbreak\fP(3X) nor \fB\%raw\fP(3X)
+is not well-defined.
.PP
-Note that \fBgetch\fR, \fBmvgetch\fR, and \fBmvwgetch\fR may be macros.
+Historically,
+the list of key code macros above was influenced by the
+function-key-rich keyboard of the AT&T 7300
+(also known variously as the \*(``3B1\*('', \*(``Safari 4\*('', and
+\*(``UNIX PC\*(''),
+a 1985 machine.
+Today's computer keyboards are based that of the IBM PC/AT and tend to
+have fewer.
+A
+.I curses
+application can expect such a keyboard to transmit key codes
+.BR \%KEY_UP ,
+.BR \%KEY_DOWN ,
+.BR \%KEY_LEFT ,
+.BR \%KEY_RIGHT ,
+.BR \%KEY_HOME ,
+.BR \%KEY_END ,
+.B \%KEY_PPAGE
+(Page Up),
+.B \%KEY_NPAGE
+(Page Down),
+.B \%KEY_IC
+(Insert),
+.B \%KEY_DC
+(Delete),
+and
+.BI \%KEY_F( n )
+for 1 \(<=
+.I n
+\(<= 12.
.PP
-Historically, the set of keypad macros was largely defined by the extremely
-function-key-rich keyboard of the AT&T 7300, aka 3B1, aka Safari 4.
-Modern
-personal computers usually have only a small subset of these.
-IBM PC-style
-consoles typically support little more than \fBKEY_UP\fR, \fBKEY_DOWN\fR,
-\fBKEY_LEFT\fR, \fBKEY_RIGHT\fR, \fBKEY_HOME\fR, \fBKEY_END\fR,
-\fBKEY_NPAGE\fR, \fBKEY_PPAGE\fR, and function keys 1 through 12.
-The Ins key
-is usually mapped to \fBKEY_IC\fR.
+.BR \%getch ,
+.BR \%mvgetch ,
+and
+.B \%mvwgetch
+may be implemented as macros.
+.SH EXTENSIONS
+In
+.IR \%ncurses ,
+when a window's \*(``no time-out\*('' mode is
+.I not
+set,
+the
+.B \%ESCDELAY
+variable configures the duration of the timer used to disambiguate a
+function key character sequence from a series of key strokes beginning
+with ESC typed by the user;
+see
+\fB\%curs_variables\fP(3X).
+.PP
+\fB\%has_key\fP was designed for \fB\%ncurses\fP(3X),
+and is not found in SVr4
+.IR curses ,
+4.4BSD
+.IR curses ,
+or any other previous curses implementation.
.SH PORTABILITY
-The *get* functions are described in the XSI Curses standard, Issue 4.
-They
-read single-byte characters only.
-The standard specifies that they return
-\fBERR\fR on failure, but specifies no error conditions.
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
.PP
-The echo behavior of these functions on input of \fBKEY_\fR or backspace
-characters was not specified in the SVr4 documentation.
-This description is
-adopted from the XSI Curses standard.
+X/Open Curses,
+Issue 4 describes
+\fB\%getch\fP,
+\fB\%wgetch\fP,
+\fB\%mvgetch\fP,
+\fB\%mvwgetch\fP,
+and
+\fB\%ungetch\fP.
+It specifies no error conditions for them.
.PP
-The behavior of \fBgetch\fR and friends in the presence of handled signals is
-unspecified in the SVr4 and XSI Curses documentation.
-Under historical curses
-implementations, it varied depending on whether the operating system's
-implementation of handled signal receipt interrupts a \fBread\fR(2) call in
-progress or not, and also (in some implementations) depending on whether an
-input timeout or non-blocking mode has been set.
+.B \%wgetch
+reads only single-byte characters.
.PP
-Programmers concerned about portability should be prepared for either of two
-cases: (a) signal receipt does not interrupt \fBgetch\fR; (b) signal receipt
-interrupts \fBgetch\fR and causes it to return ERR with \fBerrno\fR set to
-\fBEINTR\fR.
-Under the \fBncurses\fR implementation, handled signals never
-interrupt \fBgetch\fR.
+The echo behavior of these functions on input of
+.B KEY_
+or backspace characters was not specified in the SVr4 documentation.
+This description is adapted from X/Open Curses.
.PP
-The \fBhas_key\fR function is unique to \fBncurses\fR.
-We recommend that
-any code using it be conditionalized on the \fBNCURSES_VERSION\fR feature macro.
+The behavior of
+.B \%wgetch
+in the presence of signal handlers is unspecified in the SVr4
+documentation and X/Open Curses.
+In historical
+.I curses
+implementations,
+it varied depending on whether the operating system's dispatch of a
+signal to a handler interrupting a \fIread\fP(2) call in progress,
+and also
+(in some implementations)
+whether an input timeout or non-blocking mode has been set.
+Programmers concerned about portability should be prepared for either of
+two cases:
+(a) signal receipt does not interrupt
+.BR \%wgetch ;
+or
+(b) signal receipt interrupts
+.B \%wgetch
+and causes it to return
+.B ERR
+with
+.B \%errno
+set to
+.BR \%EINTR .
+.PP
+.B \%KEY_MOUSE
+is mentioned in X/Open Curses,
+along with a few related
+.I \%term\%info
+capabilities,
+but no higher-level functions use the feature.
+The implementation in
+.I \%ncurses
+is an extension.
+.PP
+.B \%KEY_RESIZE
+and
+.B \%has_key
+are extensions first implemented for
+.IR \%ncurses .
+By 2022,
+.I \%PDCurses
+.\" https://web.archive.org/web/20220117232009/https://pdcurses.org/docs/MANUAL.html
+and
+NetBSD
+.I curses
+.\" https://web.archive.org/web/20200923185647/https://man.netbsd.org/curses_input.3
+had added them along with
+.BR \%KEY_MOUSE .
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_inopts\fR(3X),
-\fBcurs_outopts\fR(3X),
-\fBcurs_mouse\fR(3X),
-\fBcurs_move\fR(3X),
-\fBcurs_refresh\fR(3X),
-\fBresizeterm\fR(3X).
+\fB\%curs_get_wch\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its wide-character configuration
+.RI ( \%ncursesw ).
.PP
-Comparable functions in the wide-character (ncursesw) library are
-described in
-\fBcurs_get_wch\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_addch\fP(3X),
+\fB\%curs_inopts\fP(3X),
+\fB\%curs_mouse\fP(3X),
+\fB\%curs_move\fP(3X),
+\fB\%curs_outopts\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_variables\fP(3X),
+\fB\%resizeterm\fP(3X),
+\fB\%ascii\fP(7)
+.PP
+ECMA-6 \*(``7-bit coded Character Set\*(''
+\%<https://\*:ecma\-international\*:.org/\
+\*:publications\-and\-standards/\*:standards/\*:ecma\-6/>
+.PP
+ECMA-48 \*(``Control Functions for Coded Character Sets\*(''
+\%<https://\*:ecma\-international\*:.org/\
+\*:publications\-and\-standards/\*:standards/\*:ecma\-48/>
diff --git a/man/curs_getstr.3x b/man/curs_getstr.3x
index e548cf1..4a49352 100644
--- a/man/curs_getstr.3x
+++ b/man/curs_getstr.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2005,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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 *
@@ -26,97 +27,275 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getstr.3x,v 1.19 2010/12/04 18:36:44 tom Exp $
-.TH curs_getstr 3X ""
-.na
-.hy 0
+.\" $Id: curs_getstr.3x,v 1.58 2024/04/20 19:18:18 tom Exp $
+.TH curs_getstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBgetstr\fR,
-\fBgetnstr\fR,
-\fBwgetstr\fR,
-\fBwgetnstr\fR,
-\fBmvgetstr\fR,
-\fBmvgetnstr\fR,
-\fBmvwgetstr\fR,
-\fBmvwgetnstr\fR \- accept character strings from \fBcurses\fR terminal keyboard
-.ad
-.hy
+\fB\%getstr\fP,
+\fB\%getnstr\fP,
+\fB\%wgetstr\fP,
+\fB\%wgetnstr\fP,
+\fB\%mvgetstr\fP,
+\fB\%mvgetnstr\fP,
+\fB\%mvwgetstr\fP,
+\fB\%mvwgetnstr\fP \-
+accept character strings from \fIcurses\fR terminal keyboard
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint getstr(char *str);\fR
-.br
-\fBint getnstr(char *str, int n);\fR
-.br
-\fBint wgetstr(WINDOW *win, char *str);\fR
-.br
-\fBint wgetnstr(WINDOW *win, char *str, int n);\fR
-.br
-\fBint mvgetstr(int y, int x, char *str);\fR
-.br
-\fBint mvwgetstr(WINDOW *win, int y, int x, char *str);\fR
-.br
-\fBint mvgetnstr(int y, int x, char *str, int n);\fR
-.br
-\fBint mvwgetnstr(WINDOW *, int y, int x, char *str, int n);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint getstr(char *\fIstr\fP);
+\fBint getnstr(char *\fIstr\fP, int \fIn\fP);
+\fBint wgetstr(WINDOW *\fIwin\fP, char *\fIstr\fP);
+\fBint wgetnstr(WINDOW *\fIwin\fP, char *\fIstr\fP, int \fIn\fP);
+.PP
+\fBint mvgetstr(int \fIy\fP, int \fIx\fP, char *\fIstr\fP);
+\fBint mvwgetstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, char *\fIstr\fP);
+\fBint mvgetnstr(int \fIy\fP, int \fIx\fP, char *\fIstr\fP, int \fIn\fP);
+\fBint mvwgetnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, char *\fIstr\fP, int \fIn\fP);
+.fi
.SH DESCRIPTION
-The function \fBgetstr\fR is equivalent to a series of calls to \fBgetch\fR,
-until a newline or carriage return is received (the terminating character is
-not included in the returned string). The resulting value is placed in the
-area pointed to by the character pointer \fIstr\fR.
+The function
+\fBwgetnstr\fP
+is equivalent to a series of calls to
+\fBwgetch\fP(3X),
+until a newline or carriage return terminates the series:
+.bP
+The terminating character is not included in the returned string.
+.bP
+In all instances, the end of the string is terminated
+by a NUL.
+.bP
+The function stores the result in the area pointed to
+by the \fIstr\fP parameter.
+.bP
+The function reads at most \fIn\fP characters,
+thus preventing a possible overflow of the input buffer.
+.IP
+Any attempt to enter more characters
+(other than the terminating newline or carriage return)
+causes a beep.
+.IP
+Function keys also cause a beep and are ignored.
.PP
-\fBwgetnstr\fR reads at most \fIn\fR characters, thus preventing a possible
-overflow of the input buffer. Any attempt to enter more characters (other
-than the terminating newline or carriage return) causes a beep. Function
-keys also cause a beep and are ignored. The \fBgetnstr\fR function reads
-from the \fIstdscr\fR default window.
+The user's \fIerase\fP and \fIkill\fP characters are interpreted:
+.bP
+The \fIerase\fP character (e.g., \fB^H\fP) erases the character
+at the end of the buffer, moving the cursor to the left.
+.IP
+If \fIkeypad\fP mode is on for the window,
+\fBKEY_LEFT\fP and \fBKEY_BACKSPACE\fP
+are both considered equivalent to the user's \fIerase\fP character.
+.bP
+The \fIkill\fP character (e.g., \fB^U\fP) erases the entire buffer,
+leaving the cursor at the beginning of the buffer.
.PP
-The user's erase and kill characters are interpreted. If keypad
-mode is on for the window, \fBKEY_LEFT\fR and \fBKEY_BACKSPACE\fR
-are both considered equivalent to the user's kill character.
+Characters input are echoed only if \fBecho\fP is currently on.
+In that case,
+backspace is echoed as deletion of the previous character
+(typically a left motion).
.PP
-Characters input are echoed only if \fBecho\fR is currently on. In that case,
-backspace is echoed as deletion of the previous character (typically a left
-motion).
+The
+\fBgetnstr\fP,
+\fBmvgetnstr\fP,
+\fBmvwgetnstr\fP, and
+\fBwgetnstr\fP
+functions are identical
+to the
+\fBgetstr\fP,
+\fBmvgetstr\fP,
+\fBmvwgetstr\fP, and
+\fBwgetstr\fP
+functions, respectively,
+except that the
+\fB*n*\fP
+versions read at most
+\fIn\fP
+characters, letting the application prevent overflow of the
+input buffer.
.SH RETURN VALUE
-All routines return the integer \fBERR\fR upon failure and an \fBOK\fR (SVr4
-specifies only "an integer value other than \fBERR\fR") upon successful
-completion.
+All of these functions return the integer \fBOK\fP upon successful completion.
+(SVr4 specifies only \*(``an integer value other than \fBERR\fP\*('')
+If unsuccessful, they return \fBERR\fP.
.PP
X/Open defines no error conditions.
.PP
In this implementation,
these functions return an error
-if the window pointer is null, or
-if its timeout expires without having any data.
+.bP
+if the window pointer is null,
+.bP
+if its timeout expires without having any data, or
+.bP
+if the associated call to
+\fBwgetch\fP
+failed.
.PP
This implementation provides an extension as well.
-If a SIGWINCH interrupts the function, it will return \fBKEY_RESIZE\fP
+If a \fBSIGWINCH\fP interrupts the function, it will return \fBKEY_RESIZE\fP
rather than \fBOK\fP or \fBERR\fP.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
-Note that \fBgetstr\fR, \fBmvgetstr\fR, and \fBmvwgetstr\fR may be macros.
+Any of these functions other than
+\fBwgetnstr\fP
+may be macros.
+.PP
+Using
+\fBgetstr\fP,
+\fBmvgetstr\fP,
+\fBmvwgetstr\fP, or
+\fBwgetstr\fP
+to read a line that
+overflows the array pointed to by
+\fBstr\fP
+causes undefined
+results.
+The use of
+\fBgetnstr\fP,
+\fBmvgetnstr\fP,
+\fBmvwgetnstr\fP, or
+\fBwgetnstr\fP,
+respectively, is recommended.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
-They read single-byte characters only.
-The standard does not define any error conditions.
-This implementation returns ERR if the window pointer is null,
-or if the lower-level \fBwgetch\fR call returns an ERR.
+These functions are described in The Single Unix Specification, Version 2.
+No error conditions are defined.
+.PP
+This implementation returns \fBERR\fP if the window pointer is null,
+or if the lower-level \fBwgetch\fP(3X) call returns an \fBERR\fP.
.PP
SVr3 and early SVr4 curses implementations did not reject function keys;
-the SVr4.0 documentation claimed that "special keys" (such as function
-keys, "home" key, "clear" key, \fIetc\fR.) are "interpreted", without
-giving details. It lied. In fact, the `character' value appended to the
+the SVr4.0 documentation claimed that \*(``special keys\*(''
+(such as function keys,
+\*(``home\*('' key,
+\*(``clear\*('' key,
+\fIetc\fP.) are \*(``interpreted\*('',
+without giving details.
+It lied.
+In fact, the \*(``character\*('' value appended to the
string by those implementations was predictable but not useful
(being, in fact, the low-order eight bits of the key's KEY_ value).
.PP
-The functions \fBgetnstr\fR, \fBmvgetnstr\fR, and \fBmvwgetnstr\fR were
+The functions \fBgetnstr\fP, \fBmvgetnstr\fP, and \fBmvwgetnstr\fP were
present but not documented in SVr4.
+.PP
+X/Open Curses, Issue 5 (2007) stated that these functions
+\*(``read at most \fIn\fP bytes\*(''
+but did not state whether the terminating NUL is counted in that limit.
+X/Open Curses, Issue 7 (2009) changed that to say they
+\*(``read at most \fIn\fP\-1 bytes\*(''
+to allow for the terminating NUL.
+As of 2018, some implementations count it, some do not:
+.bP
+\fI\%ncurses\fP 6.1 and PDCurses do not count the NUL in the given limit, while
+.bP
+Solaris SVr4 and NetBSD curses count the NUL as part of the limit.
+.bP
+Solaris xcurses provides both:
+its wide-character \fBwget_nstr\fP reserves a NUL,
+but its \fBwgetnstr\fP does not count the NUL consistently.
+.PP
+In SVr4 curses,
+a negative value of \fIn\fP tells \fBwgetnstr\fP to assume that the
+caller's buffer is large enough to hold the result,
+i.e., to act like \fBwgetstr\fP.
+X/Open Curses does not mention this
+(or anything related to negative or zero values of \fIn\fP),
+however most implementations
+use the feature, with different limits:
+.bP
+Solaris SVr4 curses and PDCurses limit the result to 255 bytes.
+Other Unix systems than Solaris are likely to use the same limit.
+.bP
+Solaris xcurses limits the result to \fBLINE_MAX\fP bytes.
+.bP
+NetBSD 7 assumes no particular limit for the result from \fBwgetstr\fP.
+However, it limits the \fBwgetnstr\fP parameter \fIn\fP to ensure
+that it is greater than zero.
+.IP
+A comment in NetBSD's source code states that this is specified in SUSv2.
+.bP
+\fI\%ncurses\fP (before 6.2) assumes no particular limit for the result
+from \fBwgetstr\fP, and treats the \fIn\fP parameter of \fBwgetnstr\fP
+like SVr4 curses.
+.bP
+\fI\%ncurses\fP 6.2 uses \fBLINE_MAX\fP,
+or a larger (system-dependent) value
+which the \fBsysconf\fP function may provide.
+If neither \fBLINE_MAX\fP or \fBsysconf\fP is available,
+\fI\%ncurses\fP uses the POSIX value for \fBLINE_MAX\fP (a 2048 byte limit).
+In either case, it reserves a byte for the terminating NUL.
+.PP
+Although \fBgetnstr\fP is equivalent to a series of calls to \fBgetch\fP,
+it also makes changes to the curses modes to allow simple editing of
+the input buffer:
+.bP
+\fBgetnstr\fP saves the current value of the \fBnl\fP, \fBecho\fP,
+\fBraw\fP and \fBcbreak\fP modes, and sets
+\fBnl\fP,
+\fBnoecho\fP,
+\fBnoraw\fP, and
+\fBcbreak\fP.
+.IP
+\fBgetnstr\fP handles the echoing of characters,
+rather than relying on the caller to set an appropriate mode.
+.bP
+It also obtains the \fIerase\fP and \fIkill\fP characters
+from \fBerasechar\fP and \fBkillchar\fP, respectively.
+.bP
+On return, \fBgetnstr\fP restores the modes to their previous values.
+.PP
+Other implementations differ in their treatment of special characters:
+.bP
+While they may set the \fIecho\fP mode,
+other implementations do not modify the \fIraw\fP mode,
+They may take the \fIcbreak\fP
+mode set by the caller into account when deciding whether to handle
+echoing within \fBgetnstr\fP or as a side-effect of the \fBgetch\fP calls.
+.bP
+The original \fI\%ncurses\fP
+(as \fIpcurses\fP in 1986)
+set \fBnoraw\fP and \fBcbreak\fP when accepting input for \fBgetnstr\fP.
+That may have been done to make function- and cursor-keys work;
+it is not necessary with \fI\%ncurses\fP.
+.IP
+Since 1995,
+\fI\%ncurses\fP has provided signal handlers for INTR and QUIT
+(e.g., \fB^C\fP or \fB^\e\fP).
+With the \fBnoraw\fP and \fBcbreak\fP settings,
+those may catch a signal and stop the program,
+where other implementations allow one to enter those characters in the buffer.
+.bP
+Starting in 2021
+(\fI\%ncurses\fP 6.3),
+\fBgetnstr\fP sets \fBraw\fP,
+rather than \fBnoraw\fP and \fBcbreak\fP for better compatibility with
+SVr4-curses, e.g., allowing one to enter a \fB^C\fP into the buffer.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_getch\fR(3X),
-\fBcurs_variables\fR(3X).
+\fB\%curs_get_wstr\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its wide-character configuration
+.RI ( \%ncursesw ).
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_getch\fP(3X),
+\fB\%curs_termattrs\fP(3X),
+\fB\%curs_variables\fP(3X)
diff --git a/man/curs_getyx.3x b/man/curs_getyx.3x
index 980968e..eadcece 100644
--- a/man/curs_getyx.3x
+++ b/man/curs_getyx.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright 2020-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2007,2010 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 *
@@ -26,75 +27,87 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getyx.3x,v 1.18 2010/12/04 18:36:44 tom Exp $
-.TH curs_getyx 3X ""
+.\" $Id: curs_getyx.3x,v 1.44 2024/04/20 21:20:07 tom Exp $
+.TH curs_getyx 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.SH NAME
-\fBgetyx\fR,
-\fBgetparyx\fR,
-\fBgetbegyx\fR,
-\fBgetmaxyx\fR \- get \fBcurses\fR cursor and window coordinates
+\fB\%getyx\fP,
+\fB\%getparyx\fP,
+\fB\%getbegyx\fP,
+\fB\%getmaxyx\fP \-
+get \fIcurses\fR cursor and window coordinates
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBvoid getyx(WINDOW *win, int y, int x);\fR
-.br
-\fBvoid getparyx(WINDOW *win, int y, int x);\fR
-.br
-\fBvoid getbegyx(WINDOW *win, int y, int x);\fR
-.br
-\fBvoid getmaxyx(WINDOW *win, int y, int x);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBvoid getyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
+\fBvoid getparyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
+\fBvoid getbegyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
+\fBvoid getmaxyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
+.fi
.SH DESCRIPTION
-The \fBgetyx\fR macro places the current cursor position of the given window in
-the two integer variables \fIy\fR and \fIx\fR.
+The \fB\%getyx\fP macro places the current cursor position
+of the given window in the two integer variables \fIy\fP and \fIx\fP.
.PP
-If \fIwin\fR is a subwindow, the \fBgetparyx\fR macro places the beginning
+If \fIwin\fP is a subwindow, the \fB\%getparyx\fP macro places the beginning
coordinates of the subwindow relative to the parent window into two integer
-variables \fIy\fR and \fIx\fR.
-Otherwise, \fB\-1\fR is placed into \fIy\fR and \fIx\fR.
+variables \fIy\fP and \fIx\fP.
+Otherwise, \fB\-1\fP is placed into \fIy\fP and \fIx\fP.
.PP
-Like \fBgetyx\fR, the \fBgetbegyx\fR and \fBgetmaxyx\fR macros store
+Like \fB\%getyx\fP, the \fB\%getbegyx\fP and \fB\%getmaxyx\fP macros store
the current beginning coordinates and size of the specified window.
.SH RETURN VALUE
The return values of these macros are undefined (i.e.,
they should not be used as the right-hand side of assignment statements).
.SH NOTES
All of these interfaces are macros.
-A "\fB&\fR" is not necessary before the variables \fIy\fR and \fIx\fR.
+A \*(``&\*('' is not necessary before the variables \fIy\fP and \fIx\fP.
.SH PORTABILITY
The
-\fBgetyx\fR,
-\fBgetparyx\fR,
-\fBgetbegyx\fR and
-\fBgetmaxyx\fR
-macros are described in the XSI Curses standard, Issue 4.
+\fB\%getyx\fP,
+\fB\%getparyx\fP,
+\fB\%getbegyx\fP and
+\fB\%getmaxyx\fP
+macros are described in X/Open Curses, Issue 4.
.PP
This implementation also provides functions
-\fBgetbegx\fR,
-\fBgetbegy\fR,
-\fBgetcurx\fR,
-\fBgetcury\fR,
-\fBgetmaxx\fR,
-\fBgetmaxy\fR,
-\fBgetparx\fR and
-\fBgetpary\fR
-for compatibility with older versions of curses.
+\fB\%getbegx\fP,
+\fB\%getbegy\fP,
+\fB\%getcurx\fP,
+\fB\%getcury\fP,
+\fB\%getmaxx\fP,
+\fB\%getmaxy\fP,
+\fB\%getparx\fP and
+\fB\%getpary\fP
+for compatibility with older versions of \fIcurses\fP;
+see \fB\%curs_legacy\fP(3X).
.PP
Although X/Open Curses does not address this,
-many implementations provide members of the WINDOW structure
+many implementations provide members of the \fB\%WINDOW\fP structure
containing values corresponding to these macros.
-For best portability, do not rely on using the data in WINDOW,
-since some implementations make WINDOW opaque (do not allow
+For best portability, do not rely on using the data in \fB\%WINDOW\fP,
+since some implementations make \fB\%WINDOW\fP opaque (do not allow
direct use of its members).
.PP
Besides the problem of opaque structures,
the data stored in like-named members may not have like-values in
different implementations.
-For example, the WINDOW._maxx and WINDOW._maxy values in ncurses
-have (at least since release 1.8.1) differed by one from some
-other implementations.
-The difference is hidden by means of the macro \fBgetmaxyx\fP.
+For example, the \fB\%WINDOW._maxx\fP and \fB\%WINDOW._maxy\fP values
+in \fI\%ncurses\fP have
+(at least since release 1.8.1)
+differed by one from some other implementations.
+The difference is hidden by means of the macro \fB\%getmaxyx\fP.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_legacy\fR(3X),
-\fBcurs_opaque\fR(3X)
+\fB\%curses\fP(3X),
+\fB\%curs_legacy\fP(3X),
+\fB\%curs_opaque\fP(3X)
diff --git a/man/curs_in_wch.3x b/man/curs_in_wch.3x
index 5f50e5a..8512e6d 100644
--- a/man/curs_in_wch.3x
+++ b/man/curs_in_wch.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 2002-2010,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 *
@@ -26,41 +27,58 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_in_wch.3x,v 1.5 2010/12/04 18:36:44 tom Exp $
-.TH curs_in_wch 3X ""
+.\" $Id: curs_in_wch.3x,v 1.31 2024/04/20 21:20:07 tom Exp $
+.TH curs_in_wch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-\fBin_wch\fR,
-\fBmvin_wch\fR,
-\fBmvwin_wch\fR,
-\fBwin_wch\fR \- extract a complex character and rendition from a window
+\fB\%in_wch\fP,
+\fB\%mvin_wch\fP,
+\fB\%mvwin_wch\fP,
+\fB\%win_wch\fP \-
+get a \fIcurses\fR complex character from a window
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint in_wch(cchar_t *\fR\fIwcval\fR\fB);\fR
-.br
-\fBint mvin_wch(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwcval\fR\fB);\fR
-.br
-\fBint mvwin_wch(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwcval\fR\fB);\fR
-.br
-\fBint win_wch(WINDOW *\fR\fIwin\fR\fB, cchar_t *\fR\fIwcval\fR\fB);\fR
+.nf
+\fB#include <curses.h>
+.PP
+\fBint in_wch(cchar_t *\fIwch\fP);
+\fBint win_wch(WINDOW *\fIwin\fP, cchar_t *\fIwch\fP);
+.PP
+\fBint mvin_wch(int \fIy\fP, int \fIx\fP, cchar_t *\fIwch\fP);
+\fBint mvwin_wch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, cchar_t *\fIwch\fP);
+.fi
.SH DESCRIPTION
These functions extract the complex character and rendition from
-the current position in the named window into the \fBcchar_t\fR object
-referenced by wcval.
+the current position in the named window into the \fBcchar_t\fP object
+referenced by wch.
.SH RETURN VALUE
-No errors are defined in the XSI Curses standard.
-This implementation checks for null pointers, returns ERR in that case.
-Also, the \fImv\fR routines check for error moving the cursor, returning ERR
-in that case.
-Otherwise they return OK
+No errors are defined in X/Open Curses.
+This implementation checks for null pointers, returns \fBERR\fP in that case.
+Also, the \fImv\fP routines check for error moving the cursor,
+returning \fBERR\fP in that case.
+Otherwise they return \fBOK\fP.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
Note that all of these routines may be macros.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
+These functions are described in X/Open Curses, Issue 4.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_inch\fR(3X).
+\fB\%curs_inch\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its non-wide-character configuration.
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_inwstr\fP(3X)
diff --git a/man/curs_in_wchstr.3x b/man/curs_in_wchstr.3x
index f929687..53c9846 100644
--- a/man/curs_in_wchstr.3x
+++ b/man/curs_in_wchstr.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 2002-2012,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 *
@@ -26,95 +27,106 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_in_wchstr.3x,v 1.9 2012/11/03 23:03:59 tom Exp $
-.TH curs_in_wchstr 3X ""
-.na
-.hy 0
+.\" $Id: curs_in_wchstr.3x,v 1.39 2024/04/20 21:24:19 tom Exp $
+.TH curs_in_wchstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBin_wchstr\fR,
-\fBin_wchnstr\fR,
-\fBwin_wchstr\fR,
-\fBwin_wchnstr\fR,
-\fBmvin_wchstr\fR,
-\fBmvin_wchnstr\fR,
-\fBmvwin_wchstr\fR,
-\fBmvwin_wchnstr\fR \- get an array of complex characters and renditions from a curses window
-.ad
-.hy
+\fB\%in_wchstr\fP,
+\fB\%in_wchnstr\fP,
+\fB\%win_wchstr\fP,
+\fB\%win_wchnstr\fP,
+\fB\%mvin_wchstr\fP,
+\fB\%mvin_wchnstr\fP,
+\fB\%mvwin_wchstr\fP,
+\fB\%mvwin_wchnstr\fP \-
+get a \fIcurses\fR complex character string from a window
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fR
-.sp
-\fBint in_wchstr(cchar_t *\fR\fIwchstr\fR\fB);\fR
-.br
-\fBint in_wchnstr(cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint win_wchstr(WINDOW *\fR\fIwin\fR\fB, cchar_t *\fR\fIwchstr\fR\fB);\fR
-.br
-\fBint win_wchnstr(WINDOW *\fR\fIwin\fR\fB, cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint mvin_wchstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwchstr\fR\fB);\fR
-.br
-\fBint mvin_wchnstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint mvwin_wchstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwchstr\fR\fB);\fR
-.br
-\fBint mvwin_wchnstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwchstr\fR, int \fIn\fR\fB);\fR
+\fB#include <curses.h>
+.PP
+\fBint in_wchstr(cchar_t *\fIwchstr\fP);
+\fBint win_wchstr(WINDOW *\fIwin\fP, cchar_t *\fIwchstr\fP);
+\fBint mvin_wchstr(int \fIy\fP, int \fIx\fP, cchar_t *\fIwchstr\fP);
+\fBint mvwin_wchstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, cchar_t *\fIwchstr\fP);
+.PP
+\fBint in_wchnstr(cchar_t *\fIwchstr\fP, int \fIn\fP);
+\fBint win_wchnstr(WINDOW *\fIwin\fP, cchar_t *\fIwchstr\fP, int \fIn\fP);
+\fBint mvin_wchnstr(int \fIy\fP, int \fIx\fP, cchar_t *\fIwchstr\fP, int \fIn\fP);
+\fBint mvwin_wchnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, cchar_t *\fIwchstr\fP, int \fIn\fP);
.fi
.SH DESCRIPTION
-These functions return an array of complex characters in \fIwchstr\fR,
+These functions return an array of complex characters in \fIwchstr\fP,
starting at the current cursor position in the named window.
Attributes (rendition) are stored with the characters.
.PP
-The
-\fBin_wchnstr\fR,
-\fBmvin_wchnstr\fR,
-\fBmvwin_wchnstr\fR
-and
-\fBwin_wchnstr\fR
-fill the array
-with at most
-\fIn\fR
-\fBcchar_t\fR
-elements.
-.br
-.SH NOTES
-Note that all routines except
-\fBwin_wchnstr\fR
-may be
-macros.
+The four functions with \fIn\fP as the last argument return
+a leading substring at most \fIn\fP characters long
+(exclusive of the trailing zeroed \fBcchar_t\fR.
+Transfer stops at the end of the current line, or when \fIn\fP characters have
+been stored at the location referenced by \fIwchstr\fP.
.PP
-Reading a line that overflows the array pointed to by
-\fIwchstr\fR
-with
-\fBin_wchstr\fR,
-\fBmvin_wchstr\fR,
-\fBmvwin_wchstr\fR
-or
-\fBwin_wchstr\fR
-causes undefined results. Therefore, the use of
-\fBin_wchnstr\fR,
-\fBmvin_wchnstr\fR,
-\fBmvwin_wchnstr\fR, or
-\fBwin_wchnstr\fR
-is recommended.
+Constants defined in \fB<curses.h>\fP can be used with the \fB&\fP (logical
+AND) operator to extract the character or the attribute alone from any position
+in the \fIwchstr\fP [see \fBgetcchar\fP(3X)].
.SH RETURN VALUE
Upon successful completion, these functions return
-\fBOK\fR.
+\fBOK\fP.
Otherwise, they return
-\fBERR\fR.
+\fBERR\fP.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+X/Open Curses defines no error conditions.
+This implementation returns an error
+.bP
+if the \fIwin\fP parameter is null or
+.bP
+if the \fIwchstr\fP parameter is null.
+.PP
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
+.SH NOTES
+All routines except \fBwin_wchnstr\fP may be macros.
+.PP
+Reading a line that overflows the array pointed to by
+\fIwchstr\fP
+with
+\fBin_wchstr\fP,
+\fBmvin_wchstr\fP,
+\fBmvwin_wchstr\fP
+or
+\fBwin_wchstr\fP
+causes undefined results.
+Therefore, the use of
+\fBin_wchnstr\fP,
+\fBmvin_wchnstr\fP,
+\fBmvwin_wchnstr\fP, or
+\fBwin_wchnstr\fP
+is recommended.
.SH PORTABILITY
-The XSI Curses defines no error conditions.
+X/Open Curses defines no error conditions.
This implementation checks for null pointers,
-returning ERR in that case.
+returning \fBERR\fP in that case.
.SH SEE ALSO
-Functions:
-\fBcurses\fR(3X),
-\fBcurs_in_wch\fR(3X),
-\fBcurs_instr\fR(3X),
-\fBcurs_inwstr\fR(3X)
-\fBcurs_inchstr\fR(3X)
+\fB\%curs_inchstr\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its non-wide-character configuration.
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_inwstr\fP(3X),
+\fB\%curs_in_wch\fP(3X)
diff --git a/man/curs_inch.3x b/man/curs_inch.3x
index 7e1e3b4..962e9dc 100644
--- a/man/curs_inch.3x
+++ b/man/curs_inch.3x
@@ -1,6 +1,7 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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 *
@@ -27,51 +28,101 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inch.3x,v 1.17 2010/12/04 18:36:44 tom Exp $
-.TH curs_inch 3X ""
+.\" $Id: curs_inch.3x,v 1.51 2024/04/20 21:20:07 tom Exp $
+.TH curs_inch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBinch\fR,
-\fBwinch\fR,
-\fBmvinch\fR,
-\fBmvwinch\fR \- get a character and attributes from a \fBcurses\fR window
+\fB\%inch\fP,
+\fB\%winch\fP,
+\fB\%mvinch\fP,
+\fB\%mvwinch\fP \-
+get a \fIcurses\fR character from a window
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBchtype inch(void);\fR
-.br
-\fBchtype winch(WINDOW *win);\fR
-.br
-\fBchtype mvinch(int y, int x);\fR
-.br
-\fBchtype mvwinch(WINDOW *win, int y, int x);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBchtype inch(void);
+\fBchtype winch(WINDOW *\fIwin\fP);
+.PP
+\fBchtype mvinch(int \fIy\fP, int \fIx\fP);
+\fBchtype mvwinch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
+.fi
.SH DESCRIPTION
-These routines return the character, of type \fBchtype\fR, at the current
-position in the named window. If any attributes are set for that position,
-their values are OR'ed into the value returned. Constants defined in
-\fB<curses.h>\fR can be used with the \fB&\fR (logical AND) operator to
+These routines return the character, of type \fBchtype\fP, at the current
+position in the named window.
+If any attributes are set for that position,
+their values are OR'ed into the value returned.
+Constants defined in
+\fB<curses.h>\fP can be used with the \fB&\fP (logical AND) operator to
extract the character or attributes alone.
.
.SS Attributes
-The following bit-masks may be AND-ed with characters returned by \fBwinch\fR.
-.
+The following bit masks may be AND-ed with characters returned by \fBwinch\fP.
+.PP
.TS
-l l .
-\fBA_CHARTEXT\fR Bit-mask to extract character
-\fBA_ATTRIBUTES\fR Bit-mask to extract attributes
-\fBA_COLOR\fR Bit-mask to extract color-pair field information
+Lb Lb
+Lb Lx.
+Name Description
+_
+A_CHARTEXT Extract character
+A_ATTRIBUTES Extract attributes
+A_COLOR Extract color pair information
.TE
.SH RETURN VALUE
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
+.PP
+The \fBwinch\fP function does not return an error if the window contains
+characters larger than 8-bits (255).
+Only the low-order 8 bits of the character are used by \fBwinch\fP.
.SH NOTES
Note that all of these routines may be macros.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
-.SH SEE ALSO
-\fBcurses\fR(3X).
+These functions are described in X/Open Curses, Issue 4.
.PP
-Comparable functions in the wide-character (ncursesw) library are
-described in
-\fBcurs_in_wch\fR(3X).
+Very old systems (before standardization) provide a different function
+with the same name:
+.bP
+The \fBwinch\fP function was part of the original BSD curses library,
+which stored a 7-bit character combined with the \fIstandout\fP attribute.
+.IP
+In BSD curses, \fBwinch\fP returned only the character (as an integer)
+with the \fIstandout\fP attribute removed.
+.bP
+System V curses added support for several video attributes which
+could be combined with characters in the window.
+.IP
+Reflecting this improvement, the function was altered to return the
+character combined with all video attributes in a \fBchtype\fP value.
+.PP
+X/Open Curses does not specify
+the size and layout of attributes, color and character values in
+\fBchtype\fP; it is implementation-dependent.
+This implementation uses 8 bits for character values.
+An application using more bits, e.g., a Unicode value,
+should use the wide-character equivalents to these functions.
+.SH SEE ALSO
+\fB\%curs_in_wch\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its wide-character configuration
+.RI ( \%ncursesw ).
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_instr\fP(3X)
diff --git a/man/curs_inchstr.3x b/man/curs_inchstr.3x
index 2dc7673..bcd5d68 100644
--- a/man/curs_inchstr.3x
+++ b/man/curs_inchstr.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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 *
@@ -26,74 +27,109 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inchstr.3x,v 1.15 2010/12/04 18:36:44 tom Exp $
-.TH curs_inchstr 3X ""
-.na
-.hy 0
+.\" $Id: curs_inchstr.3x,v 1.45 2024/04/20 21:20:07 tom Exp $
+.TH curs_inchstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBinchstr\fR,
-\fBinchnstr\fR,
-\fBwinchstr\fR,
-\fBwinchnstr\fR,
-\fBmvinchstr\fR,
-\fBmvinchnstr\fR,
-\fBmvwinchstr\fR,
-\fBmvwinchnstr\fR \- get a string of characters (and attributes) from a \fBcurses\fR window
-.ad
-.hy
+\fB\%inchstr\fP,
+\fB\%inchnstr\fP,
+\fB\%winchstr\fP,
+\fB\%winchnstr\fP,
+\fB\%mvinchstr\fP,
+\fB\%mvinchnstr\fP,
+\fB\%mvwinchstr\fP,
+\fB\%mvwinchnstr\fP \-
+get a \fIcurses\fR character string from a window
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint inchstr(chtype *chstr);\fR
-.br
-\fBint inchnstr(chtype *chstr, int n);\fR
-.br
-\fBint winchstr(WINDOW *win, chtype *chstr);\fR
-.br
-\fBint winchnstr(WINDOW *win, chtype *chstr, int n);\fR
-.br
-\fBint mvinchstr(int y, int x, chtype *chstr);\fR
-.br
-\fBint mvinchnstr(int y, int x, chtype *chstr, int n);\fR
-.br
-\fBint mvwinchstr(WINDOW *win, int y, int x, chtype *chstr);\fR
-.br
-\fBint mvwinchnstr(WINDOW *win, int y, int x, chtype *chstr, int n);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint inchstr(chtype *\fIchstr\fP);
+\fBint inchnstr(chtype *\fIchstr\fP, int \fIn\fP);
+\fBint winchstr(WINDOW *\fIwin\fP, chtype *\fIchstr\fP);
+\fBint winchnstr(WINDOW *\fIwin\fP, chtype *\fIchstr\fP, int \fIn\fP);
+.PP
+\fBint mvinchstr(int \fIy\fP, int \fIx\fP, chtype *\fIchstr\fP);
+\fBint mvinchnstr(int \fIy\fP, int \fIx\fP, chtype *\fIchstr\fP, int \fIn\fP);
+\fBint mvwinchstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, chtype *\fIchstr\fP);
+\fBint mvwinchnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, chtype *\fIchstr\fP, int \fIn\fP);
+.fi
.SH DESCRIPTION
-These routines return a NULL-terminated array of \fBchtype\fR quantities,
+These routines return a NULL-terminated array of \fBchtype\fP quantities,
starting at the current cursor position in the named window and ending at the
-right margin of the window. The four functions with \fIn\fR as
-the last argument, return a leading substring at most \fIn\fR characters long
+right margin of the window.
+.PP
+The four functions with \fIn\fP as the last argument, return
+a leading substring at most \fIn\fP characters long
(exclusive of the trailing (chtype)0).
-Constants defined in \fB<curses.h>\fR can be used with the \fB&\fR (logical
+Transfer stops at the end of the current line, or when \fIn\fP characters have
+been stored at the location referenced by \fIchstr\fP.
+.PP
+Constants defined in \fB<curses.h>\fP can be used with the \fB&\fP (logical
AND) operator to extract the character or the attribute alone from any position
-in the \fIchstr\fR [see \fBcurs_inch\fR(3X)].
+in the \fIchstr\fP [see \fBcurs_inch\fP(3X)].
.SH RETURN VALUE
-All routines return the integer \fBERR\fR upon failure and an integer value
-other than \fBERR\fR upon successful completion (the number of characters
+All routines return the integer \fBERR\fP upon failure and an integer value
+other than \fBERR\fP upon successful completion (the number of characters
retrieved, exclusive of the trailing 0).
.PP
-No error conditions are defined.
-If the \fIchstr\fP parameter is null,
-no data is returned,
-and the return value is zero.
+X/Open Curses defines no error conditions.
+This implementation returns an error
+.bP
+if the \fIwin\fP parameter is null or
+.bP
+if the \fIchstr\fP parameter is null.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
-Note that all routines except \fBwinchnstr\fR may be macros. SVr4 does not
+All routines except \fBwinchnstr\fP may be macros.
+.PP
+SVr4 does not
document whether the result string is zero-terminated; it does not document
whether a length limit argument includes any trailing 0; and it does not
document the meaning of the return value.
-.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4. It is no
-more specific than the SVr4 documentation on the trailing 0. It does specify
-that the successful return of the functions is \fBOK\fR.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_inch\fR(3X).
.PP
-Comparable functions in the wide-character (ncursesw) library are
-described in
-\fBcurs_in_wchstr\fR(3X).
+Reading a line that overflows the array pointed to by
+\fIchstr\fP
+with
+\fBinchstr\fP,
+\fBmvinchstr\fP,
+\fBmvwinchstr\fP
+or
+\fBwinchstr\fP
+causes undefined results.
+Therefore, the use of
+\fBinchnstr\fP,
+\fBmvinchnstr\fP,
+\fBmvwinchnstr\fP, or
+\fBwinchnstr\fP
+is recommended.
+.SH PORTABILITY
+These functions are described in X/Open Curses, Issue 4.
+It is no
+more specific than the SVr4 documentation on the trailing 0.
+It does specify
+that the successful return of the functions is \fBOK\fP.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%curs_inch\fP(3X),
+\fB\%curs_inwstr\fP(3X),
+\fB\%curs_in_wchstr\fP(3X)
diff --git a/man/curs_initscr.3x b/man/curs_initscr.3x
index dc15ecb..0f460af 100644
--- a/man/curs_initscr.3x
+++ b/man/curs_initscr.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2014,2015 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -26,126 +27,143 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_initscr.3x,v 1.24 2015/07/21 23:01:38 tom Exp $
-.TH curs_initscr 3X ""
+.\" $Id: curs_initscr.3x,v 1.69 2024/04/20 21:24:19 tom Exp $
+.TH curs_initscr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
-.na
-.hy 0
.SH NAME
-\fBinitscr\fR,
-\fBnewterm\fR,
-\fBendwin\fR,
-\fBisendwin\fR,
-\fBset_term\fR,
-\fBdelscreen\fR \- \fBcurses\fR screen initialization and manipulation routines
-.ad
-.hy
+\fB\%initscr\fP,
+\fB\%newterm\fP,
+\fB\%endwin\fP,
+\fB\%isendwin\fP,
+\fB\%set_term\fP,
+\fB\%delscreen\fP \-
+initialize, manipulate, or tear down \fIcurses\fR terminal interface
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBWINDOW *initscr(void);\fR
-.br
-\fBint endwin(void);\fR
-.br
-\fBbool isendwin(void);\fR
-.br
-\fBSCREEN *newterm(char *\fP\fItype\fP\fB, FILE *\fP\fIoutfd\fP\fB, FILE *\fP\fIinfd\fP\fB);\fR
-.br
-\fBSCREEN *set_term(SCREEN *\fP\fInew\fP\fB);\fR
-.br
-\fBvoid delscreen(SCREEN* \fP\fIsp\fP\fB);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBWINDOW *initscr(void);
+\fBint endwin(void);
+.PP
+\fBbool isendwin(void);
+.PP
+\fBSCREEN *newterm(const char *\fItype\fP, FILE *\fIoutf\fP, FILE *\fIinf\fP);
+\fBSCREEN *set_term(SCREEN *\fInew\fP);
+\fBvoid delscreen(SCREEN* \fIsp\fP);
+.fi
.SH DESCRIPTION
.SS initscr
-\fBinitscr\fR is normally the first \fBcurses\fR routine to call when
+\fBinitscr\fP is normally the first \fBcurses\fP routine to call when
initializing a program.
A few special routines sometimes need to be called before it;
-these are \fBslk_init\fR, \fBfilter\fR, \fBripoffline\fR,
-\fBuse_env\fR.
+these are \fBslk_init\fP(3X), \fBfilter\fP, \fBripoffline\fP,
+\fBuse_env\fP.
For multiple-terminal applications,
-\fBnewterm\fR may be called before \fBinitscr\fR.
+\fBnewterm\fP may be called before \fBinitscr\fP.
.PP
-The initscr code determines the terminal type and initializes all \fBcurses\fR
+The initscr code determines the terminal type and initializes all \fBcurses\fP
data structures.
-\fBinitscr\fR also causes the first call to \fBrefresh\fR to clear the screen.
-If errors occur, \fBinitscr\fR writes an appropriate error
+\fBinitscr\fP also causes the first call to \fBrefresh\fP(3X)
+to clear the screen.
+If errors occur, \fBinitscr\fP writes an appropriate error
message to standard error and exits;
-otherwise, a pointer is returned to \fBstdscr\fR.
+otherwise, a pointer is returned to \fBstdscr\fP.
.SS newterm
-.PP
-A program that outputs to more than one terminal should use the \fBnewterm\fR
-routine for each terminal instead of \fBinitscr\fR.
+A program that outputs to more than one terminal should use the \fBnewterm\fP
+routine for each terminal instead of \fBinitscr\fP.
A program that needs to inspect capabilities,
so it can continue to run in a line-oriented mode if the
terminal cannot support a screen-oriented program, would also use
-\fBnewterm\fR.
-The routine \fBnewterm\fR should be called once for each terminal.
-It returns a variable of type \fBSCREEN *\fR which should be saved
+\fBnewterm\fP.
+.PP
+The routine \fBnewterm\fP should be called once for each terminal.
+It returns a variable of type \fISCREEN *\fP which should be saved
as a reference to that terminal.
\fBnewterm\fP's arguments are
.bP
-the \fItype\fR of the terminal to be used in place of \fB$TERM\fR,
+the \fItype\fP of the terminal to be used in place of \fB$TERM\fP,
.bP
-a file pointer for output to the terminal, and
+an output stream connected to the terminal, and
.bP
-another file pointer for input from the terminal
+an input stream connected to the terminal
.PP
-If the \fItype\fR parameter is \fBNULL\fR, \fB$TERM\fR will be used.
+If the \fItype\fP parameter is \fBNULL\fP, \fB$TERM\fP will be used.
+.PP
+The file descriptor of the output stream is passed to \fBsetupterm\fP(3X),
+which returns a pointer to a \fI\%TERMINAL\fP structure.
+\fBnewterm\fP's return value holds a pointer to the \fI\%TERMINAL\fP structure.
.SS endwin
-.PP
The program must also call
-\fBendwin\fR for each terminal being used before exiting from \fBcurses\fR.
-If \fBnewterm\fR is called more than once for the same terminal, the first
-terminal referred to must be the last one for which \fBendwin\fR is called.
+\fBendwin\fP for each terminal being used before exiting from \fBcurses\fP.
+If \fBnewterm\fP is called more than once for the same terminal, the first
+terminal referred to must be the last one for which \fBendwin\fP is called.
.PP
-A program should always call \fBendwin\fR before exiting or escaping from
-\fBcurses\fR mode temporarily.
+A program should always call \fBendwin\fP before exiting or escaping from
+\fBcurses\fP mode temporarily.
This routine
.bP
-restores tty modes,
+resets colors to correspond with the default color pair 0,
.bP
-moves the cursor to the lower left-hand corner of the screen and
+moves the cursor to the lower left-hand corner of the screen,
.bP
-resets the terminal into
-the proper non-visual mode.
+clears the remainder of the line so that it uses the default colors,
+.bP
+sets the cursor to normal visibility (see \fBcurs_set\fP(3X)),
+.bP
+stops cursor-addressing mode using the \fIexit_ca_mode\fP terminal capability,
+.bP
+restores tty modes (see \fBreset_shell_mode\fP(3X)).
.PP
-Calling \fBrefresh\fR or \fBdoupdate\fR after a
+Calling \fBrefresh\fP(3X) or \fBdoupdate\fP(3X) after a
temporary escape causes the program to resume visual mode.
.SS isendwin
-.PP
-The \fBisendwin\fR routine returns \fBTRUE\fR if \fBendwin\fR has been
-called without any subsequent calls to \fBwrefresh\fR,
-and \fBFALSE\fR otherwise.
+The \fBisendwin\fP routine returns \fBTRUE\fP if \fBendwin\fP has been
+called without any subsequent calls to \fBwrefresh\fP,
+and \fBFALSE\fP otherwise.
.SS set_term
-.PP
-The \fBset_term\fR routine is used to switch between different terminals.
-The screen reference \fBnew\fR becomes the new current terminal.
+The \fBset_term\fP routine is used to switch between different terminals.
+The screen reference \fInew\fP becomes the new current terminal.
The previous terminal is returned by the routine.
-This is the only routine which manipulates \fBSCREEN\fR pointers;
+This is the only routine which manipulates \fISCREEN\fP pointers;
all other routines affect only the current terminal.
.SS delscreen
-.PP
-The \fBdelscreen\fR routine frees storage associated with the
-\fBSCREEN\fR data structure.
-The \fBendwin\fR routine does not do
-this, so \fBdelscreen\fR should be called after \fBendwin\fR if a
-particular \fBSCREEN\fR is no longer needed.
+The \fBdelscreen\fP routine frees storage associated with the
+\fISCREEN\fP data structure.
+The \fBendwin\fP routine does not do
+this, so \fBdelscreen\fP should be called after \fBendwin\fP if a
+particular \fISCREEN\fP is no longer needed.
.SH RETURN VALUE
-\fBendwin\fR returns the integer \fBERR\fR upon failure and \fBOK\fR
+\fBendwin\fP returns the integer \fBERR\fP upon failure and \fBOK\fP
upon successful completion.
.PP
-Routines that return pointers always return \fBNULL\fR on error.
+Routines that return pointers always return \fBNULL\fP on error.
.PP
X/Open defines no error conditions.
In this implementation
.bP
-\fBendwin\fP returns an error if the terminal was not initialized.
+\fBendwin\fP returns an error if
+.RS
+.bP
+the terminal was not initialized, or
+.bP
+\fBendwin\fP is called more than once without updating the screen, or
+.bP
+\fBreset_shell_mode\fP(3X) returns an error.
+.RE
.bP
\fBnewterm\fP
returns an error if it cannot allocate the data structures for the screen,
@@ -155,47 +173,96 @@
.bP
\fBset_term\fP
returns no error.
-.SH NOTES
-Note that \fBinitscr\fR and \fBnewterm\fR may be macros.
.SH PORTABILITY
-These functions were described in the XSI Curses standard, Issue 4.
+These functions were described in X/Open Curses, Issue 4.
As of 2015, the current document is X/Open Curses, Issue 7.
.SS Differences
-X/Open specifies that portable applications must not
-call \fBinitscr\fR more than once:
+X/Open Curses specifies that portable applications must not
+call \fBinitscr\fP more than once:
.bP
The portable way to use \fBinitscr\fP is once only,
-using \fBrefresh\fP (see curs_refresh(3X)) to restore the screen after \fBendwin\fP.
+using \fB\%refresh\fP(3X)
+to restore the screen after \fBendwin\fP.
.bP
This implementation allows using \fBinitscr\fP after \fBendwin\fP.
.PP
-Old versions of curses, e.g., BSD 4.4, may have returned a null pointer
-from \fBinitscr\fR when an error is detected, rather than exiting.
-It is safe but redundant to check the return value of \fBinitscr\fR
-in XSI Curses.
-.SS Unset TERM Variable
+Old versions of curses, e.g., BSD 4.4, would return a null pointer
+from \fBinitscr\fP when an error is detected, rather than exiting.
+It is safe but redundant to check the return value of \fBinitscr\fP
+in X/Open Curses.
.PP
-If the TERM variable is missing or empty, \fBinitscr\fP uses the
+Calling \fBendwin\fP does not dispose of the memory allocated in \fBinitscr\fP
+or \fBnewterm\fP.
+Deleting a \fISCREEN\fP provides a way to do this:
+.bP
+X/Open Curses does not say what happens to \fI\%WINDOW\fPs when \fBdelscreen\fP
+\*(``frees storage associated with the \fISCREEN\fP\*(''
+nor does the SVr4 documentation help,
+adding that it should be called after \fBendwin\fP if a \fISCREEN\fP
+is no longer needed.
+.bP
+However, \fI\%WINDOW\fPs are implicitly associated with a \fISCREEN\fP.
+so that it is reasonable to expect \fBdelscreen\fP to deal with these.
+.bP
+SVr4 curses deletes the standard \fI\%WINDOW\fP structures
+\fBstdscr\fP and \fBcurscr\fP as well as a work area \fBnewscr\fP.
+SVr4 curses ignores other windows.
+.bP
+Since version 4.0 (1996),
+\fI\%ncurses\fP has maintained a list of all windows for each screen,
+using that information to delete those windows when \fBdelscreen\fP is called.
+.bP
+NetBSD copied this feature of \fI\%ncurses\fP in 2001.
+PDCurses follows the SVr4 model,
+deleting only the standard \fI\%WINDOW\fP structures.
+.SS "High-level versus Low-level"
+Different implementations may disagree regarding the level of some functions.
+For example, \fISCREEN\fP (returned by \fBnewterm\fP) and
+\fI\%TERMINAL\fP (returned by \fBsetupterm\fP(3X)) hold file descriptors for
+the output stream.
+If an application switches screens using \fBset_term\fR,
+or switches terminals using \fBset_curterm\fP(3X),
+applications which use the output file descriptor can have different
+behavior depending on which structure holds the corresponding descriptor.
+.PP
+For example
+.bP
+NetBSD's \fBbaudrate\fP(3X) function uses the descriptor in \fI\%TERMINAL\fP.
+\fI\%ncurses\fP and SVr4 use the descriptor in \fISCREEN\fP.
+.bP
+NetBSD and \fI\%ncurses\fP use the descriptor
+in \fI\%TERMINAL\fP
+for terminal I/O modes,
+e.g.,
+\fBdef_shell_mode\fP(3X),
+\fBdef_prog_mode\fP(3X).
+SVr4 curses uses the descriptor in \fISCREEN\fP.
+.SS "Unset \fITERM\fP Variable"
+If the \fITERM\fP variable is missing or empty, \fBinitscr\fP uses the
value \*(``unknown\*('',
which normally corresponds to a terminal entry with the \fIgeneric\fP
(\fIgn\fP) capability.
-Generic entries are detected by \fBsetupterm\fP (see curs_terminfo(3X)) and cannot be
-used for full-screen operation.
-Other implementations may handle a missing/empty TERM variable differently.
-.SS Signal Handlers
-.PP
-Quoting from X/Open Curses, section 3.1.1:
+Generic entries are detected by \fBsetupterm\fP(3X)
+and cannot be used for full-screen operation.
+Other implementations may handle
+a missing/empty \fITERM\fP variable differently.
+.SS "Signal Handlers"
+Quoting from X/Open Curses Issue 7, section 3.1.1:
.RS 5
.PP
-\fICurses implementations may provide for special handling of the SIGINT,
-SIGQUIT and SIGTSTP signals if their disposition is SIG_DFL at the time
-\fBinitscr()\fP is called \fP...
+Curses implementations may provide for special handling of the
+\%SIGINT,
+\%SIGQUIT,
+and \%SIGTSTP signals if their disposition is \%SIG_DFL at the time
+.I \%initscr
+is called.\|.\|.
.PP
-\fIAny special handling for these signals may remain in effect for the
+Any special handling for these signals may remain in effect for the
life of the process or until the process changes the disposition of
-the signal.\fP
+the signal.
.PP
-\fINone of the Curses functions are required to be safe with respect to signals \fP...
+None of the Curses functions are required to be safe
+with respect to signals.\|.\|.
.RE
.PP
This implementation establishes signal handlers during initialization,
@@ -204,18 +271,19 @@
handlers \fIafter\fP initializing the library:
.TP 5
.B SIGINT
-The handler \fIattempts\fP to cleanup the screen on exit.
+The handler \fIattempts\fP to clean up the screen on exit.
Although it \fIusually\fP works as expected, there are limitations:
.RS 5
.bP
-Walking the \fBSCREEN\fP list is unsafe, since all list management
+Walking the \fISCREEN\fP list is unsafe, since all list management
is done without any signal blocking.
.bP
On systems which have \fBREENTRANT\fP turned on, \fBset_term\fP uses
functions which could deadlock or misbehave in other ways.
.bP
-\fBendwin\fP calls other functions, many of which use stdio or
-other library functions which are clearly unsafe.
+\fBendwin\fP calls other functions,
+many of which use \fI\%stdio\fP(3) or other library functions which are
+clearly unsafe.
.RE
.TP 5
.B SIGTERM
@@ -226,25 +294,26 @@
.B SIGTSTP
This handles the \fIstop\fP signal, used in job control.
When resuming the process, this implementation discards pending
-input with \fBflushinput\fP (see curs_util(3X)), and repaints the screen
+input with \fB\%flushinp\fP(3X), and repaints the screen
assuming that it has been completely altered.
-It also updates the saved terminal modes with \fBdef_shell_mode\fP (see curs_kernel(3X)).
+It also updates the saved terminal modes with
+\fB\%def_shell_mode\fP(3X).
.TP 5
.B SIGWINCH
-This handles the window-size changes which were initially ignored in
+This handles the window-size changes which were ignored in
the standardization efforts.
The handler sets a (signal-safe) variable
-which is later tested in \fBwgetch\fP (see curs_getch(3X)).
+which is later tested in \fB\%wgetch\fP(3X).
If \fBkeypad\fP has been enabled for the corresponding window,
\fBwgetch\fP returns the key symbol \fBKEY_RESIZE\fP.
At the same time, \fBwgetch\fP calls \fBresizeterm\fP to adjust the
standard screen \fBstdscr\fP,
and update other data such as \fBLINES\fP and \fBCOLS\fP.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_kernel\fR(3X),
-\fBcurs_refresh\fR(3X),
-\fBcurs_slk\fR(3X),
-\fBcurs_terminfo\fR(3X),
-\fBcurs_util\fR(3X),
-\fBcurs_variables\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_kernel\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_slk\fP(3X),
+\fB\%curs_terminfo\fP(3X),
+\fB\%curs_util\fP(3X),
+\fB\%curs_variables\fP(3X)
diff --git a/man/curs_inopts.3x b/man/curs_inopts.3x
index 7b9a1be..63db496 100644
--- a/man/curs_inopts.3x
+++ b/man/curs_inopts.3x
@@ -1,5 +1,7 @@
+'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2013,2015 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -26,322 +28,527 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inopts.3x,v 1.19 2015/04/11 10:21:38 tom Exp $
-.TH curs_inopts 3X ""
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
-.na
-.hy 0
+.\" $Id: curs_inopts.3x,v 1.66 2024/04/13 22:20:29 tom Exp $
+.TH curs_inopts 3X 2024-04-13 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-\fBcbreak\fR,
-\fBnocbreak\fR,
-\fBecho\fR,
-\fBnoecho\fR,
-\fBhalfdelay\fR,
-\fBintrflush\fR,
-\fBkeypad\fR,
-\fBmeta\fR,
-\fBnodelay\fR,
-\fBnotimeout\fR,
-\fBraw\fR,
-\fBnoraw\fR,
-\fBnoqiflush\fR,
-\fBqiflush\fR,
-\fBtimeout\fR,
-\fBwtimeout\fR,
-\fBtypeahead\fR \- \fBcurses\fR input options
-.ad
-.hy
+\fB\%cbreak\fP,
+\fB\%echo\fP,
+\fB\%halfdelay\fP,
+\fB\%intrflush\fP,
+\fB\%is_cbreak\fP,
+\fB\%is_echo\fP,
+\fB\%is_nl\fP,
+\fB\%is_raw\fP,
+\fB\%keypad\fP,
+\fB\%meta\fP,
+\fB\%nl\fP,
+\fB\%nocbreak\fP,
+\fB\%nodelay\fP,
+\fB\%noecho\fP,
+\fB\%nonl\fP,
+\fB\%noqiflush\fP,
+\fB\%noraw\fP,
+\fB\%notimeout\fP,
+\fB\%qiflush\fP,
+\fB\%raw\fP,
+\fB\%timeout\fP,
+\fB\%wtimeout\fP,
+\fB\%typeahead\fP \-
+get and set \fIcurses\fR terminal input options
.SH SYNOPSIS
-\fB#include <curses.h>\fR
+.nf
+\fB#include <curses.h>
.PP
-\fBint cbreak(void);\fR
-.br
-\fBint nocbreak(void);\fR
-.br
-\fBint echo(void);\fR
-.br
-\fBint noecho(void);\fR
-.br
-\fBint halfdelay(int tenths);\fR
-.br
-\fBint intrflush(WINDOW *win, bool bf);\fR
-.br
-\fBint keypad(WINDOW *win, bool bf);\fR
-.br
-\fBint meta(WINDOW *win, bool bf);\fR
-.br
-\fBint nodelay(WINDOW *win, bool bf);\fR
-.br
-\fBint raw(void);\fR
-.br
-\fBint noraw(void);\fR
-.br
-\fBvoid noqiflush(void);\fR
-.br
-\fBvoid qiflush(void);\fR
-.br
-\fBint notimeout(WINDOW *win, bool bf);\fR
-.br
-\fBvoid timeout(int delay);\fR
-.br
-\fBvoid wtimeout(WINDOW *win, int delay);\fR
-.br
-\fBint typeahead(int fd);\fR
-.br
+\fBint cbreak(void);
+\fBint nocbreak(void);
+.PP
+\fBint echo(void);
+\fBint noecho(void);
+.PP
+\fBint intrflush(WINDOW *\fIwin\fP, bool \fIbf\fP);
+\fBint keypad(WINDOW *\fIwin\fP, bool \fIbf\fP);
+\fBint meta(WINDOW *\fIwin\fP, bool \fIbf\fP);
+\fBint nodelay(WINDOW *\fIwin\fP, bool \fIbf\fP);
+\fBint notimeout(WINDOW *\fIwin\fP, bool \fIbf\fP);
+.PP
+\fBint nl(void);
+\fBint nonl(void);
+.PP
+\fBint raw(void);
+\fBint noraw(void);
+.PP
+\fBvoid qiflush(void);
+\fBvoid noqiflush(void);
+.PP
+\fBint halfdelay(int \fItenths\fP);
+\fBvoid timeout(int \fIdelay\fP);
+\fBvoid wtimeout(WINDOW *\fIwin\fP, int \fIdelay\fP);
+.PP
+\fBint typeahead(int \fIfd\fP);
+.PP
+\fI/* extensions */
+\fBint is_cbreak(void);
+\fBint is_echo(void);
+\fBint is_nl(void);
+\fBint is_raw(void);
+.fi
.SH DESCRIPTION
-The \fBncurses\fP library provides several functions which let an application
-change way input from the terminal is handled.
-Some are global, applying to all windows.
+.I \%ncurses
+provides several functions that let an application change the way input
+from the terminal is handled.
+Some are global,
+applying to all windows.
Others apply only to a specific window.
Window-specific settings are not automatically applied to new or derived
windows.
-An application must apply these to each window, if the same behavior
-is needed.
+An application must apply these to each window if the same behavior is
+desired.
.\"
-.SS cbreak
-Normally, the tty driver buffers typed characters until a newline or carriage
+.SS "cbreak, nocbreak"
+Normally,
+the terminal driver buffers typed characters until a newline or carriage
return is typed.
-The \fBcbreak\fR routine disables line buffering and
-erase/kill character-processing (interrupt and flow control characters are
-unaffected), making characters typed by the user immediately available to the
+The \fB\%cbreak\fP routine disables line buffering and
+erase/kill character-processing
+(interrupt and flow control characters are unaffected),
+making characters typed by the user immediately available to the
program.
-The \fBnocbreak\fR routine returns the terminal to normal (cooked)
+The \fB\%nocbreak\fP routine returns the terminal to normal (cooked)
mode.
.PP
-Initially the terminal may or may not be in \fBcbreak\fR mode, as the mode is
-inherited; therefore, a program should call \fBcbreak\fR or \fBnocbreak\fR
-explicitly.
-Most interactive programs using \fBcurses\fR set the \fBcbreak\fR
-mode.
-Note that \fBcbreak\fR overrides \fBraw\fR.
-[See \fBcurs_getch\fR(3X) for a
-discussion of how these routines interact with \fBecho\fR and \fBnoecho\fR.]
+Initially the terminal may or may not be in \fB\%cbreak\fP mode,
+as the mode is inherited;
+therefore,
+a program should call \fB\%cbreak\fP or \fB\%nocbreak\fP explicitly.
+Most interactive programs using
+.I curses
+set the \fB\%cbreak\fP mode.
+Note that \fB\%cbreak\fP overrides \fBraw\fP.
+[See \fB\%curs_getch\fP(3X) for a discussion of how these routines
+interact with \fBecho\fP and \fB\%noecho\fP.]
.\"
-.SS echo/noecho
-.PP
-The \fBecho\fR and \fBnoecho\fR routines control whether characters typed by
-the user are echoed by \fBgetch\fR as they are typed.
-Echoing by the tty
-driver is always disabled, but initially \fBgetch\fR is in echo mode, so
-characters typed are echoed.
+.SS "echo, noecho"
+The \fBecho\fP and \fB\%noecho\fP routines control whether characters
+typed by the user are echoed by \fB\%getch\fP(3X) as they are typed.
+Echoing by the terminal driver is always disabled,
+but initially \fB\%getch\fP is in echo mode,
+so characters typed are echoed.
Authors of most interactive programs prefer to do
-their own echoing in a controlled area of the screen, or not to echo at all, so
-they disable echoing by calling \fBnoecho\fR.
-[See \fBcurs_getch\fR(3X) for a
-discussion of how these routines interact with \fBcbreak\fR and
-\fBnocbreak\fR.]
+their own echoing in a controlled area of the screen,
+or not to echo at all,
+so they disable echoing by calling \fB\%noecho\fP.
+[See \fB\%curs_getch\fP(3X) for a
+discussion of how these routines interact with \fB\%cbreak\fP and
+\fB\%nocbreak\fP.]
.\"
.SS halfdelay
-.PP
-The \fBhalfdelay\fR routine is used for half-delay mode, which is similar to
-\fBcbreak\fR mode in that characters typed by the user are immediately
-available to the program.
-However, after blocking for \fItenths\fR tenths of
-seconds, ERR is returned if nothing has been typed.
-The value of \fBtenths\fR
-must be a number between 1 and 255.
-Use \fBnocbreak\fR to leave half-delay
-mode.
+The \fB\%halfdelay\fP routine is used for half-delay mode,
+which is similar to \fB\%cbreak\fP mode in that characters typed by the
+user are immediately available to the program.
+However,
+after blocking for \fItenths\fP tenths of seconds,
+\fBERR\fP is returned if nothing has been typed.
+The value of \fItenths\fP must be a number between 1 and 255.
+Use \fB\%nocbreak\fP to leave half-delay mode.
.\"
.SS intrflush
-.PP
-If the \fBintrflush\fR option is enabled, (\fIbf\fR is \fBTRUE\fR), when an
-interrupt key is pressed on the keyboard (interrupt, break, quit) all output in
-the tty driver queue will be flushed, giving the effect of faster response to
-the interrupt, but causing \fBcurses\fR to have the wrong idea of what is on
-the screen.
-Disabling (\fIbf\fR is \fBFALSE\fR), the option prevents the
-flush.
-The default for the option is inherited from the tty driver settings.
-The window argument is ignored.
+If the \fB\%intrflush\fP option is enabled
+.RI ( bf
+is
+.BR TRUE ),
+and an interrupt key is pressed on the keyboard
+(interrupt,
+break,
+quit),
+all output in the terminal driver queue is flushed,
+giving the effect of faster response to the interrupt,
+but causing
+.I curses
+to have the wrong idea of what is on the screen.
+Disabling the option
+.RI ( bf
+is
+.BR FALSE ),
+prevents the flush.
+The default for the option is inherited from the terminal driver
+settings.
+The
+.I win
+argument is ignored.
.\"
.SS keypad
-.PP
-The \fBkeypad\fR option enables the keypad of the user's terminal.
+The \fB\%keypad\fP option enables the keypad of the user's terminal.
If
-enabled (\fIbf\fR is \fBTRUE\fR), the user can press a function key
-(such as an arrow key) and \fBwgetch\fR returns a single value
-representing the function key, as in \fBKEY_LEFT\fR.
+enabled
+.RI ( bf
+is
+.BR TRUE ),
+the user can press a function key
+(such as an arrow key)
+and \fB\%wgetch\fP(3X) returns a single value representing the function
+key,
+as in \fB\%KEY_LEFT\fP.
If disabled
-(\fIbf\fR is \fBFALSE\fR), \fBcurses\fR does not treat function keys
-specially and the program has to interpret the escape sequences
-itself.
-If the keypad in the terminal can be turned on (made to
-transmit) and off (made to work locally), turning on this option
-causes the terminal keypad to be turned on when \fBwgetch\fR is
-called.
+(\fIbf\fP is \fBFALSE\fP),
+.I curses
+does not treat function keys specially and the program has to interpret
+the escape sequences itself.
+If the keypad in the terminal can be turned on
+(made to transmit)
+and off
+(made to work locally),
+turning on this option causes the terminal keypad to be turned on when
+\fB\%wgetch\fP(3X) is called.
The default value for keypad is \fBFALSE\fP.
.\"
.SS meta
-.PP
-Initially, whether the terminal returns 7 or 8 significant bits on
-input depends on the control mode of the tty driver [see termio(7)].
-To force 8 bits to be returned, invoke \fBmeta\fR(\fIwin\fR,
-\fBTRUE\fR); this is equivalent, under POSIX, to setting the CS8 flag
-on the terminal.
-To force 7 bits to be returned, invoke
-\fBmeta\fR(\fIwin\fR, \fBFALSE\fR); this is equivalent, under POSIX,
+Initially,
+whether the terminal returns 7 or 8 significant bits on input depends on
+the control mode of the terminal driver [see \fI\%termios\fP(3)].
+To force 8 bits to be returned,
+invoke
+\fBmeta\fP(\fIwin\fP, \fBTRUE\fP);
+this is equivalent,
+under POSIX,
+to setting the CS8 flag on the terminal.
+To force 7 bits to be returned,
+invoke
+\fBmeta\fP(\fIwin\fP, \fBFALSE\fP);
+this is equivalent,
+under POSIX,
to setting the CS7 flag on the terminal.
The window argument,
-\fIwin\fR, is always ignored.
-If the terminfo capabilities \fBsmm\fR
-(meta_on) and \fBrmm\fR (meta_off) are defined for the terminal,
-\fBsmm\fR is sent to the terminal when \fBmeta\fR(\fIwin\fR,
-\fBTRUE\fR) is called and \fBrmm\fR is sent when \fBmeta\fR(\fIwin\fR,
-\fBFALSE\fR) is called.
+.IR win ,
+is always ignored.
+If the terminfo capabilities
+\fBsmm\fP (meta_on) and
+\fBrmm\fP (meta_off) are defined for the terminal,
+\fBsmm\fP is sent to the terminal when
+\fBmeta\fP(\fIwin\fP, \fBTRUE\fP)
+is called and \fBrmm\fP is sent when
+\fBmeta\fP(\fIwin\fP, \fBFALSE\fP) is called.
+.\"
+.SS "nl, nonl"
+The \fBnl\fP and \fBnonl\fP routines control whether the underlying
+display device translates the return key into newline on input.
.\"
.SS nodelay
-.PP
-The \fBnodelay\fR option causes \fBgetch\fR to be a non-blocking call.
-If no input is ready, \fBgetch\fR returns \fBERR\fR.
+The \fB\%nodelay\fP option causes \fB\%getch\fP to be a non-blocking
+call.
+If no input is ready,
+\fB\%getch\fP returns \fBERR\fP.
If disabled
-(\fIbf\fR is \fBFALSE\fR), \fBgetch\fR waits until a key is pressed.
-.PP
-While interpreting an input escape sequence, \fBwgetch\fR sets a timer
+.RI ( bf
+is
+.BR FALSE ),
+\fB\%getch\fP waits until a key is pressed.
+.SS notimeout
+When interpreting an escape sequence,
+\fB\%wgetch\fP(3X) sets a timer
while waiting for the next character.
-If \fBnotimeout(\fR\fIwin\fR,
-\fBTRUE\fR) is called, then \fBwgetch\fR does not set a timer.
-The
-purpose of the timeout is to differentiate between sequences received
-from a function key and those typed by a user.
-.\"
-.SS raw/noraw
-.PP
-The \fBraw\fR and \fBnoraw\fR routines place the terminal into or out of raw
-mode.
-Raw mode is similar to \fBcbreak\fR mode, in that characters typed are
-immediately passed through to the user program.
-The differences are that in
-raw mode, the interrupt, quit, suspend, and flow control characters are all
-passed through uninterpreted, instead of generating a signal.
-The behavior of
-the BREAK key depends on other bits in the tty driver that are not set by
-\fBcurses\fR.
-.\"
-.SS noqiflush
-.PP
-When the \fBnoqiflush\fR routine is used, normal flush of input and
-output queues associated with the \fBINTR\fR, \fBQUIT\fR and
-\fBSUSP\fR characters will not be done [see termio(7)].
-When
-\fBqiflush\fR is called, the queues will be flushed when these control
-characters are read.
-You may want to call \fBnoqiflush()\fR in a signal
-handler if you want output to continue as though the interrupt
-had not occurred, after the handler exits.
-.\"
-.SS timeout/wtimeout
-.PP
-The \fBtimeout\fR and \fBwtimeout\fR routines set blocking or
-non-blocking read for a given window.
-If \fIdelay\fR is negative,
-blocking read is used (i.e., waits indefinitely for
-input).
-If \fIdelay\fR is zero, then non-blocking read is used
-(i.e., read returns \fBERR\fR if no input is waiting).
If
-\fIdelay\fR is positive, then read blocks for \fIdelay\fR
-milliseconds, and returns \fBERR\fR if there is still no input.
-Hence, these routines provide the same functionality as \fBnodelay\fR,
+\fB\%notimeout(\fIwin\fR, \fBTRUE\fP)
+is called,
+then \fB\%wgetch\fP does not set a timer.
+The purpose of the timeout is to distinguish sequences produced by a
+function key from those typed by a user.
+.\"
+.SS "raw, noraw"
+The \fBraw\fP and \fB\%noraw\fP routines place the terminal into or out
+of raw mode.
+Raw mode is similar to \fB\%cbreak\fP mode,
+in that characters typed are immediately passed through to the user
+program.
+The differences are that in raw mode,
+the interrupt,
+quit,
+suspend,
+and flow control characters are all
+passed through uninterpreted,
+instead of generating a signal.
+The behavior of the BREAK key depends on other bits in the terminal
+driver that are not set by
+.IR curses .
+.\"
+.SS "qiflush, nqiflush"
+When the \fB\%noqiflush\fP routine is used,
+normal flush of input and output queues associated with the \fBINTR\fP,
+\fBQUIT\fP and \fBSUSP\fP characters will not be done
+[see \fB\%termios\fP(3)].
+When
+\fB\%qiflush\fP is called,
+the queues will be flushed when these control characters are read.
+You may want to call \fB\%noqiflush\fP in a signal handler if you want
+output to continue as though the interrupt had not occurred,
+after the handler exits.
+.\"
+.SS "timeout, wtimeout"
+The \fB\%timeout\fP and \fB\%wtimeout\fP routines set blocking or
+non-blocking read for a given window.
+If \fIdelay\fP is negative,
+a blocking read is used
+(i.e.,
+waits indefinitely for input).
+If \fIdelay\fP is zero,
+then a non-blocking read is used
+(i.e.,
+.I read
+returns \fBERR\fP if no input is waiting).
+If
+\fIdelay\fP is positive,
+then
+.I read
+blocks for \fIdelay\fP milliseconds,
+and returns \fBERR\fP if there is still no input.
+Hence,
+these routines provide the same functionality as \fB\%nodelay\fP,
plus the additional capability of being able to block for only
-\fIdelay\fR milliseconds (where \fIdelay\fR is positive).
+\fIdelay\fP milliseconds
+(where \fIdelay\fP is positive).
.\"
.SS typeahead
-.PP
-The \fBcurses\fR library does \*(``line-breakout optimization\*(''
-by looking for typeahead periodically while updating the screen.
-If input is found, and it is coming from a tty,
+.I curses
+does \*(``line-breakout optimization\*('' by looking for typeahead
+periodically while updating the screen.
+If input is found,
+and it is coming from a terminal,
the current update is postponed until
-\fBrefresh\fR or \fBdoupdate\fR is called again.
+\fB\%refresh\fP(3X) or \fB\%doupdate\fP is called again.
This allows faster response to commands typed in advance.
-Normally, the input FILE
-pointer passed to \fBnewterm\fR, or \fBstdin\fR in the case that
-\fBinitscr\fR was used, will be used to do this typeahead checking.
-The \fBtypeahead\fR routine specifies that the file descriptor
-\fIfd\fR is to be used to check for typeahead instead.
-If \fIfd\fR is
-\-1, then no typeahead checking is done.
+Normally,
+the input
+.I FILE
+pointer passed to \fB\%newterm\fP,
+or \fBstdin\fP in the case that \fB\%initscr\fP was used,
+will be used to do this typeahead checking.
+The \fB\%typeahead\fP routine specifies that the file descriptor
+\fIfd\fP is to be used to check for typeahead instead.
+If \fIfd\fP is
+\-1,
+then no typeahead checking is done.
.\"
.SH RETURN VALUE
-All routines that return an integer return \fBERR\fR upon failure and OK (SVr4
-specifies only "an integer value other than \fBERR\fR") upon successful
-completion, unless otherwise noted in the preceding routine descriptions.
+All routines that return an integer return \fBERR\fP upon failure and
+\fBOK\fP
+(SVr4 specifies only \*(``an integer value other than \fBERR\fP\*('')
+upon successful completion,
+unless otherwise noted in the preceding routine descriptions.
.PP
-X/Open does not define any error conditions.
+X/Open Curses does not specify any error conditions.
In this implementation,
functions with a window parameter will return an error if it is null.
-Any function will also return an error if the terminal was not initialized.
+Any function will also return an error if the terminal was not
+initialized.
Also,
-.RS
+.RS 3
.TP 5
-\fBhalfdelay\fP
+\fB\%halfdelay\fP
returns an error
if its parameter is outside the range 1..255.
.RE
+.SH NOTES
+\fBecho\fP,
+\fB\%noecho\fP,
+\fB\%halfdelay\fP,
+\fB\%intrflush\fP,
+\fBmeta\fP,
+\fBnl\fP,
+\fBnonl\fP,
+\fB\%nodelay\fP,
+\fB\%notimeout\fP,
+\fB\%noqiflush\fP,
+\fB\%qiflush\fP,
+\fB\%timeout\fP,
+and
+\fB\%wtimeout\fP
+may be implemented as macros.
+.PP
+\fB\%noraw\fP and \fB\%nocbreak\fP follow historical practice in that
+they attempt to restore normal (\*(``cooked\*('') mode
+from raw and cbreak modes respectively.
+Mixing \fBraw\fP/\fB\%noraw\fP and \fB\%cbreak\fP/\fB\%nocbreak\fP calls
+leads to terminal driver control states that are hard to predict or
+understand;
+doing so is not recommended.
+.SH EXTENSIONS
+.I \%ncurses
+provides four \*(``is_\*('' functions that may be used to detect if the
+corresponding flags were set or reset.
+.PP
+.TS
+center;
+Lb Lb Lb
+L L L .
+Query Set Reset
+_
+is_cbreak cbreak nocbreak
+is_echo echo noecho
+is_nl nl nonl
+is_raw raw noraw
+.TE
+.PP
+In each case,
+the function returns
+.TP 4 \" "-1" + 2n
+1
+if the flag is set,
+.TP
+0
+if the flag is reset,
+or
+.TP
+\-1
+if the library is not initialized.
+.PP
+They were designed for
+\fB\%ncurses\fP(3X),
+and are not found in SVr4
+.IR curses ,
+4.4BSD
+.IR curses ,
+or any other previous
+.I curses
+implementation.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
.PP
-The ncurses library obeys the XPG4 standard and the historical practice of the
-AT&T curses implementations, in that the echo bit is cleared when curses
+Except as noted in section \*(``EXTENSIONS\*('' above,
+X/Open Curses, Issue 4, Version 2 describes these functions.
+.PP
+.I \%ncurses
+follows X/Open Curses
+and the historical practice of AT&T
+.I curses
+implementations,
+in that the echo bit is cleared when
+.I curses
initializes the terminal state.
-BSD curses differed from this slightly; it
-left the echo bit on at initialization, but the BSD \fBraw\fR call turned it
-off as a side-effect.
-For best portability, set echo or noecho explicitly
-just after initialization, even if your program remains in cooked mode.
+BSD
+.I curses
+differed from this slightly;
+it left the echo bit on at initialization,
+but the BSD \fBraw\fP call turned it off as a side effect.
+For best portability,
+set \fBecho\fP or \fB\%noecho\fP explicitly just after initialization,
+even if your program remains in cooked mode.
.PP
-When \fBkeypad\fP is first enabled,
-ncurses loads the key-definitions for the current terminal description.
+X/Open Curses is ambiguous regarding whether \fBraw\fP should disable
+the CR/LF translations controlled by \fBnl\fP and \fBnonl\fP.
+BSD
+.I curses
+did turn off these translations;
+AT&T
+.I curses
+(at least as late as SVr1)
+did not.
+.I \%ncurses
+does so,
+on the assumption that a programmer requesting raw input wants a clean
+(ideally,
+8-bit clean)
+connection that the operating system will not alter.
+.PP
+When \fB\%keypad\fP is first enabled,
+.I \%ncurses
+loads the key definitions for the current terminal description.
If the terminal description includes extended string capabilities,
-e.g., from using the \fB\-x\fP option of @TIC@,
-then ncurses also defines keys for the capabilities whose names
-begin with "k".
-The corresponding keycodes are generated and (depending on previous
-loads of terminal descriptions) may differ from one execution of a
-program to the next.
-The generated keycodes are recognized by the \fBkeyname\fP function
-(which will then return a name beginning with "k" denoting the
-terminfo capability name rather than "K", used for curses key-names).
-On the other hand, an application can use \fBdefine_key\fP to establish
+e.g.,
+from using the
+.B \-x
+option of \fB\%@TIC@\fP,
+then
+.I \%ncurses
+also defines keys for the capabilities whose names begin with
+\*(``k\*(''.
+The corresponding keycodes are generated and
+(depending on previous loads of terminal descriptions)
+may differ from one execution of a program to the next.
+The generated keycodes are recognized by the \fB\%keyname\fP(3X)
+function
+(which will then return a name beginning with \*(``k\*('' denoting the
+terminfo capability name rather than \*(``K\*('',
+used for
+.I curses
+key names).
+On the other hand,
+an application can use \fB\%define_key\fP(3X) to establish
a specific keycode for a given string.
This makes it possible for an application to check for an extended
-capability's presence with \fItigetstr\fP,
+capability's presence with \fB\%tigetstr\fP,
and reassign the keycode to match its own needs.
.PP
-Low-level applications can use \fBtigetstr\fP to obtain the definition
+Low-level applications can use \fB\%tigetstr\fP to obtain the definition
of any particular string capability.
-Higher-level applications which use the curses \fBwgetch\fP
-and similar functions to return keycodes rely upon the order in which
-the strings are loaded.
+Higher-level applications which use the
+.I curses
+\fB\%wgetch\fP and similar functions to return keycodes rely upon the
+order in which the strings are loaded.
If more than one key definition has the same string value,
-then \fBwgetch\fP can return only one keycode.
-Most curses implementations (including ncurses)
+then \fB\%wgetch\fP can return only one keycode.
+Most
+.I curses
+implementations
+(including
+.IR \%ncurses )
load key definitions in the order
defined by the array of string capability names.
The last key to be loaded determines the keycode which will be returned.
-In ncurses, you may also have extended capabilities interpreted as
-key definitions.
+In
+.IR \%ncurses ,
+you may also have extended capabilities interpreted as key definitions.
These are loaded after the predefined keys,
and if a capability's value is the same as a previously-loaded
key definition,
the later definition is the one used.
-.SH NOTES
-Note that \fBecho\fR, \fBnoecho\fR, \fBhalfdelay\fR, \fBintrflush\fR,
-\fBmeta\fR, \fBnodelay\fR, \fBnotimeout\fR, \fBnoqiflush\fR,
-\fBqiflush\fR, \fBtimeout\fR, and \fBwtimeout\fR may be macros.
-.PP
-The \fBnoraw\fR and \fBnocbreak\fR calls follow historical practice in that
-they attempt to restore to normal (`cooked') mode from raw and cbreak modes
-respectively.
-Mixing raw/noraw and cbreak/nocbreak calls leads to tty driver
-control states that are hard to predict or understand; it is not recommended.
+.SH HISTORY
+Formerly,
+.I \%ncurses
+used
+.B \%nl
+and
+.B \%nonl
+to control the conversion of newlines to carriage return/line feed
+on output as well as input.
+X/Open Curses documents the use of these functions only for input.
+This difference arose from converting the
+.I \%pcurses
+source (1986),
+which used
+\fI\%ioctl\fP(2) calls and the
+.I \%sgttyb
+structure,
+to
+.I \%termios
+(the POSIX terminal API).
+In the former,
+both input and output were controlled via a single option
+.BR \%CRMOD ,
+while the latter separates these features.
+Because that conversion interferes with output optimization,
+.I \%ncurses
+6.2 (2020) amended
+.B \%nl
+and
+.B \%nonl
+to eliminate their effect on output.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_getch\fR(3X),
-\fBcurs_initscr\fR(3X),
-\fBcurs_util\fR(3X),
-\fBdefine_key\fR(3X),
-\fBtermio\fR(7)
+\fB\%curses\fP(3X),
+\fB\%curs_getch\fP(3X),
+\fB\%curs_initscr\fP(3X),
+\fB\%curs_util\fP(3X),
+\fB\%define_key\fP(3X),
+\fB\%termios\fP(3)
diff --git a/man/curs_ins_wch.3x b/man/curs_ins_wch.3x
index 4c6a925..90b03f6 100644
--- a/man/curs_ins_wch.3x
+++ b/man/curs_ins_wch.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2019-2023,2024 Thomas E. Dickey *
+.\" Copyright 2002-2010,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 *
@@ -26,38 +27,89 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_ins_wch.3x,v 1.5 2010/12/04 18:38:55 tom Exp $
-.TH curs_ins_wch 3X ""
+.\" $Id: curs_ins_wch.3x,v 1.30 2024/04/20 19:18:18 tom Exp $
+.TH curs_ins_wch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-\fBins_wch\fR,
-\fBmvins_wch\fR,
-\fBmvwins_wch\fR,
-\fBwins_wch\fR \- insert a complex character and rendition into a window
+\fB\%ins_wch\fP,
+\fB\%mvins_wch\fP,
+\fB\%mvwins_wch\fP,
+\fB\%wins_wch\fP \-
+insert a \fIcurses\fR complex character in a window
.SH SYNOPSIS
-#include <curses.h>
-.sp
-\fBint ins_wch(const cchar_t *\fR\fIwch\fR\fB);\fR
-.br
-\fBint wins_wch(WINDOW *\fR\fIwin, const cchar_t *\fR\fIwch\fR\fB);\fR
-.br
-\fBint mvins_wch(int \fR\fIy, int \fR\fIx, const cchar_t *\fR\fIwch\fR\fB);\fR
-.br
-\fBint mvwins_wch(WINDOW *\fR\fIwin, int \fR\fIy, int \fR\fIx, const cchar_t *\fR\fIwch\fR\fB);\fR
-.SH DESCRIPTION
-These routines, insert the complex character \fIwch\fR with rendition
-before the character under the cursor.
-All characters to the right of the cursor are moved one space to the right,
-with the possibility of the rightmost character on the line being lost.
-The insertion operation does not change the cursor position.
-.SH RETURN VALUE
-If successful, these functions return OK.
-If not, they return ERR.
+.nf
+\fB#include <curses.h>\fP
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
-.SH ERRORS
-No errors are defined.
-.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_insch\fR(3X).
+\fBint ins_wch(const cchar_t *\fIwch\fP);
+\fBint wins_wch(WINDOW *\fIwin\fP, const cchar_t *\fIwch\fP);
+\fBint mvins_wch(int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fP);
+\fBint mvwins_wch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fP);
+.fi
+.SH DESCRIPTION
+These functions insert the
+.I curses
+complex character
+.I wch
+at the cursor in the specified window
+.I win
+(or
+.BR \%stdscr ).
+The character previously at the cursor and any to its right move one
+cell to the right;
+the rightmost character on the line is discarded.
+The cursor does not advance.
+.SH "RETURN VALUE"
+These functions return \fBOK\fP on success and \fBERR\fP on failure.
+.PP
+Functions taking a
+.I \%WINDOW
+pointer argument fail if the pointer is
+.BR NULL .
+.PP
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
+.SH NOTES
+A terminal's
+.B \%insert_character
+.RB ( ich1 )
+capability
+is not necessarily employed.
+.PP
+\fB\%ins_wch\fP,
+\fB\%mvins_wch\fP,
+and
+\fB\%mvwins_wch\fP
+may be implemented as macros.
+.SH PORTABILITY
+X/Open Curses,
+Issue 4 describes these functions.
+.PP
+SVr4 describes successful return values only as
+\*(``an integer value other than \fBERR\fP\*(''.
+.SH HISTORY
+SVr4 (1989) implemented these functions under the names
+.BR inswch ,
+.BR winswch ,
+.BR mvinswch ,
+and
+.BR mvwinswch .
+.SH "SEE ALSO"
+\fB\%curs_insch\fP(3X) describes comparable functions in the
+non-wide-character
+.I curses
+configuration.
+.PP
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(5)
diff --git a/man/curs_ins_wstr.3x b/man/curs_ins_wstr.3x
index 12479b0..4ebd3ac 100644
--- a/man/curs_ins_wstr.3x
+++ b/man/curs_ins_wstr.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright 2019-2023,2024 Thomas E. Dickey *
+.\" Copyright 2002-2012,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 *
@@ -26,81 +27,102 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_ins_wstr.3x,v 1.7 2012/11/03 23:03:59 tom Exp $
-.TH curs_ins_wstr 3X ""
-.na
-.hy 0
+.\" $Id: curs_ins_wstr.3x,v 1.38 2024/04/20 21:23:08 tom Exp $
+.TH curs_ins_wstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBins_wstr\fR,
-\fBins_nwstr\fR,
-\fBwins_wstr\fR,
-\fBwins_nwstr\fR,
-\fBmvins_wstr\fR,
-\fBmvins_nwstr\fR,
-\fBmvwins_wstr\fR,
-\fBmvwins_nwstr\fR \- insert a wide-character string into a curses window
-.ad
-.hy
+\fB\%ins_wstr\fP,
+\fB\%ins_nwstr\fP,
+\fB\%wins_wstr\fP,
+\fB\%wins_nwstr\fP,
+\fB\%mvins_wstr\fP,
+\fB\%mvins_nwstr\fP,
+\fB\%mvwins_wstr\fP,
+\fB\%mvwins_nwstr\fP \-
+insert a wide-character string in a \fIcurses\fR window
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fR
-.sp
-\fBint ins_wstr(const wchar_t *\fR\fIwstr);\fR
-.br
-\fBint ins_nwstr(const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint wins_wstr(WINDOW *\fR\fIwin\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR
-.br
-\fBint wins_nwstr(WINDOW *\fR\fIwin\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint mvins_wstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR
-.br
-\fBint mvins_nwstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint mvwins_wstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR
-.br
-\fBint mvwins_nwstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
+\fB#include <curses.h>
+.PP
+\fBint ins_wstr(const wchar_t *\fIwstr\fP);
+\fBint ins_nwstr(const wchar_t *\fIwstr\fP, int \fIn\fP);
+\fBint wins_wstr(WINDOW *\fIwin\fP, const wchar_t *\fIwstr\fP);
+\fBint wins_nwstr(WINDOW *\fIwin\fP, const wchar_t *\fIwstr\fP, int \fIn\fP);
+.PP
+\fBint mvins_wstr(int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP);
+\fBint mvins_nwstr(int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP, int \fIn\fP);
+\fBint mvwins_wstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP);
+\fBint mvwins_nwstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP, int \fIn\fP);
.fi
.SH DESCRIPTION
-These routines insert a \fBwchar_t\fR character string
+These routines insert a \fBwchar_t\fP character string
(as many characters as will fit on the line)
-before the character under the cursor.
+before the character under the cursor,
+as if calling \fBwins_wch\fP(3X).
All characters to the right of the cursor are shifted right,
with the possibility of the rightmost characters on the line being lost.
No wrapping is performed.
+.PP
The cursor position does not change
-(after moving to \fIy\fR, \fIx\fR, if specified).
-The four routines with \fIn\fR as the last argument
-insert a leading substring of at most \fIn\fR \fBwchar_t\fR characters.
-If \fIn\fR is less than 1, the entire string is inserted.
+(after moving to \fIy\fP, \fIx\fP, if specified).
.PP
-If a character in \fIwstr\fR is a tab, newline, carriage return or
-backspace, the cursor is moved appropriately within the window.
-A newline also does a \fBclrtoeol\fR before moving.
-Tabs are considered to be at every eighth column.
-If a character in \fIwstr\fR is another control character,
-it is drawn in the \fB^\fR\fIX\fR notation.
-Calling \fBwin_wch\fR after adding a control character
-(and moving to it, if necessary)
-does not return the control character,
-but instead returns a character in the ^-representation
-of the control character.
-.SH NOTES
-Note that all but wins_nwstr may be macros.
+The functions with \fIn\fP as the last argument
+insert a leading substring of at most \fIn\fP \fBwchar_t\fP characters.
+If \fIn\fP is less than zero, the entire string is inserted
+(stopping on a L'\e0' character).
.PP
-If the first character in the string is a nonspacing character, these
-functions will fail.
-XSI does not define what will happen if a nonspacing character follows
-a control character.
+Special characters are handled as in \fBwadd_wch\fP(3X).
.SH RETURN VALUE
-Upon successful completion, these functions return OK.
-Otherwise, they return ERR.
+All functions return the integer \fBERR\fP upon failure and \fBOK\fP on success.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+X/Open Curses does not specify any error conditions.
+This implementation returns an error
+.bP
+if the \fIwin\fP parameter is null or
+.bP
+if the \fIwstr\fP parameter is null or
+.bP
+if the \fBwins_wch\fP function returns an error.
+.PP
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
+.SH NOTES
+All but \fBwins_nwstr\fP may be macros.
+.PP
+If the first character in the string is a non-spacing character, these
+functions will fail.
+X/Open Curses does not define what will happen
+if a non-spacing character follows a control character.
+.SH PORTABILITY
+These functions are described in X/Open Curses, Issue 4,
+which adds \fI\%const\fP qualifiers to the arguments.
+.PP
+X/Open states that the entire string is inserted if \fIn\fP is less than 1.
+This is probably an error,
+because it is inconsistent with other functions,
+and differs from the X/Open implementation on Solaris.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_insstr\fR(3X),
-\fBcurs_in_wch\fR(3X),
-\fBcurs_ins_wch\fR(3X).
+\fB\%curs_insstr\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its non-wide-character configuration.
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_ins_wch\fP(3X),
+\fB\%curs_in_wch\fP(3X)
diff --git a/man/curs_insch.3x b/man/curs_insch.3x
index 77e92ec..baf2f6c 100644
--- a/man/curs_insch.3x
+++ b/man/curs_insch.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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 *
@@ -26,47 +27,89 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_insch.3x,v 1.13 2010/12/04 18:38:55 tom Exp $
-.TH curs_insch 3X ""
+.\" $Id: curs_insch.3x,v 1.40 2024/04/20 19:03:47 tom Exp $
+.TH curs_insch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-\fBinsch\fR,
-\fBwinsch\fR,
-\fBmvinsch\fR,
-\fBmvwinsch\fR \- insert a character before cursor in a \fBcurses\fR window
+\fB\%insch\fP,
+\fB\%winsch\fP,
+\fB\%mvinsch\fP,
+\fB\%mvwinsch\fP \-
+insert a \fIcurses\fP character in a window
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint insch(chtype ch);\fR
-.br
-\fBint winsch(WINDOW *win, chtype ch);\fR
-.br
-\fBint mvinsch(int y, int x, chtype ch);\fR
-.br
-\fBint mvwinsch(WINDOW *win, int y, int x, chtype ch);\fR
-.br
+.nf
+\fB#include <curses.h>\fP
+.PP
+\fBint insch(chtype \fIch\fP);
+\fBint winsch(WINDOW *\fIwin\fP, chtype \fIch\fP);
+\fBint mvinsch(int \fIy\fP, int \fIx\fP, chtype \fIch\fP);
+\fBint mvwinsch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, chtype \fIch\fP);
+.fi
.SH DESCRIPTION
-These routines insert the character \fIch\fR before the character under the
-cursor. All characters to the right of the cursor are moved one space to the
-right, with the possibility of the rightmost character on the line being lost.
-The insertion operation does not change the cursor position.
-.SH RETURN VALUE
-All routines that return an integer return \fBERR\fR upon failure and OK (SVr4
-specifies only "an integer value other than \fBERR\fR") upon successful
-completion, unless otherwise noted in the preceding routine descriptions.
+These functions insert the
+.I curses
+character
+.I ch
+at the cursor in the specified window
+.I win
+(or
+.BR \%stdscr ).
+The character previously at the cursor and any to its right move one
+cell to the right;
+the rightmost character on the line is discarded.
+The cursor does not advance.
+.SH "RETURN VALUE"
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions taking a
+.I \%WINDOW
+pointer argument fail if the pointer is
+.BR NULL .
+.PP
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
-These routines do not necessarily imply use of a hardware insert character
-feature.
+.BR \%insch ,
+.BR \%mvinsch ,
+and
+.B \%mvwinsch
+may be implemented as macros.
.PP
-Note that \fBinsch\fR, \fBmvinsch\fR, and \fBmvwinsch\fR may be macros.
+A terminal's
+.B \%insert_character
+.RB ( ich1 )
+capability
+is not necessarily employed.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
-.SH SEE ALSO
-\fBcurses\fR(3X).
+X/Open Curses,
+Issue 4 describes these functions.
.PP
-Comparable functions in the wide-character (ncursesw) library are
-described in
-\fBcurs_ins_wch\fR(3X).
+SVr4
+.I curses
+describes a successful return value only as
+\*(``an integer value other than
+.BR ERR \*(''.
+.SH "SEE ALSO"
+\fB\%curs_ins_wch\fP(3X) describes comparable functions in the
+wide-character
+.I curses
+configuration.
+.PP
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(5)
diff --git a/man/curs_insstr.3x b/man/curs_insstr.3x
index 3e38a53..888d425 100644
--- a/man/curs_insstr.3x
+++ b/man/curs_insstr.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2019-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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 *
@@ -26,74 +27,98 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_insstr.3x,v 1.21 2010/12/04 18:38:55 tom Exp $
-.TH curs_insstr 3X ""
+.\" $Id: curs_insstr.3x,v 1.51 2024/04/20 21:20:07 tom Exp $
+.TH curs_insstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBinsstr\fR,
-\fBinsnstr\fR,
-\fBwinsstr\fR,
-\fBwinsnstr\fR,
-\fBmvinsstr\fR,
-\fBmvinsnstr\fR,
-\fBmvwinsstr\fR,
-\fBmvwinsnstr\fR \- insert string before cursor in a \fBcurses\fR window
+\fB\%insstr\fP,
+\fB\%insnstr\fP,
+\fB\%winsstr\fP,
+\fB\%winsnstr\fP,
+\fB\%mvinsstr\fP,
+\fB\%mvinsnstr\fP,
+\fB\%mvwinsstr\fP,
+\fB\%mvwinsnstr\fP \-
+insert a string in a \fIcurses\fR window
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.br
-\fBint insstr(const char *str);\fR
-.br
-\fBint insnstr(const char *str, int n);\fR
-.br
-\fBint winsstr(WINDOW *win, const char *str);\fR
-.br
-\fBint winsnstr(WINDOW *win, const char *str, int n);\fR
-.br
-\fBint mvinsstr(int y, int x, const char *str);\fR
-.br
-\fBint mvinsnstr(int y, int x, const char *str, int n);\fR
-.br
-\fBint mvwinsstr(WINDOW *win, int y, int x, const char *str);\fR
-.br
-\fBint mvwinsnstr(WINDOW *win, int y, int x, const char *str, int n);\fR
-.br
+.nf
+\fB#include <curses.h>
+\fBint insstr(const char *\fIstr\fP);
+\fBint insnstr(const char *\fIstr\fP, int \fIn\fP);
+\fBint winsstr(WINDOW *\fIwin\fP, const char *\fIstr\fP);
+\fBint winsnstr(WINDOW *\fIwin\fP, const char *\fIstr\fP, int \fIn\fP);
+.PP
+\fBint mvinsstr(int \fIy\fP, int \fIx\fP, const char *\fIstr\fP);
+\fBint mvinsnstr(int \fIy\fP, int \fIx\fP, const char *\fIstr\fP, int \fIn\fP);
+\fBint mvwinsstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const char *\fIstr\fP);
+\fBint mvwinsnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const char *\fIstr\fP, int \fIn\fP);
+.fi
.SH DESCRIPTION
These routines insert a character string
(as many characters as will fit on the line)
-before the character under the cursor.
-All characters to the right of the cursor are shifted right
+before the character under the cursor,
+as if calling \fBwinsch\fP(3X).
+All characters to the right of the cursor are shifted right,
with the possibility of the rightmost characters on the line being lost.
+No wrapping is performed.
+.PP
The cursor position does not change
-(after moving to \fIy\fR, \fIx\fR, if specified).
-The functions with \fIn\fR as the last argument
-insert a leading substring of at most \fIn\fR characters.
-If \fIn\fR<=0, then the entire string is inserted.
+(after moving to \fIy\fP, \fIx\fP, if specified).
.PP
-Special characters are handled as in \fBaddch\fP.
+The functions with \fIn\fP as the last argument
+insert a leading substring of at most \fIn\fP characters.
+If \fIn\fP is less than zero, the entire string is inserted
+(stopping on a NUL character).
+.PP
+Special characters are handled as in \fBwaddch\fP(3X).
.SH RETURN VALUE
-All routines that return an integer return \fBERR\fR upon failure and OK (SVr4
-specifies only "an integer value other than \fBERR\fR") upon successful
-completion, unless otherwise noted in the preceding routine descriptions.
+All functions return the integer \fBERR\fP upon failure and \fBOK\fP on success.
.PP
-X/Open defines no error conditions.
-In this implementation,
-if the window parameter is null or the str parameter is null,
-an error is returned.
+X/Open Curses does not specify any error conditions.
+This implementation returns an error
+.bP
+if the \fIwin\fP parameter is null or
+.bP
+if the \fIstr\fP parameter is null or
+.bP
+the \fBwinsch\fP(3X) function returns an error.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
-Note that all but \fBwinsnstr\fR may be macros.
+All but \fBwinsnstr\fP may be macros.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4, which adds
-const qualifiers to the arguments.
-.LP
-The Single Unix Specification, Version 2 states that
+These functions are described in X/Open Curses, Issue 4,
+which adds \fI\%const\fP qualifiers to the arguments.
+.PP
+The Single Unix Specification, Version 2 states that
\fBinsnstr\fP and \fBwinsnstr\fP perform wrapping.
This is probably an error, since it makes this group of functions inconsistent.
Also, no implementation of curses documents this inconsistency.
+.PP
+X/Open states that the entire string is inserted if \fIn\fP is less than 1.
+This is probably an error,
+because it is inconsistent with other functions,
+and differs from the SVr4 and X/Open implementations on Solaris.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_util\fR(3X),
-\fBcurs_clear\fR(3X),
-\fBcurs_inch\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_inch\fP(3X),
+\fB\%curs_ins_wstr\fP(3X),
+\fB\%curs_util\fP(3X)
diff --git a/man/curs_instr.3x b/man/curs_instr.3x
index 1b17db9..5b6e4b7 100644
--- a/man/curs_instr.3x
+++ b/man/curs_instr.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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 *
@@ -26,62 +27,104 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_instr.3x,v 1.16 2010/12/04 18:38:55 tom Exp $
-.TH curs_instr 3X ""
+.\" $Id: curs_instr.3x,v 1.51 2024/04/20 21:24:19 tom Exp $
+.TH curs_instr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBinstr\fR,
-\fBinnstr\fR,
-\fBwinstr\fR,
-\fBwinnstr\fR,
-\fBmvinstr\fR,
-\fBmvinnstr\fR,
-\fBmvwinstr\fR,
-\fBmvwinnstr\fR \- get a string of characters from a \fBcurses\fR window
+\fB\%instr\fP,
+\fB\%innstr\fP,
+\fB\%winstr\fP,
+\fB\%winnstr\fP,
+\fB\%mvinstr\fP,
+\fB\%mvinnstr\fP,
+\fB\%mvwinstr\fP,
+\fB\%mvwinnstr\fP \-
+get a string from a \fIcurses\fR window
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint instr(char *str);\fR
-.br
-\fBint innstr(char *str, int n);\fR
-.br
-\fBint winstr(WINDOW *win, char *str);\fR
-.br
-\fBint winnstr(WINDOW *win, char *str, int n);\fR
-.br
-\fBint mvinstr(int y, int x, char *str);\fR
-.br
-\fBint mvinnstr(int y, int x, char *str, int n);\fR
-.br
-\fBint mvwinstr(WINDOW *win, int y, int x, char *str);\fR
-.br
-\fBint mvwinnstr(WINDOW *win, int y, int x, char *str, int n);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint instr(char *\fIstr\fP);
+\fBint innstr(char *\fIstr\fP, int \fIn\fP);
+\fBint winstr(WINDOW *\fIwin\fP, char *\fIstr\fP);
+\fBint winnstr(WINDOW *\fIwin\fP, char *\fIstr\fP, int \fIn\fP);
+.PP
+\fBint mvinstr(int \fIy\fP, int \fIx\fP, char *\fIstr\fP);
+\fBint mvinnstr(int \fIy\fP, int \fIx\fP, char *\fIstr\fP, int \fIn\fP);
+\fBint mvwinstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, char *\fIstr\fP);
+\fBint mvwinnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, char *\fIstr\fP, int \fIn\fP);
+.fi
.SH DESCRIPTION
-These routines return a string of characters in \fIstr\fR, extracted starting
-at the current cursor position in the named window.
-Attributes are stripped from the characters. The four
-functions with \fIn\fR as the last argument return a leading substring at most
-\fIn\fR characters long (exclusive of the trailing NUL).
+These routines return a string of characters in \fIstr\fP,
+starting at the current cursor position in the named window.
+Attributes are stripped from the characters.
+.PP
+The four functions with \fIn\fP as the last argument return
+a leading substring at most \fIn\fP characters long
+(exclusive of the trailing NUL).
+Transfer stops at the end of the current line, or when \fIn\fP characters have
+been stored at the location referenced by \fIstr\fP.
.SH RETURN VALUE
-All of the functions return \fBERR\fR upon failure,
+All of the functions return \fBERR\fP upon failure,
or the number of characters actually read into the string.
.PP
-X/Open defines no error conditions.
-In this implementation,
-if the window parameter is null or the str parameter is null,
-a zero is returned.
+X/Open Curses defines no error conditions.
+This implementation returns an error
+.bP
+if the \fIwin\fP parameter is null or
+.bP
+if the \fIchstr\fP parameter is null.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
-Note that all routines except \fBwinnstr\fR may be macros.
+All routines except \fBwinnstr\fP may be macros.
+.PP
+Reading a line that overflows the array pointed to by
+\fIstr\fP
+with
+\fBinstr\fP,
+\fBmvinstr\fP,
+\fBmvwinstr\fP
+or
+\fBwinstr\fP
+causes undefined results.
+Therefore, the use of
+\fBinnstr\fP,
+\fBmvinnstr\fP,
+\fBmvwinnstr\fP, or
+\fBwinnstr\fP
+is recommended.
.SH PORTABILITY
SVr4 does not
document whether a length limit includes or excludes the trailing NUL.
.PP
-The ncurses library extends the XSI description by allowing a negative
-value for \fIn\fR.
+The \fI\%ncurses\fP library extends the X/Open Curses description by allowing a
+negative value for \fIn\fP.
In this case, the functions return the string ending at the right margin.
.SH SEE ALSO
-\fBcurses\fR(3X).
+\fB\%curs_ins_wstr\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its wide-character configuration
+.RI ( \%ncursesw ).
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_inch\fP(3X),
+\fB\%curs_inchstr\fP(3X)
diff --git a/man/curs_inwstr.3x b/man/curs_inwstr.3x
index 0cdf4d8..eec361d 100644
--- a/man/curs_inwstr.3x
+++ b/man/curs_inwstr.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 2002-2012,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 *
@@ -26,66 +27,115 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inwstr.3x,v 1.8 2012/11/03 23:03:59 tom Exp $
-.TH curs_inwstr 3X ""
+.\" $Id: curs_inwstr.3x,v 1.41 2024/04/20 21:20:07 tom Exp $
+.TH curs_inwstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBinwstr\fR,
-\fBinnwstr\fR,
-\fBwinwstr\fR,
-\fBwinnwstr\fR,
-\fBmvinwstr\fR,
-\fBmvinnwstr\fR,
-\fBmvwinwstr\fR,
-\fBmvwinnwstr\fR \- get a string of \fBwchar_t\fR characters from a curses window
+\fB\%inwstr\fP,
+\fB\%innwstr\fP,
+\fB\%winwstr\fP,
+\fB\%winnwstr\fP,
+\fB\%mvinwstr\fP,
+\fB\%mvinnwstr\fP,
+\fB\%mvwinwstr\fP,
+\fB\%mvwinnwstr\fP \-
+get a wide-character string from a \fIcurses\fR window
.SH SYNOPSIS
.nf
-\fB#include <curses.h> \fR
-.sp
-\fBint inwstr(\fR\fBwchar_t *\fR\fIstr\fR\fB);\fR
-.br
-\fBint innwstr(\fR\fBwchar_t *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint winwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, wchar_t *\fR\fIstr\fR\fB);\fR
-.br
-\fBint winnwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, wchar_t *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint mvinwstr(\fR\fBint \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIstr\fR\fB);\fR
-.br
-\fBint mvinnwstr(\fR\fBint \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
-.br
-\fBint mvwinwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIstr\fR\fB);\fR
-.br
-\fBint mvwinnwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
+\fB#include <curses.h>
+.PP
+\fBint inwstr(wchar_t *\fIwstr\fP);
+\fBint innwstr(wchar_t *\fIwstr\fP, int \fIn\fP);
+\fBint winwstr(WINDOW *\fIwin\fP, wchar_t *\fIwstr\fP);
+\fBint winnwstr(WINDOW *\fIwin\fP, wchar_t *\fIwstr\fP, int \fIn\fP);
+.PP
+\fBint mvinwstr(int \fIy\fP, int \fIx\fP, wchar_t *\fIwstr\fP);
+\fBint mvinnwstr(int \fIy\fP, int \fIx\fP, wchar_t *\fIwstr\fP, int \fIn\fP);
+\fBint mvwinwstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, wchar_t *\fIwstr\fP);
+\fBint mvwinnwstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, wchar_t *\fIwstr\fP, int \fIn\fP);
.fi
.SH DESCRIPTION
-These routines return a string of \fBwchar_t\fR characters in \fIwstr\fR,
-extracted starting at the current cursor position in the named window.
-Attributes are stripped from the characters.
-The four functions with \fIn\fR as the last argument return a leading substring at most
-\fIn\fR bytes long (exclusive of the trailing NUL).
-Transfer stops at the end of the current line, or when \fIn\fR bytes have
-been stored at the location referenced by \fIwstr\fR.
+These routines return a string of \fBwchar_t\fP wide characters in \fIwstr\fP,
+starting at the current cursor position in the named window.
.PP
-If the size \fIn\fR is not large enough to store a complete character,
+The four functions with \fIn\fP as the last argument return
+a leading substring at most \fIn\fP characters long
+(exclusive of the trailing NUL).
+Transfer stops at the end of the current line, or when \fIn\fP characters have
+been stored at the location referenced by \fIwstr\fP.
+.PP
+If the size \fIn\fP is not large enough to store a complete complex character,
an error is generated.
-.SH NOTES
-Note that all routines except
-\fBwinnwstr\fR
-may be macros.
.SH RETURN VALUE
All routines return
-\fBERR\fR
-upon failure. Upon
-successful completion, the *\fBinwstr\fR
+\fBERR\fP
+upon failure.
+Upon
+successful completion, the *\fBinwstr\fP
routines return
-\fBOK\fR, and the *\fBinnwstr\fR
+\fBOK\fP, and the *\fBinnwstr\fP
routines return the
number of characters read into the string.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+X/Open defines no error conditions.
+This implementation returns an error
+.bP
+if the \fIwin\fP parameter is null or
+.bP
+if the \fIwstr\fP parameter is null, or
+.bP
+if no characters could be read.
+.PP
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
+.SH NOTES
+All routines except
+\fBwinnwstr\fP
+may be macros.
+.PP
+Each cell in the window holds a complex character
+(a spacing character and zero or more non-spacing characters)
+together with attributes and color.
+These functions store only the wide characters,
+ignoring attributes and color.
+Use \fBin_wchstr\fP to return the complex characters from a window.
+.PP
+Reading a line that overflows the array pointed to by
+\fIwstr\fP
+with
+\fBinwstr\fP,
+\fBmvinwstr\fP,
+\fBmvwinwstr\fP
+or
+\fBwinwstr\fP
+causes undefined results.
+Therefore, the use of
+\fBinnwstr\fP,
+\fBmvinnwstr\fP,
+\fBmvwinnwstr\fP, or
+\fBwinnwstr\fP
+is recommended.
+.SH PORTABILITY
+These functions are described in X/Open Curses, Issue 4.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_instr\fR(3X),
-\fBcurs_in_wchstr\fR(3X)
+\fB\%curses\fP(3X),
+\fB\%curs_inch\fP(3X),
+\fB\%curs_inchstr\fP(3X),
+\fB\%curs_instr\fP(3X),
+\fB\%curs_in_wchstr\fP(3X)
diff --git a/man/curs_kernel.3x b/man/curs_kernel.3x
index 664d15d..e85c132 100644
--- a/man/curs_kernel.3x
+++ b/man/curs_kernel.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2015 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -26,109 +27,123 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_kernel.3x,v 1.20 2015/07/21 01:10:11 tom Exp $
+.\" $Id: curs_kernel.3x,v 1.61 2024/04/20 21:24:19 tom Exp $
+.TH curs_kernel 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.TH curs_kernel 3X ""
-.na
-.hy 0
.SH NAME
-\fBdef_prog_mode\fR,
-\fBdef_shell_mode\fR,
-\fBreset_prog_mode\fR,
-\fBreset_shell_mode\fR,
-\fBresetty\fR,
-\fBsavetty\fR,
-\fBgetsyx\fR,
-\fBsetsyx\fR,
-\fBripoffline\fR,
-\fBcurs_set\fR,
-\fBnapms\fR \- low-level \fBcurses\fR routines
-.ad
-.hy
+\fB\%def_prog_mode\fP,
+\fB\%def_shell_mode\fP,
+\fB\%reset_prog_mode\fP,
+\fB\%reset_shell_mode\fP,
+\fB\%resetty\fP,
+\fB\%savetty\fP,
+\fB\%getsyx\fP,
+\fB\%setsyx\fP,
+\fB\%ripoffline\fP,
+\fB\%curs_set\fP,
+\fB\%napms\fP \-
+low-level \fIcurses\fR routines
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint def_prog_mode(void);\fR
-.br
-\fBint def_shell_mode(void);\fR
-.br
-\fBint reset_prog_mode(void);\fR
-.br
-\fBint reset_shell_mode(void);\fR
-.br
-\fBint resetty(void);\fR
-.br
-\fBint savetty(void);\fR
-.br
-\fBvoid getsyx(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR
-.br
-\fBvoid setsyx(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR
-.br
-\fBint ripoffline(int \fP\fIline\fP\fB, int (*\fP\fIinit\fP\fB)(WINDOW *, int));\fR
-.br
-\fBint curs_set(int \fP\fIvisibility\fP\fB);\fR
-.br
-\fBint napms(int \fP\fIms\fP\fB);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint def_prog_mode(void);
+\fBint def_shell_mode(void);
+.PP
+\fBint reset_prog_mode(void);
+\fBint reset_shell_mode(void);
+.PP
+\fBint resetty(void);
+\fBint savetty(void);
+.PP
+\fBvoid getsyx(int \fIy\fP, int \fIx\fP);
+\fBvoid setsyx(int \fIy\fP, int \fIx\fP);
+.PP
+\fBint ripoffline(int \fIline\fP, int (*\fIinit\fP)(WINDOW *, int));
+\fBint curs_set(int \fIvisibility\fP);
+\fBint napms(int \fIms\fP);
+.fi
.SH DESCRIPTION
-The following routines give low-level access to various \fBcurses\fR
-capabilities. These routines typically are used inside library
-routines.
-.SS def_prog_mode, def_shell_mode
-.PP
-The \fBdef_prog_mode\fR and \fBdef_shell_mode\fR routines save the
-current terminal modes as the "program" (in \fBcurses\fR) or "shell"
-(not in \fBcurses\fR) state for use by the \fBreset_prog_mode\fR and
-\fBreset_shell_mode\fR routines. This is done automatically by
-\fBinitscr\fR. There is one such save area for each screen context
-allocated by \fBnewterm()\fR.
-.SS reset_prog_mode, reset_shell_mode
-.PP
-The \fBreset_prog_mode\fR and \fBreset_shell_mode\fR routines restore
-the terminal to "program" (in \fBcurses\fR) or "shell" (out of
-\fBcurses\fR) state. These are done automatically by \fBendwin\fR
-and, after an \fBendwin\fR, by \fBdoupdate\fR, so they normally are
-not called.
-.SS resetty, savetty
-.PP
-The \fBresetty\fR and \fBsavetty\fR routines save and restore the
-state of the terminal modes. \fBsavetty\fR saves the current state in
-a buffer and \fBresetty\fR restores the state to what it was at the
-last call to \fBsavetty\fR.
+The following routines give low-level access
+to various \fBcurses\fP capabilities.
+These routines typically are used inside library routines.
+.SS "def_prog_mode, def_shell_mode"
+The \fBdef_prog_mode\fP and \fBdef_shell_mode\fP routines save the
+current terminal modes as the \*(``program\*(''
+(in \fBcurses\fP) or \*(``shell\*(''
+(not in \fBcurses\fP) state for use by the \fBreset_prog_mode\fP and
+\fBreset_shell_mode\fP routines.
+This is done automatically by \fBinitscr\fP.
+There is one such save area for each screen context
+allocated by \fBnewterm\fP.
+.SS "reset_prog_mode, reset_shell_mode"
+The \fBreset_prog_mode\fP and \fBreset_shell_mode\fP routines restore
+the terminal to \*(``program\*('' (in \fBcurses\fP) or \*(``shell\*('' (out of
+\fBcurses\fP) state.
+These are done automatically by \fBendwin\fP(3X) and,
+after an \fBendwin\fP, by \fBdoupdate\fP,
+so they normally are not called.
+.SS "resetty, savetty"
+The \fBresetty\fP and \fBsavetty\fP routines save and restore the
+state of the terminal modes.
+\fBsavetty\fP saves the current state in
+a buffer and \fBresetty\fP restores the state to what it was at the
+last call to \fBsavetty\fP.
.SS getsyx
+The \fBgetsyx\fP routine returns the current coordinates
+of the \fIvirtual screen\fP cursor in \fIy\fP and \fIx\fP.
+If \fBleaveok\fP is currently \fBTRUE\fP, then
+\fB\-1\fP,\fB\-1\fP is returned.
+If lines have been removed from the top of the
+screen, using \fBripoffline\fP, \fIy\fP and \fIx\fP include these lines;
+therefore, \fIy\fP and \fIx\fP should be used only as arguments for
+\fBsetsyx\fP.
.PP
-The \fBgetsyx\fR routine returns the current coordinates of the virtual screen
-cursor in \fIy\fR and \fIx\fR. If \fBleaveok\fR is currently \fBTRUE\fR, then
-\fB\-1\fR,\fB\-1\fR is returned. If lines have been removed from the top of the
-screen, using \fBripoffline\fR, \fIy\fR and \fIx\fR include these lines;
-therefore, \fIy\fR and \fIx\fR should be used only as arguments for
-\fBsetsyx\fR.
+Few applications will use this feature,
+most use \fBgetyx\fP instead.
.SS setsyx
-.PP
-The \fBsetsyx\fR routine sets the virtual screen cursor to
-\fIy\fR, \fIx\fR. If \fIy\fR and \fIx\fR are both \fB\-1\fR, then
-\fBleaveok\fR is set. The two routines \fBgetsyx\fR and \fBsetsyx\fR
+The \fBsetsyx\fP routine sets
+the \fIvirtual screen\fP cursor to \fIy\fP, \fIx\fP.
+If \fIy\fP and \fIx\fP are both \fB\-1\fP, then
+\fBleaveok\fP is set.
+The two routines \fBgetsyx\fP and \fBsetsyx\fP
are designed to be used by a library routine, which manipulates
-\fBcurses\fR windows but does not want to change the current position
-of the program's cursor. The library routine would call \fBgetsyx\fR
+\fBcurses\fP windows but does not want to change the current position
+of the program's cursor.
+The library routine would call \fBgetsyx\fP
at the beginning, do its manipulation of its own windows, do a
-\fBwnoutrefresh\fR on its windows, call \fBsetsyx\fR, and then call
-\fBdoupdate\fR.
+\fBwnoutrefresh\fP on its windows, call \fBsetsyx\fP, and then call
+\fBdoupdate\fP.
+.PP
+Few applications will use this feature,
+most use \fBwmove\fP instead.
.SS ripoffline
-.PP
-The \fBripoffline\fR routine provides access to the same facility that
-\fBslk_init\fR [see \fBcurs_slk\fR(3X)] uses to reduce the size of the
-screen. \fBripoffline\fR must be called before \fBinitscr\fR or
-\fBnewterm\fR is called, to prepare these initial actions:
+.B \%ripoffline
+provides access to the same facility that \fB\%slk_init\fP(3X) uses to
+reduce the size of the screen.
+\fB\%ripoffline\fP must be called before \fBinitscr\fP or
+\fBnewterm\fP is called, to prepare these initial actions:
.bP
-If \fIline\fR is positive, a line is removed from the top of \fBstdscr\fR.
+If \fIline\fP is positive, a line is removed from the top of \fBstdscr\fP.
.bP
-if \fIline\fR is negative, a line is removed from the bottom.
+if \fIline\fP is negative, a line is removed from the bottom.
.PP
-When the resulting initialization is done inside \fBinitscr\fR, the
-routine \fBinit\fR (supplied by the user) is called with two
+When the resulting initialization is done inside \fBinitscr\fP, the
+routine \fBinit\fP (supplied by the user) is called with two
arguments:
.bP
a window pointer to the one-line window that has been
@@ -136,72 +151,81 @@
.bP
an integer with the number of columns in the window.
.PP
-Inside this initialization routine, the integer variables \fBLINES\fR
-and \fBCOLS\fR (defined in \fB<curses.h>\fR) are not guaranteed to be
-accurate and \fBwrefresh\fR or \fBdoupdate\fR must not be called. It
-is allowable to call \fBwnoutrefresh\fR during the initialization
-routine.
+Inside this initialization routine, the integer variables \fBLINES\fP
+and \fBCOLS\fP (defined in \fB<curses.h>\fP) are not guaranteed to be
+accurate and \fBwrefresh\fP or \fBdoupdate\fP must not be called.
+It is allowable to call \fBwnoutrefresh\fP during the initialization routine.
.PP
-\fBripoffline\fR can be called up to five times before calling \fBinitscr\fR or
-\fBnewterm\fR.
+\fBripoffline\fP can be called up to five times before calling \fBinitscr\fP or
+\fBnewterm\fP.
.SS curs_set
-.PP
-The \fBcurs_set\fR routine sets the cursor state to invisible,
-normal, or very visible for \fBvisibility\fR equal to \fB0\fR,
-\fB1\fR, or \fB2\fR respectively. If the terminal supports the
-\fIvisibility\fR requested, the previous \fIcursor\fR state is
-returned; otherwise, \fBERR\fR is returned.
+The \fBcurs_set\fP routine sets the cursor state to invisible,
+normal, or very visible for \fBvisibility\fP equal to \fB0\fP,
+\fB1\fP, or \fB2\fP respectively.
+If the terminal supports the \fIvisibility\fP requested,
+the previous \fIcursor\fP state is returned;
+otherwise, \fBERR\fP is returned.
.SS napms
-.PP
-The \fBnapms\fR routine is used to sleep for \fIms\fR milliseconds.
+.B \%napms
+sleeps for
+.I ms
+milliseconds.
+If
+.I ms
+exceeds 30,000
+(thirty seconds),
+it is capped at that value.
.SH RETURN VALUE
-Except for \fBcurs_set\fR, these routines always return \fBOK\fR.
+Except for \fBcurs_set\fP, these routines always return \fBOK\fP.
.PP
-\fBcurs_set\fR
-returns the previous cursor state, or \fBERR\fR if the
-requested \fIvisibility\fR is not supported.
+\fBcurs_set\fP
+returns the previous cursor state, or \fBERR\fP if the
+requested \fIvisibility\fP is not supported.
.PP
X/Open defines no error conditions.
In this implementation
.TP 5
-.na
-.hy 0
-\fBdef_prog_mode\fR, \fBdef_shell_mode\fR, \fBreset_prog_mode\fR, \fBreset_shell_mode\fR
-.hy
-.ad
+\fBdef_prog_mode\fP, \fBdef_shell_mode\fP, \fBreset_prog_mode\fP, \fBreset_shell_mode\fP
return an error
if the terminal was not initialized, or
if the I/O call to obtain the terminal settings fails.
.TP 5
\fBripoffline\fP
returns an error if the maximum number of ripped-off lines
-exceeds the maximum (NRIPS = 5).
+exceeds the maximum (5).
.SH NOTES
-Note that \fBgetsyx\fR is a macro, so \fB&\fR is not necessary before
-the variables \fIy\fR and \fIx\fR.
+Note that \fBgetsyx\fP is a macro, so \fB&\fP is not necessary before
+the variables \fIy\fP and \fIx\fP.
.PP
-Older SVr4 man pages warn that the return value of \fBcurs_set\fR "is currently
-incorrect". This implementation gets it right, but it may be unwise to count
+Older SVr4 man pages warn that the return value
+of \fBcurs_set\fP \*(``is currently incorrect\*(''.
+This implementation gets it right, but it may be unwise to count
on the correctness of the return value anywhere else.
.PP
-Both ncurses and SVr4 will call \fBcurs_set\fR in \fBendwin\fR
-if \fBcurs_set\fR
+Both \fI\%ncurses\fP and SVr4 will call \fBcurs_set\fP in \fBendwin\fP
+if \fBcurs_set\fP
has been called to make the cursor other than normal, i.e., either
invisible or very visible.
-There is no way for ncurses to determine the initial cursor state to
-restore that.
+There is no way for \fI\%ncurses\fP to determine the initial cursor
+state to restore that.
.SH PORTABILITY
-The functions \fBsetsyx\fR and \fBgetsyx\fR are not described in the XSI
-Curses standard, Issue 4. All other functions are as described in XSI Curses.
+The \fIvirtual screen\fP functions \fBsetsyx\fP and \fBgetsyx\fP
+are not described in X/Open Curses, Issue 4.
+All other functions are as described in X/Open Curses.
.PP
-The SVr4 documentation describes \fBsetsyx\fR and \fBgetsyx\fR as having return
-type int. This is misleading, as they are macros with no documented semantics
+The SVr4 documentation describes \fBsetsyx\fP and \fBgetsyx\fP
+as having return type int.
+This is misleading, as they are macros with no documented semantics
for the return value.
+.PP
+If interrupted, \fI\%ncurses\fP restarts \fBnapms\fP.
+That, and the limitation to 30 seconds,
+are different from other implementations.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_initscr\fR(3X),
-\fBcurs_outopts\fR(3X),
-\fBcurs_refresh\fR(3X),
-\fBcurs_scr_dump\fR(3X),
-\fBcurs_slk\fR(3X),
-\fBcurs_variables\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_initscr\fP(3X),
+\fB\%curs_outopts\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_scr_dump\fP(3X),
+\fB\%curs_slk\fP(3X),
+\fB\%curs_variables\fP(3X)
diff --git a/man/curs_legacy.3x b/man/curs_legacy.3x
index febaf29..24be01b 100644
--- a/man/curs_legacy.3x
+++ b/man/curs_legacy.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2007,2010 Free Software Foundation, Inc. *
+.\" Copyright 2019-2023,2024 Thomas E. Dickey *
+.\" Copyright 2007-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 *
@@ -26,57 +27,112 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_legacy.3x,v 1.5 2010/12/04 18:38:55 tom Exp $
-.TH curs_legacy 3X ""
+.\" $Id: curs_legacy.3x,v 1.32 2024/03/16 15:35:01 tom Exp $
+.TH curs_legacy 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-getattrs \- get \fBcurses\fR cursor and window coordinates, attributes
+\fB\%getattrs\fP,
+\fB\%getbegx\fP,
+\fB\%getbegy\fP,
+\fB\%getcurx\fP,
+\fB\%getcury\fP,
+\fB\%getmaxx\fP,
+\fB\%getmaxy\fP,
+\fB\%getparx\fP,
+\fB\%getpary\fP \-
+get \fIcurses\fR cursor and window coordinates or attributes (legacy)
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint getattrs(WINDOW *win);\fR
-.br
-\fBint getbegx(WINDOW *win);\fR
-.br
-\fBint getbegy(WINDOW *win);\fR
-.br
-\fBint getcurx(WINDOW *win);\fR
-.br
-\fBint getcury(WINDOW *win);\fR
-.br
-\fBint getmaxx(WINDOW *win);\fR
-.br
-\fBint getmaxy(WINDOW *win);\fR
-.br
-\fBint getparx(WINDOW *win);\fR
-.br
-\fBint getpary(WINDOW *win);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint getattrs(const WINDOW *\fIwin\fP);
+.PP
+\fBint getbegx(const WINDOW *\fIwin\fP);
+\fBint getbegy(const WINDOW *\fIwin\fP);
+.PP
+\fBint getcurx(const WINDOW *\fIwin\fP);
+\fBint getcury(const WINDOW *\fIwin\fP);
+.PP
+\fBint getmaxx(const WINDOW *\fIwin\fP);
+\fBint getmaxy(const WINDOW *\fIwin\fP);
+.PP
+\fBint getparx(const WINDOW *\fIwin\fP);
+\fBint getpary(const WINDOW *\fIwin\fP);
+.fi
.SH DESCRIPTION
-The \fBgetbegy\fR and \fBgetbegx\fR functions return the same
-data as \fBgetbegyx\fR.
-.PP
-The \fBgetcury\fR and \fBgetcurx\fR functions return the same
-data as \fBgetyx\fR.
-.PP
-The \fBgetmaxy\fR and \fBgetmaxx\fR functions return the same
-data as \fBgetmaxyx\fR.
-.PP
-The \fBgetpary\fR and \fBgetparx\fR functions return the same
-data as \fBgetparyx\fR.
+These legacy functions are simpler to use
+than the X/Open \fIcurses\fP functions:
+.bP
+The \fB\%getattrs\fP function returns the same attribute data
+as \fB\%wattr_get\fP.
+.IP
+However, \fB\%getattrs\fP returns an integer (actually a \fB\%chtype\fP),
+while \fB\%wattr_get\fP returns the current color pair in a separate parameter.
+In the wide-character library configuration,
+color pairs may not fit into a \fB\%chtype\fP,
+so \fB\%wattr_get\fP is the only way to obtain the color information.
+.IP
+Because \fB\%getattrs\fP returns the attributes in a single parameter,
+it would not be possible for an application to distinguish that from
+\fBERR\fP (a \fI-1\fP).
+If the window parameter is null, \fB\%getattrs\fP
+returns \fB\%A_NORMAL\fP (zero).
+.bP
+The \fB\%getbegy\fP and \fB\%getbegx\fP functions return the same
+data as \fB\%getbegyx\fP.
+.bP
+The \fB\%getcury\fP and \fB\%getcurx\fP functions return the same
+data as \fB\%getyx\fP.
+.bP
+The \fB\%getmaxy\fP and \fB\%getmaxx\fP functions return the same
+data as \fB\%getmaxyx\fP.
+.bP
+The \fB\%getpary\fP and \fB\%getparx\fP functions return the same
+data as \fB\%getparyx\fP.
.SH RETURN VALUE
-These functions return an integer,
-or ERR if the window parameter is null.
+Except as noted,
+these functions return an integer,
+or \fBERR\fP if the window parameter is null.
.SH NOTES
-All of these interfaces are provided as macros and functions.
-The macros are suppressed (and only the functions provided)
-when \fBNCURSES_OPAQUE\fR is defined.
-The standard forms such as \fBgetyx\fP must be implemented as macros,
-and (in this implementation) are defined in terms of the functions
-described here,
-to avoid reliance on internal details of the WINDOW structure.
+All of these interfaces are implemented as macros and functions.
+The macros are suppressed
+(and only the functions provided)
+in an \*(``opaque\*(''
+.I \%ncurses
+build,
+which defines the preprocessor symbol
+.BR \%NCURSES_OPAQUE .
+See section \*(``ALTERNATE CONFIGURATIONS\*('' in \fB\%ncurses\fP(3X).
+.PP
+The standard forms such as \fB\%getyx\fP
+.I must
+be implemented as macros,
+and
+(in this implementation)
+are defined in terms of the functions described here,
+to avoid reliance on internal details of the \fI\%WINDOW\fP structure.
.SH PORTABILITY
These functions were supported on Version 7, BSD or System V implementations.
+None of those implementations checked the window parameter.
+.PP
+The \fB\%getattrs\fP function and macro are defined to return a (signed) integer
+for compatibility with those implementations
+although an unsigned type would have been more appropriate.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_getyx\fR(3X),
-\fBcurs_opaque\fR(3X)
+\fB\%curses\fP(3X),
+\fB\%curs_getyx\fP(3X),
+\fB\%curs_opaque\fP(3X)
diff --git a/man/curs_memleaks.3x b/man/curs_memleaks.3x
index 5ebc0d0..0626d77 100644
--- a/man/curs_memleaks.3x
+++ b/man/curs_memleaks.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2008,2010 Free Software Foundation, Inc. *
+.\" Copyright 2019-2023,2024 Thomas E. Dickey *
+.\" Copyright 2008-2010,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 *
@@ -26,44 +27,105 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_memleaks.3x,v 1.3 2010/12/04 18:40:45 tom Exp $
-.TH curs_memleaks 3X ""
-.na
-.hy 0
+.\" $Id: curs_memleaks.3x,v 1.35 2024/03/16 15:35:01 tom Exp $
+.TH curs_memleaks 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fB_nc_freeall\fP
-\fB_nc_free_and_exit\fP \- \fBcurses\fR memory-leak checking
-.ad
-.hy
+\fB\%exit_curses\fP,
+\fB\%exit_terminfo\fP \-
+check for memory leaks in \fIcurses\fR
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBvoid _nc_freeall(void);\fR
-.br
-\fBvoid _nc_free_and_exit(int);\fR
+.nf
+\fB#include <curses.h>
+\fBvoid exit_curses(int \fIcode\fP);
+.PP
+\fB#include <term.h>
+\fBvoid exit_terminfo(int \fIcode\fP);
+.PP
+\fI/* deprecated (intentionally not declared in curses.h or term.h) */
+\fBvoid _nc_freeall(void);
+\fBvoid _nc_free_and_exit(int \fIcode\fP);
+\fBvoid _nc_free_tinfo(int \fIcode\fP);
+.fi
.SH DESCRIPTION
-These functions are used to simplify analysis of memory leaks in the ncurses
-library.
-They are normally not available; they must be configured into the library
-at build time using the \fB\-\-disable-leaks\fP option.
-That compiles-in code that frees memory that normally would not be freed.
+These functions are used to simplify analysis of memory leaks in the
+\fI\%ncurses\fP library.
.PP
Any implementation of curses must not free the memory associated with
-a screen, since (even after calling \fBendwin\fP), it must be available
-for use in the next call to \fBrefresh\fP.
+a screen, since (even after calling \fB\%endwin\fP(3X)), it must be available
+for use in the next call to \fB\%refresh\fP(3X).
There are also chunks of memory held for performance reasons.
That makes it hard to analyze curses applications for memory leaks.
-To work around this, one can build a debugging version of the ncurses
-library which frees those chunks which it can, and provides these
-functions to free all of the memory allocated by the ncurses library.
+When using the specially configured debugging version of the
+\fI\%ncurses\fP library,
+applications can call functions which free those chunks of memory,
+simplifying the process of memory-leak checking.
.PP
-The \fP_nc_free_and_exit\fP function is the preferred one since
-some of the memory which is freed may be required for the application
-to continue running.
-Its parameter is the code to pass to the \fPexit\fP routine.
+Some of the functions are named with a \*(``_nc_\*('' prefix
+because they are not intended for use in the non-debugging library:
+.TP 5
+\fB\%_nc_freeall\fP
+This frees (almost) all of the memory allocated by \fI\%ncurses\fP.
+.TP 5
+\fB\%_nc_free_and_exit\fP
+This frees the memory allocated by \fI\%ncurses\fP
+(like \fB\%_nc_freeall\fP),
+and exits the program.
+It is preferred over \fB\%_nc_freeall\fP since some of that memory
+may be required to keep the application running.
+Simply exiting (with the given exit-code) is safer.
+.TP 5
+\fB\%_nc_free_tinfo\fP
+Use this function if only the low-level terminfo functions (and
+corresponding library) are used.
+Like \fB\%_nc_free_and_exit\fP, it exits the program after freeing memory.
+.PP
+The functions prefixed \*(``_nc\*('' are normally not available;
+they must be configured into the library
+at build time using the \fB\%\-\-disable-leaks\fP option.
+That compiles-in code that frees memory that normally would not be freed.
+.PP
+The \fB\%exit_curses\fP and \fB\%exit_terminfo\fP functions
+call \fB\%_nc_free_and_exit\fP and \fB\%_nc_free_tinfo\fP if
+the library is configured to support memory-leak checking.
+If the library is not configured to support memory-leak checking,
+they simply call \fBexit\fP.
.SH RETURN VALUE
These functions do not return a value.
.SH PORTABILITY
-These functions are not part of the XSI interface.
+These functions are not part of X/Open Curses;
+nor do other implementations of curses provide a similar feature.
+.PP
+In any implementation of X/Open Curses, an application can free part
+of the memory allocated by curses:
+.bP
+The portable part of \fB\%exit_curses\fP can be freed using \fB\%delscreen\fP,
+passing the \fISCREEN\fP pointer returned by \fB\%newterm\fP.
+.IP
+In some implementations, there is a global variable \fBsp\fP
+which could be used, e.g., if the screen were only initialized
+using \fB\%initscr\fP.
+.bP
+The portable part of \fB\%exit_terminfo\fP can be freed
+using \fB\%del_curterm\fP.
+.IP
+In this case, there is a global variable \fB\%cur_term\fP which can be
+used as parameter.
.SH SEE ALSO
-\fBcurses\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_initscr\fP(3X),
+\fB\%curs_terminfo\fP(3X)
diff --git a/man/curs_mouse.3x b/man/curs_mouse.3x
index b7cf4c6..8e5c701 100644
--- a/man/curs_mouse.3x
+++ b/man/curs_mouse.3x
@@ -1,6 +1,7 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2014,2015 Free Software Foundation, Inc. *
+.\" 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 *
.\" copy of this software and associated documentation files (the *
@@ -27,81 +28,102 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_mouse.3x,v 1.42 2015/07/21 09:27:39 tom Exp $
+.\" $Id: curs_mouse.3x,v 1.98 2024/04/20 19:02:07 tom Exp $
+.TH curs_mouse 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.TH curs_mouse 3X ""
-.na
-.hy 0
.SH NAME
-\fBhas_mouse\fR,
-\fBgetmouse\fR, \fBungetmouse\fR,
-\fBmousemask\fR, \fBwenclose\fR,
-\fBmouse_trafo\fR, \fBwmouse_trafo\fR,
-\fBmouseinterval\fR \- mouse interface through curses
-.ad
-.hy
+\fB\%has_mouse\fP,
+\fB\%getmouse\fP,
+\fB\%ungetmouse\fP,
+\fB\%mousemask\fP,
+\fB\%wenclose\fP,
+\fB\%mouse_trafo\fP,
+\fB\%wmouse_trafo\fP,
+\fB\%mouseinterval\fP \-
+get mouse events in \fIcurses\fR
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.PP
-\fBtypedef unsigned long mmask_t;\fR
-.PP
.nf
-\fBtypedef struct {\fR
-\fB short id; \fR\fI/* ID to distinguish multiple devices */\fR
-\fB int x, y, z; \fR\fI/* event coordinates */\fR
-\fB mmask_t bstate; \fR\fI/* button state bits */\fR
-\fB} MEVENT;\fR
-.fi
+\fB#include <curses.h>
.PP
-\fBbool has_mouse(void);\fR
-.br
-\fBint getmouse(MEVENT *\fP\fIevent\fP\fB);\fR
-.br
-\fBint ungetmouse(MEVENT *\fP\fIevent\fP\fB);\fR
-.br
-\fBmmask_t mousemask(mmask_t \fP\fInewmask\fP\fB, mmask_t *\fP\fIoldmask\fP\fB);\fR
-.br
-\fBbool wenclose(const WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR
-.br
-\fBbool mouse_trafo(int* \fP\fIpY\fP\fB, int* \fP\fIpX\fP\fB, bool \fP\fIto_screen\fP\fB);\fR
-.br
-\fBbool wmouse_trafo(const WINDOW* \fP\fIwin\fP\fB, int* \fP\fIpY\fP\fB, int* \fP\fIpX\fP\fB,\fR
-.br
- \fBbool \fP\fIto_screen\fP\fB);\fR
-.br
-\fBint mouseinterval(int \fP\fIerval\fP\fB);\fR
-.br
+\fBtypedef unsigned long mmask_t;
+.PP
+\fBtypedef struct {
+\fB short id; \fI/* ID to distinguish multiple devices */
+\fB int x, y, z; \fI/* event coordinates */
+\fB mmask_t bstate; \fI/* button state bits */
+\fB} MEVENT;
+.PP
+\fBbool has_mouse(void);
+.PP
+\fBmmask_t mousemask(mmask_t \fInewmask\fP, mmask_t *\fIoldmask\fP);
+.PP
+\fBint getmouse(MEVENT *\fIevent\fP);
+\fBint ungetmouse(MEVENT *\fIevent\fP);
+.PP
+\fBbool wenclose(const WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
+.PP
+\fBbool mouse_trafo(int* \fIpY\fP, int* \fIpX\fP, bool \fIto_screen\fP);
+\fBbool wmouse_trafo(const WINDOW* \fIwin\fP,
+.ti +18n \" "bool wmouse_trafo("
+\fBint* \fIpY\fB, int* \fIpX\fB, bool \fIto_screen\fB);
+.PP
+\fBint mouseinterval(int \fIerval\fB);\fR
+.fi
.SH DESCRIPTION
These functions provide an interface to mouse events from
-\fBncurses\fR(3X).
-Mouse events are represented by \fBKEY_MOUSE\fR
-pseudo-key values in the \fBwgetch\fR input stream.
+\fB\%ncurses\fP(3X).
+Mouse events are represented by \fB\%KEY_MOUSE\fP
+pseudo-key values in the \fB\%wgetch\fP(3X) input stream.
+.SS has_mouse
+The \fB\%has_mouse\fP function returns \fBTRUE\fP if the mouse driver
+has been successfully initialized,
+and \fBFALSE\fP otherwise.
+.PP
+Mouse events are ignored when input is in cooked mode, and
+cause an error beep when cooked mode is being simulated in a window by a
+function such as \fB\%getstr\fP that expects a linefeed for input-loop
+termination.
.SS mousemask
-.PP
-To make mouse events visible, use the \fBmousemask\fR function.
-This will set
-the mouse events to be reported.
+To make mouse events visible, use the \fB\%mousemask\fP function.
+This sets the mouse events to be reported.
By default, no mouse events are reported.
-The function will return a mask to indicate which of the specified mouse events
-can be reported; on complete failure it returns 0.
-If oldmask is non-NULL,
-this function fills the indicated location with the previous value of the given
-window's mouse event mask.
+.bP
+The function returns an updated copy of \fInewmask\fP
+to indicate which of the specified mouse events can be reported.
+.IP
+If the screen has not been initialized,
+or if the terminal does not support mouse-events,
+this function returns 0.
+.bP
+If \fIoldmask\fP is non-\fBNULL\fP,
+this function fills the indicated location with the previous value of the
+current screen's mouse event mask.
.PP
-As a side effect, setting a zero mousemask may turn off the mouse pointer;
+As a side effect, setting a zero mouse mask may turn off the mouse pointer;
setting a nonzero mask may turn it on.
Whether this happens is device-dependent.
-.SS Mouse events
-.PP
+.SS "Mouse Events"
Here are the mouse event type masks which may be defined:
.PP
.TS
-l l
-_ _
-l l.
-\fIName\fR \fIDescription\fR
+Lb Lb
+Lb Lx.
+Name Description
+=
BUTTON1_PRESSED mouse button 1 down
BUTTON1_RELEASED mouse button 1 up
BUTTON1_CLICKED mouse button 1 clicked
@@ -132,154 +154,156 @@
BUTTON5_DOUBLE_CLICKED mouse button 5 double clicked
BUTTON5_TRIPLE_CLICKED mouse button 5 triple clicked
_
-BUTTON_SHIFT shift was down during button state change
-BUTTON_CTRL control was down during button state change
-BUTTON_ALT alt was down during button state change
+BUTTON_SHIFT T{
+shift was down during button state change
+T}
+BUTTON_CTRL T{
+control was down during button state change
+T}
+BUTTON_ALT T{
+alt was down during button state change
+T}
ALL_MOUSE_EVENTS report all button state changes
REPORT_MOUSE_POSITION report mouse movement
_
.TE
.SS getmouse
-.PP
Once a class of mouse events has been made visible in a window,
-calling the \fBwgetch\fR function on that window may return
-\fBKEY_MOUSE\fR as an indicator that a mouse event has been queued.
+calling the \fB\%wgetch\fP function on that window may return
+\fB\%KEY_MOUSE\fP as an indicator that a mouse event has been queued.
To read the event data and pop the event off the queue, call
-\fBgetmouse\fR.
-This function will return \fBOK\fR if a mouse event
-is actually visible in the given window, \fBERR\fR otherwise.
-When \fBgetmouse\fR returns \fBOK\fR, the data deposited as y and
+\fB\%getmouse\fP.
+This function will return \fBOK\fP if a mouse event
+is actually visible in the given window, \fBERR\fP otherwise.
+When \fB\%getmouse\fP returns \fBOK\fP, the data deposited as y and
x in the event structure coordinates will be screen-relative character-cell
coordinates.
The returned state mask will have exactly one bit set to
indicate the event type.
The corresponding data in the queue is marked invalid.
-A subsequent call to \fBgetmouse\fP will retrieve the next older
+A subsequent call to \fB\%getmouse\fP will retrieve the next older
item from the queue.
.SS ungetmouse
-.PP
-The \fBungetmouse\fR function behaves analogously to \fBungetch\fR.
+The \fB\%ungetmouse\fP function behaves analogously to \fB\%ungetch\fP.
It pushes
-a \fBKEY_MOUSE\fR event onto the input queue, and associates with that event
+a \fB\%KEY_MOUSE\fP event onto the input queue, and associates with that event
the given state data and screen-relative character-cell coordinates.
.SS wenclose
-.PP
-The \fBwenclose\fR function tests whether a given pair of screen-relative
+The \fB\%wenclose\fP function tests whether a given pair of screen-relative
character-cell coordinates is enclosed by a given window, returning \fBTRUE\fP
if it is and \fBFALSE\fP otherwise.
It is useful for determining what subset of
the screen windows enclose the location of a mouse event.
-.SS wmouse_trafo
.PP
-The \fBwmouse_trafo\fR function transforms a given pair of coordinates
-from stdscr-relative coordinates
+If the parameter is a pad,
+\fB\%wenclose\fP uses the most recent screen coordinates used for
+this pad in
+\fB\%prefresh\fP(3X) or
+\fB\%pnoutrefresh\fP(3X).
+.SS wmouse_trafo
+The \fB\%wmouse_trafo\fP function transforms a given pair of coordinates
+from \fB\%stdscr\fP-relative coordinates
to coordinates relative to the given window or vice versa.
-The resulting stdscr-relative coordinates are not always identical
-to window-relative coordinates due to the mechanism to reserve lines on top
-or bottom of the screen for other purposes
-(see the \fBripoffline\fP and \fBslk_init\fR calls, for example).
+The resulting \fB\%stdscr\fP-relative coordinates are not always
+identical to screen coordinates due to the mechanism to reserve
+lines on top or bottom of the screen for other purposes
+(see the \fB\%ripoffline\fP(3X) and \fB\%slk_init\fP(3X) calls, for example).
.bP
-If the parameter \fBto_screen\fR is \fBTRUE\fR, the pointers
-\fBpY, pX\fR must reference the coordinates of a location
-inside the window \fBwin\fR.
-They are converted to window-relative coordinates and returned
+If the parameter \fIto_screen\fP is \fBTRUE\fP, the pointers
+\fIpY, pX\fP must reference the coordinates of a location
+inside the window \fIwin\fP.
+They are converted to \fB\%stdscr\fP-relative coordinates and returned
through the pointers.
-If the conversion was successful, the function returns \fBTRUE\fR.
+If the conversion was successful, the function returns \fBTRUE\fP.
+.IP
+If one of the parameters was \fBNULL\fP or the location is
+not inside the window, \fBFALSE\fP is returned.
.bP
-If one of the parameters was NULL or the location is
-not inside the window, \fBFALSE\fR is returned.
-.bP
-If \fBto_screen\fR is
-\fBFALSE\fR, the pointers \fBpY, pX\fR must reference window-relative
-coordinates.
-They are converted to stdscr-relative coordinates if the
-window \fBwin\fR encloses this point.
-In this case the function returns \fBTRUE\fR.
-.bP
-If one of the parameters is NULL or the point is not inside the
-window, \fBFALSE\fR is returned.
+If \fIto_screen\fP is
+\fBFALSE\fP, the pointers \fIpY, pX\fP must reference
+\fB\%stdscr\fP-relative coordinates.
+They are converted to window-relative coordinates if the
+window \fIwin\fP encloses this point.
+In this case the function returns \fBTRUE\fP.
+.IP
+If one of the parameters is \fBNULL\fP or the point is not inside the
+window, \fBFALSE\fP is returned.
+.PP
The referenced coordinates
are only replaced by the converted coordinates if the transformation was
successful.
.SS mouse_trafo
-.PP
-The \fBmouse_trafo\fR function performs the same translation
-as \fBwmouse_trafo\fR,
-using stdscr for \fBwin\fR.
+The \fB\%mouse_trafo\fP function performs the same translation
+as \fB\%wmouse_trafo\fP,
+using \fB\%stdscr\fP for \fIwin\fP.
.SS mouseinterval
+The \fB\%mouseinterval\fP function sets the maximum time
+(in thousands of a second)
+that can elapse between press and release events for them to
+be resolved as a
+.IR click .
+An application might interpret button press and release events separated
+by more than the mouse interval as a \*(``long press\*('',
+or,
+with motion,
+as a \*(``drag\*(''.
.PP
-The \fBmouseinterval\fR function sets the maximum time (in thousands of a
-second) that can elapse between press and release events for them to
-be recognized as a click.
-Use \fBmouseinterval(0)\fR to disable click resolution.
+Calling \fB\%mouseinterval(0)\fP disables click resolution.
+When
+.I \%ncurses
+detects a mouse event,
+it awaits further input activity up to this interval,
+and then checks for a subsequent mouse event which can be combined
+with the first event.
+If the timeout expires without input activity
+(which would happen with a zero interval),
+then no click resolution will occur.
+.PP
This function returns the previous interval value.
-Use \fBmouseinterval(\-1)\fR to obtain the interval without altering it.
-The default is one sixth of a second.
-.SS has_mouse
+Use \fB\%mouseinterval(\-1)\fP to obtain the interval without altering it.
.PP
-The \fBhas_mouse\fP function returns \fBTRUE\fP if the mouse driver has been
-successfully initialized.
-.PP
-Note that mouse events will be ignored when input is in cooked mode, and will
-cause an error beep when cooked mode is being simulated in a window by a
-function such as \fBgetstr\fR that expects a linefeed for input-loop
-termination.
+The mouse interval is set to one sixth of a second
+when the corresponding screen is initialized,
+e.g., in \fBinitscr\fP(3X) or \fBsetupterm\fP(3X).
.SH RETURN VALUE
-\fBgetmouse\fR and \fBungetmouse\fR
-return the integer \fBERR\fR upon failure or \fBOK\fR
-upon successful completion:
-.RS 3
-.TP 5
-\fBgetmouse\fP
-returns an error.
-.bP
-If no mouse driver was initialized, or
-if the mask parameter is zero,
-.bP
-It also returns an error if no more events remain in the queue.
-.TP 5
-\fBungetmouse\fP
-returns an error if the FIFO is full.
-.RE
+\fB\%has_mouse\fP,
+\fB\%wenclose\fP,
+\fB\%mouse_trafo\fP,
+and
+\fB\%wmouse_trafo\fP
+return \fBTRUE\fP or \fBFALSE\fP as noted above.
.PP
-\fBmousemask\fR
+\fB\%getmouse\fP and \fB\%ungetmouse\fP
+return \fBERR\fP upon failure and \fBOK\fP upon success.
+.PP
+\fB\%getmouse\fP fails if:
+.bP
+no mouse driver was initialized,
+.bP
+the mask of reportable events is zero,
+.bP
+a mouse event was detected that does not match the mask,
+.bP
+or if no more events remain in the queue.
+.PP
+\fB\%ungetmouse\fP returns an error if the event queue is full.
+.PP
+\fB\%mousemask\fP
returns the mask of reportable events.
.PP
-\fBmouseinterval\fR
+\fB\%mouseinterval\fP
returns the previous interval value, unless
the terminal was not initialized.
In that case, it returns the maximum interval value (166).
-.PP
-\fBwenclose\fR and \fBwmouse_trafo\fR
-are boolean functions returning \fBTRUE\fR or \fBFALSE\fR depending
-on their test result.
-.SH PORTABILITY
-These calls were designed for \fBncurses\fR(3X), and are not found in SVr4
-curses, 4.4BSD curses, or any other previous version of curses.
-.PP
-The feature macro \fBNCURSES_MOUSE_VERSION\fR is provided so the preprocessor
-can be used to test whether these features are present.
-If the interface is changed, the value of \fBNCURSES_MOUSE_VERSION\fR will be
-incremented.
-These values for \fBNCURSES_MOUSE_VERSION\fR may be
-specified when configuring ncurses:
-.RS 3
-.TP 3
-1
-has definitions for reserved events.
-The mask uses 28 bits.
-.TP 3
-2
-adds definitions for button 5,
-removes the definitions for reserved events.
-The mask uses 29 bits.
-.RE
-.PP
-The order of the \fBMEVENT\fR structure members is not guaranteed.
+.SH NOTES
+The order of the \fB\%MEVENT\fP structure members is not guaranteed.
Additional fields may be added to the structure in the future.
.PP
-Under \fBncurses\fR(3X), these calls are implemented using either
-xterm's built-in mouse-tracking API or
+Under
+.IR \%ncurses ,
+these calls are implemented using either
+.IR \%xterm 's
+built-in mouse-tracking API or
platform-specific drivers including
.RS 3
.bP
@@ -292,17 +316,31 @@
.PP
If you are using an unsupported configuration,
mouse events will not be visible to
-\fBncurses\fR(3X) (and the \fBmousemask\fR function will always
-return \fB0\fR).
+\fI\%ncurses\fP (and the \fB\%mousemask\fP function will always
+return \fB0\fP).
.PP
-If the terminfo entry contains a \fBXM\fR string,
-this is used in the xterm mouse driver to control the
+If the
+.I \%term\%info
+entry contains a \fBXM\fP string,
+this is used in the
+.I \%xterm
+mouse driver to control the
way the terminal is initialized for mouse operation.
-The default, if \fBXM\fR is not found,
-corresponds to private mode 1000 of xterm:
+The default, if \fBXM\fP is not found,
+corresponds to private mode 1000 of
+.I \%xterm:
.PP
.RS 3
-\\E[?1000%?%p1%{1}%=%th%el%;
+\eE[?1000%?%p1%{1}%=%th%el%;
+.RE
+.PP
+The mouse driver also recognizes a newer
+.I \%xterm
+private mode 1006,
+e.g.,
+.PP
+.RS 3
+\eE[?1006;1000%?%p1%{1}%=%th%el%;
.RE
.PP
The \fIz\fP member in the event structure is not presently used.
@@ -310,32 +348,178 @@
for use with touch screens (which may be pressure-sensitive) or with
3D-mice/trackballs/power gloves.
.PP
-The \fBALL_MOUSE_EVENTS\fP class does not include \fBREPORT_MOUSE_POSITION\fP.
+The \fB\%ALL_MOUSE_EVENTS\fP class does not
+include \fB\%REPORT_MOUSE_POSITION\fP.
They are distinct.
-For example, in xterm,
+For example,
+in
+.IR \%xterm ,
wheel/scrolling mice send position reports as a sequence of
presses of buttons 4 or 5 without matching button-releases.
+.SH EXTENSIONS
+These functions were designed for
+\fB\%ncurses\fP(3X),
+and are not found in SVr4
+.IR curses ,
+4.4BSD
+.IR curses ,
+or any other previous curses implementation.
+(SVr4
+.I curses
+did have a
+.I \%getmouse
+function,
+which took no argument and returned a different type.)
+.SH PORTABILITY
+Applications employing the
+.I \%ncurses
+mouse extension should condition its use on the visibility of the
+.B \%NCURSES_MOUSE_VERSION
+preprocessor macro.
+When the interface changes,
+the macro's value increments.
+Multiple versions are available when
+.I \%ncurses
+is configured;
+see section \*(``ALTERNATE CONFIGURATIONS\*('' of \fB\%ncurses\fP(3X).
+The following values may be specified.
+.RS 3
+.TP 3
+1
+has definitions for reserved events.
+The mask uses 28 bits.
+.TP 3
+2
+adds definitions for button 5,
+removes the definitions for reserved events.
+The mask uses 29 bits.
+.RE
+.PP
+SVr4
+.I curses
+had support for the mouse in a variant of \fI\%xterm\fP(1).
+It is mentioned in a few places,
+with little supporting documentation.
+.bP
+Its \*(``libcurses\*('' manual page lists functions for this feature
+prototyped in \fI\%curses.h\fP.
+.PP
+.RS 8
+.EX
+extern int mouse_set(long int);
+extern int mouse_on(long int);
+extern int mouse_off(long int);
+extern int request_mouse_pos(void);
+extern int map_button(unsigned long);
+extern void wmouse_position(WINDOW *, int *, int *);
+extern unsigned long getmouse(void), getbmap(void);
+.EE
+.RE
+.bP
+Its \*(``terminfo\*('' manual page lists capabilities for the feature.
+.\" These don't appear in in the SVID 4th edition, Volume 3,
+.\" terminfo(TI_ENV) man page. They can be found in, e.g., the "z/OS
+.\" V1R1.0 C Curses" book, Chapter 17, pp. 179-186 (PDF 213-220).
+.RS 8
+.TS
+Lb Lb Lb Lx.
+buttons btns BT T{
+Number of buttons on the mouse
+T}
+get_mouse getm Gm T{
+Curses should get button events
+T}
+key_mouse kmous Km T{
+0631, Mouse event has occurred
+T}
+mouse_info minfo Mi T{
+Mouse status information
+T}
+req_mouse_pos reqmp RQ T{
+Request mouse position report
+T}
+.TE
+.RE
+.bP
+The interface made assumptions
+(as does
+.IR \%ncurses )
+about the escape sequences sent to and received from the terminal.
+.IP
+For instance,
+the SVr4
+.I curses
+library used the \fB\%get_mouse\fP capability to tell the terminal which
+mouse button events it should send,
+passing the mouse-button bit mask to the terminal.
+Also, it could ask the terminal
+where the mouse was using the \fB\%req_mouse_pos\fP capability.
+.IP
+Those features required a terminal program that had been modified
+to work with SVr4
+.IR curses .
+They were not part of the X Consortium's
+.IR \%xterm .
+.PP
+When developing the
+.I \%xterm
+mouse support for
+.I \%ncurses
+in September 1995,
+Eric Raymond was uninterested in using the same interface due to its
+lack of documentation.
+Later, in 1998, Mark Hesseling provided support in
+.I \%PDCurses
+2.3 using the SVr4 interface.
+.IR \%PDCurses ,
+however,
+does not use video terminals,
+making it unnecessary to be concerned about compatibility with the
+escape sequences.
.SH BUGS
-Mouse events under xterm will not in fact be ignored during cooked mode,
-if they have been enabled by \fBmousemask\fR.
-Instead, the xterm mouse
-report sequence will appear in the string read.
+Mouse events from
+.I \%xterm
+are
+.I not
+ignored in cooked mode if they have been enabled by \fB\%mousemask\fP.
+Instead,
+the
+.I \%xterm
+mouse report sequence appears in the string read.
.PP
-Mouse events under xterm will not be detected correctly in a window with
-its keypad bit off, since they are interpreted as a variety of function key.
-Your terminfo description should have \fBkmous\fR set to "\\E[M"
-(the beginning of the response from xterm for mouse clicks).
-Other values for \fBkmous\fR are permitted,
-but under the same assumption,
-i.e., it is the beginning of the response.
+Mouse event reports from
+.I \%xterm
+are not detected correctly in a window with keypad application mode
+disabled,
+since they are interpreted as a variety of function key.
+Set the terminal's
+.I \%term\%info
+capability \fB\%kmous\fP to \*(``\eE[M\*(''
+(the beginning of the response from
+.I \%xterm
+for mouse clicks).
+Other values of \fB\%kmous\fP are permitted under the same assumption,
+that is,
+the report begins with that sequence.
.PP
-Because there are no standard terminal responses that would serve to identify
-terminals which support the xterm mouse protocol, \fBncurses\fR assumes that
-if your $TERM environment variable contains "xterm",
-or \fBkmous\fR is defined in
-the terminal description, then the terminal may send mouse events.
+Because there are no standard response sequences that serve to identify
+terminals supporting the
+.I \%xterm
+mouse protocol,
+.I \%ncurses
+assumes that if \fB\%kmous\fP is defined in the terminal description,
+or if the terminal type's primary name or aliases contain the string
+\%\*(``xterm\*('',
+then the terminal may send mouse events.
+The \fB\%kmous\fP capability is checked first,
+allowing use of newer
+.I \%xterm
+mouse protocols,
+such as its private mode 1006.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_kernel\fR(3X),
-\fBcurs_slk\fR(3X),
-\fBcurs_variables\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_inopts\fP(3X),
+\fB\%curs_kernel\fP(3X),
+\fB\%curs_pad\fP(3X),
+\fB\%curs_slk\fP(3X),
+\fB\%curs_variables\fP(3X)
diff --git a/man/curs_move.3x b/man/curs_move.3x
index 226595c..c3b68e8 100644
--- a/man/curs_move.3x
+++ b/man/curs_move.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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 *
@@ -26,38 +27,62 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_move.3x,v 1.14 2010/12/04 18:40:45 tom Exp $
-.TH curs_move 3X ""
-.na
-.hy 0
+.\" $Id: curs_move.3x,v 1.40 2024/04/27 17:56:05 tom Exp $
+.TH curs_move 3X 2024-04-27 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmove\fR,
-\fBwmove\fR \- move \fBcurses\fR window cursor
-.ad
-.hy
+\fB\%move\fP,
+\fB\%wmove\fP \-
+move cursor in a \fIcurses\fR window
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint move(int y, int x);\fR
-.br
-\fBint wmove(WINDOW *win, int y, int x);\fR
-.br
-.SH DESCRIPTION
-These routines move the cursor associated with the window to line \fIy\fR and
-column \fIx\fR. This routine does not move the physical cursor of the terminal
-until \fBrefresh\fR is called. The position specified is relative to the upper
-left-hand corner of the window, which is (0,0).
-.SH RETURN VALUE
-These routines return \fBERR\fR upon failure and OK (SVr4
-specifies only "an integer value other than \fBERR\fR") upon successful
-completion.
+.nf
+\fB#include <curses.h>
.PP
-Specifically, they return an error
-if the window pointer is null, or
-if the position is outside the window.
+\fBint move(int \fIy\fP, int \fIx\fP);
+\fBint wmove(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
+.fi
+.SH DESCRIPTION
+.B \%wmove
+relocates the cursor associated with the
+.I curses
+window
+.I win
+to line
+.I y
+and column
+.IR x .
+The terminal's cursor does not move until \fB\%refresh\fP(3X) is called.
+The position
+.RI ( y ,
+.IR x )
+is relative to the upper left-hand corner of the window,
+which has coordinates
+(0,\ 0).
+\fB\%ncurses\fP(3X) describes the
+.B \%move
+variant of this function.
+.SH RETURN VALUE
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
+.PP
+They fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
+.PP
+.B \%wmove
+fails if its
+.I \%WINDOW
+pointer argument is
+.BR NULL .
.SH NOTES
-Note that \fBmove\fR may be a macro.
+.B \%move
+may be implemented as a macro.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
+X/Open Curses,
+Issue 4 describes these functions.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_refresh\fR(3X)
+\fB\%curses\fP(3X),
+\fB\%curs_refresh\fP(3X)
diff --git a/man/curs_opaque.3x b/man/curs_opaque.3x
index b395950..fa623ee 100644
--- a/man/curs_opaque.3x
+++ b/man/curs_opaque.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2007-2014,2015 Free Software Foundation, Inc. *
+.\" Copyright 2020-2023,2024 Thomas E. Dickey *
+.\" Copyright 2007-2014,2015 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 *
@@ -26,126 +27,135 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_opaque.3x,v 1.12 2015/04/11 10:23:49 tom Exp $
-.TH curs_opaque 3X ""
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
-.na
-.hy 0
+.\" $Id: curs_opaque.3x,v 1.43 2024/03/16 15:35:01 tom Exp $
+.TH curs_opaque 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-\fBis_cleared\fR,
-\fBis_idlok\fR,
-\fBis_idcok\fR,
-\fBis_immedok\fR,
-\fBis_keypad\fR,
-\fBis_leaveok\fR,
-\fBis_nodelay\fR,
-\fBis_notimeout\fR,
-\fBis_pad\fR,
-\fBis_scrollok\fR,
-\fBis_subwin\fR,
-\fBis_syncok\fR \- \fBcurses\fR window properties
-.ad
-.hy
+\fB\%is_cleared\fP,
+\fB\%is_idlok\fP,
+\fB\%is_idcok\fP,
+\fB\%is_immedok\fP,
+\fB\%is_keypad\fP,
+\fB\%is_leaveok\fP,
+\fB\%is_nodelay\fP,
+\fB\%is_notimeout\fP,
+\fB\%is_pad\fP,
+\fB\%is_scrollok\fP,
+\fB\%is_subwin\fP,
+\fB\%is_syncok\fP,
+\fB\%wgetdelay\fP,
+\fB\%wgetparent\fP,
+\fB\%wgetscrreg\fP \-
+obtain \fIcurses\fR window properties
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBbool is_cleared(const WINDOW *win);\fR
-.br
-\fBbool is_idcok(const WINDOW *win);\fR
-.br
-\fBbool is_idlok(const WINDOW *win);\fR
-.br
-\fBbool is_immedok(const WINDOW *win);\fR
-.br
-\fBbool is_keypad(const WINDOW *win);\fR
-.br
-\fBbool is_leaveok(const WINDOW *win);\fR
-.br
-\fBbool is_nodelay(const WINDOW *win);\fR
-.br
-\fBbool is_notimeout(const WINDOW *win);\fR
-.br
-\fBbool is_pad(const WINDOW *win);\fR
-.br
-\fBbool is_scrollok(const WINDOW *win);\fR
-.br
-\fBbool is_subwin(const WINDOW *win);\fR
-.br
-\fBbool is_syncok(const WINDOW *win);\fR
-.br
-\fBWINDOW * wgetparent(const WINDOW *win);\fR
-.br
-\fBint wgetdelay(const WINDOW *win);\fR
-.br
-\fBint wgetscrreg(const WINDOW *win, int *top, int *bottom);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBbool is_cleared(const WINDOW *\fIwin\fP);
+\fBbool is_idcok(const WINDOW *\fIwin\fP);
+\fBbool is_idlok(const WINDOW *\fIwin\fP);
+\fBbool is_immedok(const WINDOW *\fIwin\fP);
+\fBbool is_keypad(const WINDOW *\fIwin\fP);
+\fBbool is_leaveok(const WINDOW *\fIwin\fP);
+\fBbool is_nodelay(const WINDOW *\fIwin\fP);
+\fBbool is_notimeout(const WINDOW *\fIwin\fP);
+\fBbool is_pad(const WINDOW *\fIwin\fP);
+\fBbool is_scrollok(const WINDOW *\fIwin\fP);
+\fBbool is_subwin(const WINDOW *\fIwin\fP);
+\fBbool is_syncok(const WINDOW *\fIwin\fP);
+.PP
+\fBWINDOW * wgetparent(const WINDOW *\fIwin\fP);
+\fBint wgetdelay(const WINDOW *\fIwin\fP);
+\fBint wgetscrreg(const WINDOW *\fIwin\fP, int *\fItop\fP, int *\fIbottom\fP);
+.fi
.SH DESCRIPTION
-This implementation provides functions which return properties
-set in the WINDOW structure, allowing it to be \*(``opaque\*('' if
-the symbol \fBNCURSES_OPAQUE\fR is defined:
-.TP 5
-\fBis_cleared\fR
-returns the value set in \fBclearok\fR
-.TP 5
-\fBis_idcok\fR
-returns the value set in \fBidcok\fR
-.TP 5
-\fBis_idlok\fR
-returns the value set in \fBidlok\fR
-.TP 5
-\fBis_immedok\fR
-returns the value set in \fBimmedok\fR
-.TP 5
-\fBis_keypad\fR
-returns the value set in \fBkeypad\fR
-.TP 5
-\fBis_leaveok\fR
-returns the value set in \fBleaveok\fR
-.TP 5
-\fBis_nodelay\fR
-returns the value set in \fBnodelay\fR
-.TP 5
-\fBis_notimeout\fR
-returns the value set in \fBnotimeout\fR
-.TP 5
-\fBis_pad\fR
-returns \fBTRUE\fP if the window is a pad
-i.e., created by \fBnewpad\fP
-.TP 5
-\fBis_scrollok\fR
-returns the value set in \fBscrollok\fR
-.TP 5
-\fBis_subwin\fR
+\fI\%ncurses\fP provides functions returning properties of a
+\fI\%WINDOW\fP structure,
+allowing it to be \*(``opaque\*('' if
+the application defines the \fB\%NCURSES_OPAQUE\fP preprocessor symbol.
+\fIOpacity\fP in this sense means that the members of \fIstruct\fP data
+types are not directly accessible
+(for instance,
+through \*(``.\*('' or \*(``\->\*('' operators),
+but instead must be queried and/or set via library functions.
+Advantages of opacity include greater abstraction and improved
+management of concurrent accesses to data structures,
+keeping object states coherent.
+.TP
+\fBis_cleared\fP
+returns the value set by \fB\%clearok\fP(3X).
+.TP
+\fBis_idcok\fP
+returns the value set by \fB\%idcok\fP(3X).
+.TP
+\fBis_idlok\fP
+returns the value set by \fB\%idlok\fP(3X).
+.TP
+\fBis_immedok\fP
+returns the value set by \fB\%immedok\fP(3X).
+.TP
+\fBis_keypad\fP
+returns the value set by \fB\%keypad\fP(3X).
+.TP
+\fBis_leaveok\fP
+returns the value set by \fB\%leaveok\fP(3X).
+.TP
+\fBis_nodelay\fP
+returns the value set by \fB\%nodelay\fP(3X).
+.TP
+\fBis_notimeout\fP
+returns the value set by \fB\%notimeout\fP(3X).
+.TP
+\fBis_pad\fP
+returns \fBTRUE\fP if the window is a pad;
+that is,
+it was created by \fB\%newpad\fP(3X).
+.TP
+\fBis_scrollok\fP
+returns the value set by \fB\%scrollok\fP(3X).
+.TP
+\fBis_subwin\fP
returns \fBTRUE\fP if the window is a subwindow,
-i.e., created by \fBsubwin\fP or \fBderwin\fP
-.TP 5
-\fBis_syncok\fR
-returns the value set in \fBsyncok\fR
-.TP 5
-\fBwgetdelay\fR
-returns the delay timeout as set in \fBwtimeout\fP.
-.TP 5
-\fBwgetparent\fR
-returns the parent WINDOW pointer for subwindows,
-or NULL for windows having no parent.
-.TP 5
-\fBwgetscrreg\fR
-returns the top and bottom rows for the scrolling margin
-as set in \fBwsetscrreg\fP.
+that is,
+it was created by \fB\%subwin\fP(3X) or \fB\%derwin\fP(3X).
+.TP
+\fBis_syncok\fP
+returns the value set by \fB\%syncok\fP(3X).
+.TP
+\fBwgetdelay\fP
+returns the delay timeout set by \fB\%wtimeout\fP(3X).
+.TP
+\fBwgetparent\fP
+returns the parent \fI\%WINDOW\fP pointer for subwindows,
+or \fBNULL\fP for windows having no parent.
+.TP
+\fBwgetscrreg\fP
+stores the the top and bottom rows for the scrolling margin set by
+\fB\%wsetscrreg\fP(3X) in the corresponding arguments,
+returning \fBERR\fP upon failure and \fBOK\fP upon successful
+completion.
.SH RETURN VALUE
-These functions all return \fBTRUE\fP or \fBFALSE\fP, except as noted.
+These functions return \fBTRUE\fP or \fBFALSE\fP except as noted.
.SH NOTES
-Both a macro and a function are provided for each name.
+\fI\%ncurses\fP provides both a C function and a preprocessor macro for
+each function documented in this page.
.SH PORTABILITY
-These routines are specific to ncurses.
+These 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 ncurses extensions
-be conditioned using NCURSES_VERSION.
+It is recommended that any code depending on \fI\%ncurses\fP extensions
+be conditioned using \fB\%NCURSES_VERSION\fP.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_inopts\fR(3X),
-\fBcurs_outopts\fR(3X),
-\fBcurs_window\fR(3X)
+\fB\%curses\fP(3X),
+\fB\%curs_inopts\fP(3X),
+\fB\%curs_outopts\fP(3X),
+\fB\%curs_threads\fP(3X),
+\fB\%curs_window\fP(3X)
diff --git a/man/curs_outopts.3x b/man/curs_outopts.3x
index f6d425b..df263f2 100644
--- a/man/curs_outopts.3x
+++ b/man/curs_outopts.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2015 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -26,68 +27,56 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_outopts.3x,v 1.26 2015/07/21 00:23:43 tom Exp $
-.TH curs_outopts 3X ""
-.na
-.hy 0
+.\" $Id: curs_outopts.3x,v 1.64 2024/04/20 21:24:19 tom Exp $
+.TH curs_outopts 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBclearok\fR,
-\fBidlok\fR,
-\fBidcok\fR,
-\fBimmedok\fR,
-\fBleaveok\fR,
-\fBsetscrreg\fR,
-\fBwsetscrreg\fR,
-\fBscrollok\fR,
-\fBnl\fR,
-\fBnonl\fR \- \fBcurses\fR output options
-.ad
-.hy
+\fB\%clearok\fP,
+\fB\%idlok\fP,
+\fB\%idcok\fP,
+\fB\%immedok\fP,
+\fB\%leaveok\fP,
+\fB\%setscrreg\fP,
+\fB\%wsetscrreg\fP,
+\fB\%scrollok\fP \-
+set \fIcurses\fR output options
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint clearok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
-.br
-\fBint idlok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
-.br
-\fBvoid idcok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
-.br
-\fBvoid immedok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
-.br
-\fBint leaveok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
-.br
-\fBint setscrreg(int \fP\fItop\fP\fB, int \fP\fIbot\fP\fB);\fR
-.br
-\fBint wsetscrreg(WINDOW *\fP\fIwin\fP\fB, int \fP\fItop\fP\fB, int \fP\fIbot\fP\fB);\fR
-.br
-\fBint scrollok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
-.br
-\fBint nl(void);\fR
-.br
-\fBint nonl(void);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint clearok(WINDOW *\fIwin\fP, bool \fIbf\fP);
+\fBint idlok(WINDOW *\fIwin\fP, bool \fIbf\fP);
+\fBvoid idcok(WINDOW *\fIwin\fP, bool \fIbf\fP);
+\fBvoid immedok(WINDOW *\fIwin\fP, bool \fIbf\fP);
+\fBint leaveok(WINDOW *\fIwin\fP, bool \fIbf\fP);
+\fBint scrollok(WINDOW *\fIwin\fP, bool \fIbf\fP);
+.PP
+\fBint setscrreg(int \fItop\fP, int \fIbot\fP);
+\fBint wsetscrreg(WINDOW *\fIwin\fP, int \fItop\fP, int \fIbot\fP);
+.fi
.SH DESCRIPTION
These routines set options that change the style of output within
-\fBcurses\fR.
-All options are initially \fBFALSE\fR, unless otherwise stated.
-It is not necessary to turn these options off before calling \fBendwin\fR.
+\fBcurses\fP.
+All options are initially \fBFALSE\fP, unless otherwise stated.
+It is not necessary to turn these options off before calling \fBendwin\fP(3X).
.SS clearok
-.PP
-If \fBclearok\fR is called with \fBTRUE\fR as argument, the next
-call to \fBwrefresh\fR with this window will clear the screen completely and
+If \fBclearok\fP is called with \fBTRUE\fP as argument, the next
+call to \fBwrefresh\fP with this window will clear the screen completely and
redraw the entire screen from scratch.
This is useful when the contents of the
screen are uncertain, or in some cases for a more pleasing visual effect.
If
-the \fIwin\fR argument to \fBclearok\fR is the global variable \fBcurscr\fR,
-the next call to \fBwrefresh\fR with any window causes the screen to be cleared
+the \fIwin\fP argument to \fBclearok\fP is the global variable \fBcurscr\fP,
+the next call to \fBwrefresh\fP with any window causes the screen to be cleared
and repainted from scratch.
.SS idlok
-.PP
-If \fBidlok\fR is called with \fBTRUE\fR as second argument, \fBcurses\fR
+If \fBidlok\fP is called with \fBTRUE\fP as second argument, \fBcurses\fP
considers using the hardware insert/delete line feature of terminals so
equipped.
-Calling \fBidlok\fR with \fBFALSE\fR as second argument disables use
+Calling \fBidlok\fP with \fBFALSE\fP as second argument disables use
of line insertion and deletion.
This option should be enabled only if the
application needs insert/delete line, for example, for a screen editor.
@@ -95,137 +84,116 @@
disabled by default because insert/delete line tends to be visually annoying
when used in applications where it is not really needed.
If insert/delete line
-cannot be used, \fBcurses\fR redraws the changed portions of all lines.
+cannot be used, \fBcurses\fP redraws the changed portions of all lines.
.SS idcok
-.PP
-If \fBidcok\fR is called with \fBFALSE\fR as second argument, \fBcurses\fR
+If \fBidcok\fP is called with \fBFALSE\fP as second argument, \fBcurses\fP
no longer considers using the hardware insert/delete character feature of
terminals so equipped.
Use of character insert/delete is enabled by default.
-Calling \fBidcok\fR with \fBTRUE\fR as second argument re-enables use
+Calling \fBidcok\fP with \fBTRUE\fP as second argument re-enables use
of character insertion and deletion.
.SS immedok
-.PP
-If \fBimmedok\fR is called with \fBTRUE as argument\fR, any change
-in the window image, such as the ones caused by \fBwaddch, wclrtobot, wscrl\fR,
-etc., automatically cause a call to \fBwrefresh\fR.
-However, it may
-degrade performance considerably, due to repeated calls to \fBwrefresh\fR.
-It is disabled by default.
+If \fBimmedok\fP is called with \fBTRUE\fP as second argument,
+any change in the window image,
+such as the ones caused by \fBwaddch, wclrtobot, wscrl\fP,
+etc., automatically causes a call to \fBwrefresh\fP.
+However, it may degrade performance considerably,
+due to repeated calls to \fBwrefresh\fP.
+Calling \fBimmedok\fP with \fBFALSE\fP as second argument
+restores the default behavior,
+i.e., deferring screen updates until a refresh is needed.
.SS leaveok
-.PP
Normally, the hardware cursor is left at the location of the window cursor
being refreshed.
-The \fBleaveok\fR option allows the cursor to be left
+The \fBleaveok\fP option allows the cursor to be left
wherever the update happens to leave it.
It is useful for applications where
the cursor is not used, since it reduces the need for cursor motions.
-.SS setscrreg
-.PP
-The \fBsetscrreg\fR and \fBwsetscrreg\fR routines allow the application
+.SS scrollok
+The \fBscrollok\fP option controls what happens when the cursor of a window is
+moved off the edge of the window or scrolling region, either as a result of a
+newline action on the bottom line, or typing the last character of the last
+line.
+If disabled, (\fIbf\fP is \fBFALSE\fP), the cursor is left on the bottom
+line.
+If enabled, (\fIbf\fP is \fBTRUE\fP), the window is scrolled up one line
+(Note that to get the physical scrolling effect on the terminal, it is
+also necessary to call \fBidlok\fP).
+.SS "setscrreg, wsetscrreg"
+The \fBsetscrreg\fP and \fBwsetscrreg\fP routines allow the application
programmer to set a software scrolling region in a window.
-The \fItop\fR and
-\fIbot\fR parameters
+The \fItop\fP and
+\fIbot\fP parameters
are the line numbers of the top and bottom margin of the scrolling
region.
(Line 0 is the top line of the window.) If this option and
-\fBscrollok\fR are enabled, an attempt to move off the bottom margin line
+\fBscrollok\fP are enabled, an attempt to move off the bottom margin line
causes all lines in the scrolling region to scroll one line in the direction
of the first line.
Only the text of the window is scrolled.
(Note that this
has nothing to do with the use of a physical scrolling region capability in the
terminal, like that in the VT100.
-If \fBidlok\fR is enabled and the terminal
+If \fBidlok\fP is enabled and the terminal
has either a scrolling region or insert/delete line capability, they will
probably be used by the output routines.)
-.SS scrollok
-.PP
-The \fBscrollok\fR option controls what happens when the cursor of a window is
-moved off the edge of the window or scrolling region, either as a result of a
-newline action on the bottom line, or typing the last character of the last
-line.
-If disabled, (\fIbf\fR is \fBFALSE\fR), the cursor is left on the bottom
-line.
-If enabled, (\fIbf\fR is \fBTRUE\fR), the window is scrolled up one line
-(Note that to get the physical scrolling effect on the terminal, it is
-also necessary to call \fBidlok\fR).
-.SS nl, nonl
-.PP
-The \fBnl\fR and \fBnonl\fR routines control whether the underlying display
-device translates the return key into newline on input, and whether it
-translates newline into return and line-feed on output (in either case, the
-call \fBaddch('\\n')\fR does the equivalent of return and line feed on the
-virtual screen).
-Initially, these translations do occur.
-If you disable them
-using \fBnonl\fR, \fBcurses\fR will be able to make better use of the line-feed
-capability, resulting in faster cursor motion.
-Also, \fBcurses\fR will then be
-able to detect the return key.
.SH RETURN VALUE
-The functions \fBsetscrreg\fR and \fBwsetscrreg\fR return \fBOK\fR upon success
-and \fBERR\fR upon failure.
+The functions \fBsetscrreg\fP and \fBwsetscrreg\fP return \fBOK\fP upon success
+and \fBERR\fP upon failure.
All other routines that return an integer always
-return \fBOK\fR.
+return \fBOK\fP.
.PP
-X/Open Curses does not define any error conditions.
+X/Open Curses does not specify any error conditions.
.PP
-In this implementation, those functions that have a window pointer
-will return an error if the window pointer is null.
-.RS
-.TP 5
-.B wclrtoeol
-returns an error
-if the cursor position is about to wrap.
-.TP 5
-.B wsetscrreg
-returns an error if the scrolling region limits extend outside the window.
-.RE
+In this implementation,
+.bP
+those functions that have a window pointer
+will return an error if the window pointer is null
+.bP
+\fBwsetscrreg\fP
+returns an error if the scrolling region limits extend outside the
+window boundaries.
+.SH NOTES
+Note that
+\fBclearok\fP,
+\fBleaveok\fP,
+\fBscrollok\fP,
+\fBidcok\fP, and
+\fBsetscrreg\fP may be macros.
.PP
-X/Open does not define any error conditions.
-This implementation returns an error
-if the window pointer is null.
+The \fBimmedok\fP routine is useful for windows that are used as terminal
+emulators.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
-.PP
-The XSI Curses standard is ambiguous on the question of whether \fBraw\fR()
-should disable the CRLF translations controlled by \fBnl\fR() and \fBnonl\fR().
-BSD curses did turn off these translations; AT&T curses (at least as late as
-SVr1) did not.
-We choose to do so, on the theory that a programmer requesting
-raw input wants a clean (ideally 8-bit clean) connection that the operating
-system will not alter.
+These functions are described in X/Open Curses, Issue 4.
.PP
Some historic curses implementations had, as an undocumented feature, the
-ability to do the equivalent of \fBclearok(..., 1)\fR by saying
-\fBtouchwin(stdscr)\fR or \fBclear(stdscr)\fR.
-This will not work under
-ncurses.
+ability to do the equivalent of \fBclearok(..., 1)\fP by saying
+\fBtouchwin(stdscr)\fP or \fBclear(stdscr)\fP.
+This will not work under \fI\%ncurses\fP.
.PP
-Earlier System V curses implementations specified that with \fBscrollok\fR
+Earlier System V curses implementations specified that with \fBscrollok\fP
enabled, any window modification triggering a scroll also forced a physical
refresh.
-XSI Curses does not require this, and \fBncurses\fR avoids doing
-it to perform better vertical-motion optimization at \fBwrefresh\fR
+X/Open Curses does not require this, and \fI\%ncurses\fP avoids doing
+it to perform better vertical-motion optimization at \fBwrefresh\fP
time.
.PP
-The XSI Curses standard does not mention that the cursor should be
-made invisible as a side-effect of \fBleaveok\fR.
+X/Open Curses does not mention that the cursor should be
+made invisible as a side-effect of \fBleaveok\fP.
SVr4 curses documentation does this, but the code does not.
-Use \fBcurs_set\fR to make the cursor invisible.
-.SH NOTES
-Note that \fBclearok\fR, \fBleaveok\fR, \fBscrollok\fR, \fBidcok\fR, \fBnl\fR,
-\fBnonl\fR and \fBsetscrreg\fR may be macros.
-.PP
-The \fBimmedok\fR routine is useful for windows that are used as terminal
-emulators.
+Use \fBcurs_set\fP to make the cursor invisible.
+.SH HISTORY
+.I \%ncurses
+formerly treated \fBnl\fP(3X) and \fBnonl\fP(3X) as both input
+.I and
+output options,
+but no longer;
+see \fB\%curs_inopts\fP(3X).
.SH SEE ALSO
-.na
-\fBcurses\fR(3X),
-\fBcurs_addch\fR(3X),
-\fBcurs_clear\fR(3X),
-\fBcurs_initscr\fR(3X),
-\fBcurs_scroll\fR(3X),
-\fBcurs_refresh\fR(3X),
-\fBcurs_variables\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_addch\fP(3X),
+\fB\%curs_clear\fP(3X),
+\fB\%curs_initscr\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_scroll\fP(3X),
+\fB\%curs_variables\fP(3X)
diff --git a/man/curs_overlay.3x b/man/curs_overlay.3x
index e3ed63f..2d4eb72 100644
--- a/man/curs_overlay.3x
+++ b/man/curs_overlay.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2013,2015 Free Software Foundation, Inc. *
+.\" Copyright 2020-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2013,2015 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 *
@@ -26,49 +27,57 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_overlay.3x,v 1.18 2015/07/21 00:51:31 tom Exp $
-.TH curs_overlay 3X ""
-.na
-.hy 0
+.\" $Id: curs_overlay.3x,v 1.43 2024/04/20 21:20:07 tom Exp $
+.TH curs_overlay 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.SH NAME
-\fBoverlay\fR,
-\fBoverwrite\fR,
-\fBcopywin\fR \- overlay and manipulate overlapped \fBcurses\fR windows
-.ad
-.hy
+\fB\%overlay\fP,
+\fB\%overwrite\fP,
+\fB\%copywin\fP \-
+overlay \fIcurses\fR windows and manipulate them
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint overlay(const WINDOW *\fP\fIsrcwin\fP\fB, WINDOW *\fP\fIdstwin\fP\fB);\fR
-.br
-\fBint overwrite(const WINDOW *\fP\fIsrcwin\fP\fB, WINDOW *\fP\fIdstwin\fP\fB);\fR
-.br
-\fBint copywin(const WINDOW *\fP\fIsrcwin\fP\fB, WINDOW *\fP\fIdstwin\fP\fB, int \fP\fIsminrow\fP\fB,\fR
- \fBint \fP\fIsmincol\fP\fB, int \fP\fIdminrow\fP\fB, int \fP\fIdmincol\fP\fB, int \fP\fIdmaxrow\fP\fB,\fR
- \fBint \fP\fIdmaxcol\fP\fB, int \fP\fIoverlay\fP\fB);\fR
-.SH DESCRIPTION
-.SS overlay, overwrite
-The \fBoverlay\fR and \fBoverwrite\fR routines overlay \fIsrcwin\fR on
-top of \fIdstwin\fR.
-\fIscrwin\fR and \fIdstwin\fR are not required
-to be the same size; only text where the two windows overlap is copied.
-The difference is that \fBoverlay\fR is non-destructive
-(blanks are not copied) whereas \fBoverwrite\fR is destructive.
-.SS copywin
+.nf
+\fB#include <curses.h>
.PP
-The \fBcopywin\fR routine provides a finer granularity of control over the
-\fBoverlay\fR and \fBoverwrite\fR routines.
-As in the \fBprefresh\fR routine,
-a rectangle is specified in the destination window, (\fIdminrow\fR,
-\fIdmincol\fR) and (\fIdmaxrow\fR, \fIdmaxcol\fR), and the upper-left-corner
-coordinates of the source window, (\fIsminrow\fR, \fIsmincol\fR).
-If the argument \fIoverlay\fR is \fBtrue\fR,
+\fBint overlay(const WINDOW *\fIsrcwin\fP, WINDOW *\fIdstwin\fP);
+\fBint overwrite(const WINDOW *\fIsrcwin\fP, WINDOW *\fIdstwin\fP);
+\fBint copywin(const WINDOW *\fIsrcwin\fP, WINDOW *\fIdstwin\fP, int \fIsminrow\fP,
+ \fBint \fIsmincol\fB, int \fIdminrow\fB, int \fIdmincol\fB, int \fIdmaxrow\fB,\fR
+ \fBint \fIdmaxcol\fB, int \fIoverlay\fB);\fR
+.fi
+.SH DESCRIPTION
+.SS "overlay, overwrite"
+The \fBoverlay\fP and \fBoverwrite\fP routines overlay \fIsrcwin\fP on
+top of \fIdstwin\fP.
+\fIscrwin\fP and \fIdstwin\fP are not required
+to be the same size; only text where the two windows overlap is copied.
+The difference is that \fBoverlay\fP is non-destructive
+(blanks are not copied) whereas \fBoverwrite\fP is destructive.
+.SS copywin
+The \fBcopywin\fP routine provides a finer granularity of control over the
+\fBoverlay\fP and \fBoverwrite\fP routines.
+As in the \fBprefresh\fP routine,
+a rectangle is specified in the destination window, (\fIdminrow\fP,
+\fIdmincol\fP) and (\fIdmaxrow\fP, \fIdmaxcol\fP), and the upper-left-corner
+coordinates of the source window, (\fIsminrow\fP, \fIsmincol\fP).
+If the argument \fIoverlay\fP is \fBtrue\fP,
then copying is non-destructive,
-as in \fBoverlay\fR.
+as in \fBoverlay\fP.
.SH RETURN VALUE
-Routines that return an integer return \fBERR\fR upon failure, and \fBOK\fR
-(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
-completion.
+These routines return the integer \fBERR\fP upon failure and an \fBOK\fP
+(SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('')
+upon successful completion.
.PP
X/Open defines no error conditions.
In this implementation,
@@ -77,11 +86,13 @@
if either of the window pointers are null, or
if some part of the window would be placed off-screen.
.SH NOTES
-Note that \fBoverlay\fR and \fBoverwrite\fR may be macros.
+Note that \fBoverlay\fP and \fBoverwrite\fP may be macros.
.SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions (adding the const
-qualifiers).
+These functions are described in X/Open Curses, Issue 4,
+which adds \fI\%const\fP qualifiers to the arguments.
It further specifies their behavior in the presence of characters
with multibyte renditions (not yet supported in this implementation).
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_pad\fR(3X), \fBcurs_refresh\fR(3X)
+\fB\%curses\fP(3X),
+\fB\%curs_pad\fP(3X),
+\fB\%curs_refresh\fP(3X)
diff --git a/man/curs_pad.3x b/man/curs_pad.3x
index 52fe51c..21cc405 100644
--- a/man/curs_pad.3x
+++ b/man/curs_pad.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2015 Free Software Foundation, Inc. *
+.\" 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 *
.\" copy of this software and associated documentation files (the *
@@ -26,118 +27,161 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_pad.3x,v 1.18 2015/07/21 08:58:44 tom Exp $
-.TH curs_pad 3X ""
-.na
-.hy 0
+.\" $Id: curs_pad.3x,v 1.61 2024/04/27 17:55:43 tom Exp $
+.TH curs_pad 3X 2024-04-27 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBnewpad\fR,
-\fBsubpad\fR,
-\fBprefresh\fR,
-\fBpnoutrefresh\fR,
-\fBpechochar\fR,
-\fBpecho_wchar\fR \- create and display \fBcurses\fR pads
-.ad
-.hy
+\fB\%newpad\fP,
+\fB\%subpad\fP,
+\fB\%prefresh\fP,
+\fB\%pnoutrefresh\fP,
+\fB\%pechochar\fP,
+\fB\%pecho_wchar\fP \-
+create and display \fIcurses\fR pads
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBWINDOW *newpad(int \fP\fInlines\fP\fB, int \fP\fIncols\fP\fB);\fR
-.br
-\fBWINDOW *subpad(WINDOW *\fP\fIorig\fP\fB, int \fP\fInlines\fP\fB, int \fP\fIncols\fP\fB,\fR
- \fBint \fP\fIbegin_y\fP\fB, int \fP\fIbegin_x\fP\fB);\fR
-.br
-\fBint prefresh(WINDOW *\fP\fIpad\fP\fB, int \fP\fIpminrow\fP\fB, int \fP\fIpmincol\fP\fB,\fR
- \fBint \fP\fIsminrow\fP\fB, int \fP\fIsmincol\fP\fB, int \fP\fIsmaxrow\fP\fB, int \fP\fIsmaxcol\fP\fB);\fR
-.br
-\fBint pnoutrefresh(WINDOW *\fP\fIpad\fP\fB, int \fP\fIpminrow\fP\fB, int \fP\fIpmincol\fP\fB,\fR
- \fBint \fP\fIsminrow\fP\fB, int \fP\fIsmincol\fP\fB, int \fP\fIsmaxrow\fP\fB, int \fP\fIsmaxcol\fP\fB);\fR
-.br
-\fBint pechochar(WINDOW *\fP\fIpad\fP\fB, chtype \fP\fIch\fP\fB);\fR
-.br
-\fBint pecho_wchar(WINDOW *\fP\fIpad\fP\fB, const cchar_t *\fP\fIwch\fP\fB);\fR
+.nf
+\fB#include <curses.h>
+.PP
+\fBWINDOW *newpad(int \fInlines\fP, int \fIncols\fP);
+\fBWINDOW *subpad(WINDOW *\fIparent\fP, int \fInlines\fP, int \fIncols\fP,
+ \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR
+.PP
+\fBint prefresh(WINDOW *\fIpad\fB, int \fIpminrow\fB, int \fIpmincol\fB,\fR
+ \fBint \fIsminrow\fB, int \fIsmincol\fB, int \fIsmaxrow\fB, int \fIsmaxcol\fB);\fR
+\fBint pnoutrefresh(WINDOW *\fIpad\fB, int \fIpminrow\fB, int \fIpmincol\fB,\fR
+ \fBint \fIsminrow\fB, int \fIsmincol\fB, int \fIsmaxrow\fB, int \fIsmaxcol\fB);\fR
+.PP
+\fBint pechochar(WINDOW *\fIpad\fB, chtype \fIch\fB);\fR
+\fBint pecho_wchar(WINDOW *\fIpad\fB, const cchar_t *\fIwch\fB);\fR
+.fi
.SH DESCRIPTION
+A
+.I curses
+.I pad
+is like a window,
+except that it is not restricted by the screen size,
+and is not necessarily associated with a particular part of the screen.
+Pads can be used when a large window is needed,
+only part of which is to be visible on the screen.
+Pads are not automatically refreshed by scrolling or input-echoing
+operations.
+.PP
+Pads cannot be refreshed with \fB\%wrefresh\fP(3X);
+use
+.B \%prefresh
+or
+.B \%pnoutrefresh
+instead.
.SS newpad
-The \fBnewpad\fR routine creates and returns a pointer to a new pad data
-structure with the given number of lines, \fInlines\fR, and columns,
-\fIncols\fR.
-A pad is like a window, except that it is not restricted by the
-screen size, and is not necessarily associated with a particular part of the
-screen.
-Pads can be used when a large window is needed, and only a part of the
-window will be on the screen at one time.
-Automatic refreshes of pads
-(e.g., from scrolling or echoing of input) do not occur.
-It is not
-legal to call \fBwrefresh\fR with a \fIpad\fR as an argument; the routines
-\fBprefresh\fR or \fBpnoutrefresh\fR should be called instead.
-Note that these
-routines require additional parameters to specify the part of the pad to be
-displayed and the location on the screen to be used for the display.
+\fB\%newpad\fP creates and returns a pointer to a new pad data structure
+with the given number of lines,
+.IR nlines ,
+and columns,
+.IR ncols .
.SS subpad
+.B \%subpad
+creates and returns a pointer to a subwindow within a pad
+with the given number of lines,
+.IR nlines ,
+and columns,
+.IR ncols .
+Unlike \fB\%subwin\fP(3X),
+which uses screen coordinates,
+the new pad is placed at position
+.RI ( begin_y ,
+.IR begin_x )
+relative to its parent.
+Thus,
+changes made to one pad can affect both.
+When operating on a subpad,
+it is often necessary to call \fB\%touchwin\fP(3X) or
+\fB\%touchline\fP(3X) on
+.I parent
+before calling
+.BR \%prefresh .
+.SS "prefresh, pnoutrefresh"
+.B \%prefresh\fP
+and
+.B \%pnoutrefresh
+are analogous to \fB\%wrefresh\fP(3X) and \fB\%wnoutrefresh\fP(3X)
+except that they operate on pads rather than windows.
+They require additional parameters are needed to indicate what portions
+of the pad and screen are involved.
+.bP
+.I pminrow
+and
+.I pmincol
+specify the upper left-hand corner of a rectangular view of the pad.
+.bP
+.IR sminrow ,
+.IR smincol ,
+.IR smaxrow ,
+and
+.I smaxcol
+specify the vertices of the rectangle to be displayed on the screen.
.PP
-The \fBsubpad\fR routine creates and returns a pointer to a subwindow within a
-pad with the given number of lines, \fInlines\fR, and columns, \fIncols\fR.
-Unlike \fBsubwin\fR, which uses screen coordinates, the window is at position
-(\fIbegin\fR_\fIx\fR\fB,\fR \fIbegin\fR_\fIy\fR) on the pad.
-The window is
-made in the middle of the window \fIorig\fR, so that changes made to one window
-affect both windows.
-During the use of this routine, it will often be
-necessary to call \fBtouchwin\fR or \fBtouchline\fR on \fIorig\fR before
-calling \fBprefresh\fR.
-.SS prefresh, pnoutrefresh
-.PP
-The \fBprefresh\fR and \fBpnoutrefresh\fR routines are analogous to
-\fBwrefresh\fR and \fBwnoutrefresh\fR except that they relate to pads instead
-of windows.
-The additional parameters are needed to indicate what part of the
-pad and screen are involved.
-The \fIpminrow\fR and \fIpmincol\fR parameters specify the upper
-left-hand corner of the rectangle to be displayed in the pad.
-The \fIsminrow\fR,
-\fIsmincol\fR, \fIsmaxrow\fR, and \fIsmaxcol\fR
-parameters specify the edges of the
-rectangle to be displayed on the screen.
-The lower right-hand corner of the
-rectangle to be displayed in the pad is calculated from the screen coordinates,
+The lower right-hand corner
+of the rectangle to be displayed in the pad
+is calculated from the screen coordinates,
since the rectangles must be the same size.
-Both rectangles must be entirely
-contained within their respective structures.
-Negative values of
-\fIpminrow\fR, \fIpmincol\fR, \fIsminrow\fR, or \fIsmincol\fR are treated as if
-they were zero.
+Both rectangles must be entirely contained
+within their respective structures.
+.I curses
+treats
+negative values of any of these parameters as zero.
.SS pechochar
-.PP
-The \fBpechochar\fR routine is functionally equivalent to a call to \fBaddch\fR
-followed by a call to \fBrefresh\fR, a call to \fBwaddch\fR followed by a call
-to \fBwrefresh\fR, or a call to \fBwaddch\fR followed by a call to
-\fBprefresh\fR.
-The knowledge that only a single character is being output is
-taken into consideration and, for non-control characters, a considerable
-performance gain might be seen by using these routines instead of their
-equivalents.
-In the case of \fBpechochar\fR, the last location of the pad on
-the screen is reused for the arguments to \fBprefresh\fR.
+.B \%pechochar
+is functionally equivalent to calling \fB\%waddch\fP(3X) followed by
+.BR \%prefresh .
+It suggests to the
+.I curses
+optimizer that only a single character is being output;
+a considerable performance benefit may be thus enjoyed.
+The location of the character
+.I ch
+written to the pad is used to populate the arguments to
+.BR \%prefresh .
.SS pecho_wchar
-.PP
-The \fBpecho_wchar\fR function is the analogous wide-character
-form of \fBpechochar\fR.
-It outputs one character to a pad and immediately refreshes the pad.
-It does this by a call to \fBwadd_wch\fR followed by a call to \fBprefresh\fR.
+.B \%pecho_wchar\fP
+is functionally equivalent to calling \fB\%wadd_wch\fP(3X) followed by
+.BR \%prefresh .
+It suggests to the
+.I curses
+optimizer that only a single wide character is being output;
+a considerable performance benefit may be thus enjoyed.
+The location of the character
+.I wch
+written to the pad is used to populate the arguments to
+.BR \%prefresh .
.SH RETURN VALUE
-Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
-(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
-completion.
+Functions that return an integer return \fBERR\fP upon failure and
+\fBOK\fP
+(SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('')
+upon successful completion.
.PP
-Routines that return pointers return \fBNULL\fR on error, and set \fBerrno\fR
-to \fBENOMEM\fR.
+Functions that return pointers return \fBNULL\fP on error,
+and set \fB\%errno\fP to \fB\%ENOMEM\fP.
.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
-\fBprefresh\fP and \fBpnoutrefresh\fP
+\fB\%prefresh\fP and \fB\%pnoutrefresh\fP
return an error
if the window pointer is null, or
if the window is not really a pad or
@@ -147,16 +191,90 @@
\fBpechochar\fP
returns an error
if the window is not really a pad, and the associated call
-to \fBwechochar\fP returns an error.
+to \fB\%wechochar\fP returns an error.
.TP 5
\fBpecho_wchar\fP
returns an error
if the window is not really a pad, and the associated call
-to \fBwecho_wchar\fP returns an error.
+to \fB\%wecho_wchar\fP returns an error.
.RE
.SH NOTES
-Note that \fBpechochar\fR may be a macro.
+\fB\%pechochar\fP may be a macro.
.SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions.
+BSD \fIcurses\fP has no \fIpad\fP feature.
+.PP
+SVr2 \fIcurses\fP (1986) provided the \fB\%newpad\fP and related functions,
+documenting them in a single line each.
+SVr3 (1987) provided more extensive documentation.
+.PP
+The documentation does not explain the term \fIpad\fP.
+However, the Apollo \fIAegis\fP workstation operating system
+supported a graphical \fIpad\fP feature:
+.bP
+These graphical pads could be much larger than the computer's display.
+.bP
+The read-only output from a command could be scrolled back to inspect,
+and select text from the pad.
+.PP
+The two uses may be related.
+.PP
+X/Open Curses, Issue 4 describes these functions,
+without significant change from the SVr3 documentation.
+It describes no error conditions.
+The behavior of \fB\%subpad\fP if the parent window is not
+a pad is undocumented,
+and is not checked by the vendor Unix implementations:
+.bP
+SVr4 \fIcurses\fP sets a flag in the \fI\%WINDOW\fP structure in
+\fB\%newpad\fP which tells if the window is a \fIpad\fP.
+.IP
+However, it uses this information only in
+\fB\%waddch\fP (to decide if it should call \fB\%wrefresh\fP) and
+\fB\%wscrl\fP (to avoid scrolling a pad),
+and does not check in \fB\%wrefresh\fP to ensure that the pad
+is refreshed properly.
+.bP
+Solaris \fI\%xcurses\fP checks whether a window is a pad in
+\fB\%wnoutrefresh\fP,
+returning \fBERR\fP in that case.
+.IP
+However,
+it only sets the flag for subwindows if the parent window is a pad.
+Its \fB\%newpad\fP function does not set this information.
+Consequently, the check will never fail.
+.IP
+It makes no comparable check in \fB\%pnoutrefresh\fP,
+though interestingly enough, a comment in the source code
+states that the lack of a check was an MKS extension.
+.bP
+NetBSD 7 \fIcurses\fP
+sets a flag in the \fI\%WINDOW\fP structure
+for \fB\%newpad\fP and \fB\%subpad\fP,
+using this to help with the distinction between \fB\%wnoutrefresh\fP
+and \fB\%pnoutrefresh\fP.
+.IP
+It does not check for the case where a subwindow is created in
+a pad using \fB\%subwin\fP or \fB\%derwin\fP.
+.IP
+The \fB\%dupwin\fP function returns a regular window when duplicating a pad.
+Likewise, \fB\%getwin\fP always returns a window, even if the saved
+data was from a pad.
+.PP
+This implementation
+.bP
+sets a flag in the \fI\%WINDOW\fP structure
+for \fB\%newpad\fP and \fB\%subpad\fP,
+.bP
+allows a \fB\%subwin\fP or \fB\%derwin\fP call to succeed having a pad parent by
+forcing the subwindow to be a pad,
+.bP
+checks in both \fB\%wnoutrefresh\fP and \fB\%pnoutrefresh\fP to ensure
+that pads and windows are handled distinctly, and
+.bP
+ensures that \fB\%dupwin\fP and \fB\%getwin\fP treat
+pads versus windows consistently.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_refresh\fR(3X), \fBcurs_touch\fR(3X), \fBcurs_addch\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_addch\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_touch\fP(3X)
diff --git a/man/curs_print.3x b/man/curs_print.3x
index 31a4535..3694bef 100644
--- a/man/curs_print.3x
+++ b/man/curs_print.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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 *
@@ -26,43 +27,63 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_print.3x,v 1.10 2010/12/04 18:40:45 tom Exp $
-.TH curs_print 3X ""
+.\" $Id: curs_print.3x,v 1.38 2024/03/16 15:35:01 tom Exp $
+.TH curs_print 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmcprint\fR \- ship binary data to printer
+\fB\%mcprint\fP \-
+write binary data to printer using \fIterminfo\fR capabilities
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint mcprint(char *data, int len);\fR
+.nf
+\fB#include <curses.h>
+.PP
+\fBint mcprint(char *\fIdata\fP, int \fIlen\fP);
+.fi
.SH DESCRIPTION
-This function uses the \fBmc5p\fR or \fBmc4\fR and \fBmc5\fR capabilities,
+This function uses the \fBmc5p\fP or \fBmc4\fP and \fBmc5\fP capabilities,
if they are present, to ship given data to a printer attached to the terminal.
.PP
-Note that the \fBmcprint\fR code has no way to do flow control with the printer
-or to know how much buffering it has. Your application is responsible for
+Note that the \fB\%mcprint\fP code has no way
+to do flow control with the printer
+or to know how much buffering it has.
+Your application is responsible for
keeping the rate of writes to the printer below its continuous throughput rate
-(typically about half of its nominal cps rating). Dot-matrix printers and
+(typically about half of its nominal cps rating).
+Dot-matrix printers and
6-page-per-minute lasers can typically handle 80cps, so a good conservative
rule of thumb is to sleep for a second after shipping each 80-character line.
.
.SH RETURN VALUE
-The \fBmcprint\fR function returns \fBERR\fR if the write operation aborted
-for some reason. In this case, errno will contain either an error associated
-with \fBwrite(2)\fR or one of the following:
+The \fB\%mcprint\fP function returns \fBERR\fP if the write operation aborted
+for some reason.
+In this case, \fB\%errno\fP will contain either an error associated
+with \fBwrite\fP(2) or one of the following:
.TP 5
-ENODEV
+\fBENODEV\fP
Capabilities for printer redirection do not exist.
.TP 5
-ENOMEM
+\fBENOMEM\fP
Couldn't allocate sufficient memory to buffer the printer write.
.PP
-When \fBmcprint\fR succeeds, it returns the number of characters actually
+When \fB\%mcprint\fP succeeds, it returns the number of characters actually
sent to the printer.
+.SH EXTENSIONS
+\fB\%mcprint\fP was designed for
+\fB\%ncurses\fP(3X),
+and was not found in SVr4
+.IR curses ,
+4.4BSD
+.IR curses ,
+or any other previous curses implementation.
.SH PORTABILITY
-The \fBmcprint\fR call was designed for \fBncurses\fR(3X), and is not found
-in SVr4 curses, 4.4BSD curses, or any other previous version of curses.
+Applications employing this
+.I \%ncurses
+extension should condition its use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
.SH BUGS
-Padding in the \fBmc5p\fR, \fBmc4\fR and \fBmc5\fR capabilities will not be
-interpreted.
+Padding in the
+\fBmc5p\fP,
+\fBmc4\fP, and
+\fBmc5\fP capabilities is not interpreted.
.SH SEE ALSO
-\fBcurses\fR(3X)\fR
+\fB\%curses\fP(3X)
diff --git a/man/curs_printw.3x b/man/curs_printw.3x
index 9918f9d..282536b 100644
--- a/man/curs_printw.3x
+++ b/man/curs_printw.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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 *
@@ -26,67 +27,179 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_printw.3x,v 1.20 2010/12/04 18:40:45 tom Exp $
-.TH curs_printw 3X ""
-.na
-.hy 0
+.\" $Id: curs_printw.3x,v 1.53 2024/04/20 19:18:18 tom Exp $
+.TH curs_printw 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBprintw\fR,
-\fBwprintw\fR,
-\fBmvprintw\fR,
-\fBmvwprintw\fR,
-\fBvwprintw\fR, \fBvw_printw\fR \- print formatted output in \fBcurses\fR windows
-.ad
-.hy
+\fB\%printw\fP,
+\fB\%wprintw\fP,
+\fB\%mvprintw\fP,
+\fB\%mvwprintw\fP,
+\fB\%vwprintw\fP,
+\fB\%vw_printw\fP \-
+write formatted output to a \fIcurses\fR window
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint printw(const char *fmt, ...);\fR
-.br
-\fBint wprintw(WINDOW *win, const char *fmt, ...);\fR
-.br
-\fBint mvprintw(int y, int x, const char *fmt, ...);\fR
-.br
-\fBint mvwprintw(WINDOW *win, int y, int x, const char *fmt, ...);\fR
-.br
-\fBint vwprintw(WINDOW *win, const char *fmt, va_list varglist);\fR
-.br
-\fBint vw_printw(WINDOW *win, const char *fmt, va_list varglist);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint printw(const char *\fIfmt\fP, ...);
+\fBint wprintw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, ...);
+\fBint mvprintw(int \fIy\fP, int \fIx\fP, const char *\fIfmt\fP, ...);
+\fBint mvwprintw(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const char *\fIfmt\fP, ...);
+.PP
+\fBint vw_printw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, va_list \fIvarglist\fP);
+.PP
+\fI/* obsolete */\fP
+\fBint vwprintw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, va_list \fIvarglist\fP);
+.fi
.SH DESCRIPTION
-The \fBprintw\fR, \fBwprintw\fR, \fBmvprintw\fR and \fBmvwprintw\fR
-routines are analogous to \fBprintf\fR [see \fBprintf\fR(3)]. In
-effect, the string that would be output by \fBprintf\fR is output
-instead as though \fBwaddstr\fR were used on the given window.
+\fB\%printw\fP,
+\fB\%wprintw\fP,
+\fB\%mvprintw\fP,
+and
+\fB\%mvwprintw\fP
+are analogous to \fI\%printf\fP(3).
+In effect,
+the string that would be output by \fI\%printf\fP(3) is instead output
+as though \fB\%waddstr\fP(3X) were used with
+.I win
+(or
+.BR \%stdscr )
+as its first argument.
.PP
-The \fBvwprintw\fR and \fBwv_printw\fR routines are analogous
-to \fBvprintf\fR [see \fBprintf\fR(3)]
-and perform a \fBwprintw\fR using a variable argument list.
-The third argument is a \fBva_list\fR, a pointer to a
-list of arguments, as defined in \fB<stdarg.h>\fR.
+\fB\%vwprintw\fP
+and
+\fB\%vw_printw\fP are analogous to \fI\%vprintf\fP(3),
+and perform a \fB\%wprintw\fP using a variable argument list.
+The third argument is a \fI\%va_list\fP,
+a pointer to a list of arguments,
+as defined in \fI\%stdarg.h\fP.
.SH RETURN VALUE
-Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
-(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
-completion.
+These functions return
+.B ERR
+upon failure and
+.B OK
+upon success.
.PP
-X/Open defines no error conditions.
-In this implementation,
-an error may be returned if it cannot allocate enough memory for the
-buffer used to format the results.
-It will return an error if the window pointer is null.
+In
+.IR \%ncurses ,
+failure occurs if the library cannot allocate enough memory for the
+buffer into which the output is formatted,
+or if the window pointer
+.I win
+is null.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
+.SH NOTES
+No wide character counterpart functions are defined by the
+\*(``wide\*(''
+.I \%ncurses
+configuration nor by any standard.
+To format and write a wide-character string to a
+.I curses
+window,
+consider using \fI\%swprintf\fP(3) and \fB\%waddwstr\fP(3X) or similar.
.SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions. The function
-\fBvwprintw\fR is marked TO BE WITHDRAWN, and is to be replaced by a function
-\fBvw_printw\fR using the \fB<stdarg.h>\fR interface.
-The Single Unix Specification, Version 2 states that
-\fBvw_printw\fR is preferred to \fBvwprintw\fR since the latter requires
-including \fB<varargs.h>\fR, which
-cannot be used in the same file as \fB<stdarg.h>\fR.
-This implementation uses \fB<stdarg.h>\fR for both, because that header
-is included in \fB<curses.h\fR>.
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+.PP
+.I \%ncurses
+defines \fB\%vw_printw\fP and \fB\%vwprintw\fP identically to support
+legacy applications.
+However,
+the latter is obsolete.
+.bP
+X/Open Curses,
+Issue 4 Version 2 (1996),
+marked \fB\%vwprintw\fP as requiring \fI\%varargs.h\fP and
+\*(``TO BE WITHDRAWN\*('',
+and specified \fB\%vw_printw\fP using the \fI\%stdarg.h\fP interface.
+.bP
+X/Open Curses, Issue 5, Draft 2
+(December 2007) marked \fBvwprintw\fP (along with
+\fBvwscanw\fP and the \fItermcap\fP interface) as withdrawn.
+After incorporating review comments,
+this became
+X/Open Curses, Issue 7 (2009).
+.bP
+.I \%ncurses
+provides \fB\%vwprintw\fP,
+but marks it as deprecated.
+.SH HISTORY
+While \fB\%printw\fP was implemented in 4BSD
+(November 1980),
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
+.\" libcurses/printw.c
+it was unused until 4.2BSD
+(August 1983),
+which employed it for games.
+That early version of
+.I curses
+preceded the ANSI C standard of 1989.
+It did not use \fI\%varargs.h\fP,
+though that had been available since Seventh Edition Unix (1979).
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/\
+.\" varargs.h
+In 1991
+(a couple of years after SVr4 was generally available,
+and after the C standard was published),
+other developers updated the library,
+using \fI\%stdarg.h\fP internally in 4.4BSD
+.IR curses .
+Even with this improvement,
+BSD
+.I curses
+did not use function prototypes
+(nor even declare functions)
+in \fI\%curses.h\fP until 1992.
+.PP
+SVr2 (1984) documented \fB\%printw\fP and \fB\%wprintw\fP tersely as
+\*(``printf on \fB\%stdscr\fP\*('' and
+\*(``printf on \fIwin\fP\*('',
+respectively.
+.PP
+SVr3 (1987) added \fB\%mvprintw\fP and \fB\%mvwprintw\fP,
+with a three-line summary asserting that they were analogous to
+\fI\%printf\fP(3),
+explaining that the string that \fI\%printf\fP(3) would write to the
+standard output stream would instead be output using \fB\%waddstr\fP to
+the given window.
+SVr3 also implemented \fB\%vwprintw\fP,
+describing its third parameter as a \fI\%va_list\fP,
+defined in \fI\%varargs.h\fP,
+and referred the reader to the manual pages for \fI\%varargs\fP and
+\fI\%vprintf\fP for detailed descriptions.
+.PP
+SVr4 (1989) introduced no new variations of \fI\%printw\fP,
+but provided for using either \fI\%varargs.h\fP or \fI\%stdarg.h\fP to
+define the \fI\%va_list\fP type.
+.\" either header declares "va_list", but only one can be used
+.PP
+X/Open Curses, Issue 4 (1995),
+defined \fB\%vw_printw\fP to replace \fB\%vwprintw\fP,
+stating that its \fI\%va_list\fP type is defined in \fI\%stdarg.h\fP.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBprintf\fR(3), \fBvprintf(3)\fR
+\fB\%curses\fP(3X),
+\fB\%curs_addstr\fP(3X),
+\fB\%curs_scanw\fP(3X),
+\fB\%printf\fP(3),
+\fB\%vprintf\fP(3)
diff --git a/man/curs_refresh.3x b/man/curs_refresh.3x
index e1552c3..ac81d1e 100644
--- a/man/curs_refresh.3x
+++ b/man/curs_refresh.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2005,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2016 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 *
@@ -26,91 +27,115 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_refresh.3x,v 1.15 2010/12/04 18:38:55 tom Exp $
-.TH curs_refresh 3X ""
-.na
-.hy 0
+.\" $Id: curs_refresh.3x,v 1.46 2024/04/20 21:20:07 tom Exp $
+.TH curs_refresh 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBdoupdate\fR,
-\fBredrawwin\fR,
-\fBrefresh\fR,
-\fBwnoutrefresh\fR,
-\fBwredrawln\fR,
-\fBwrefresh\fR \- refresh \fBcurses\fR windows and lines
-.ad
-.hy
+\fB\%doupdate\fP,
+\fB\%redrawwin\fP,
+\fB\%refresh\fP,
+\fB\%wnoutrefresh\fP,
+\fB\%wredrawln\fP,
+\fB\%wrefresh\fP \-
+refresh \fIcurses\fR windows or lines thereupon
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint refresh(void);\fR
-.br
-\fBint wrefresh(WINDOW *win);\fR
-.br
-\fBint wnoutrefresh(WINDOW *win);\fR
-.br
-\fBint doupdate(void);\fR
-.br
-\fBint redrawwin(WINDOW *win);\fR
-.br
-\fBint wredrawln(WINDOW *win, int beg_line, int num_lines);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint refresh(void);
+\fBint wrefresh(WINDOW *\fIwin\fP);
+\fBint wnoutrefresh(WINDOW *\fIwin\fP);
+\fBint doupdate(void);
+.PP
+\fBint redrawwin(WINDOW *\fIwin\fP);
+\fBint wredrawln(WINDOW *\fIwin\fP, int \fIbeg_line\fP, int \fInum_lines\fP);
+.fi
.SH DESCRIPTION
-The \fBrefresh\fR and \fBwrefresh\fR routines (or \fBwnoutrefresh\fR and
-\fBdoupdate\fR) must be called to get actual output to the terminal, as other
-routines merely manipulate data structures.
-The routine \fBwrefresh\fR copies
-the named window to the physical terminal screen, taking into account what is
-already there to do optimizations.
-The \fBrefresh\fR routine is the
-same, using \fBstdscr\fR as the default window.
-Unless \fBleaveok\fR has been
+.SS "refresh, wrefresh"
+The \fBrefresh\fP and \fBwrefresh\fP routines (or \fBwnoutrefresh\fP and
+\fBdoupdate\fP) must be called to get actual output to the terminal,
+as other routines merely manipulate data structures.
+The routine \fBwrefresh\fP copies
+the named window to the \fIphysical screen\fP,
+taking into account what is already there to do optimizations.
+The \fBrefresh\fP routine is the
+same, using \fBstdscr\fP as the default window.
+Unless \fBleaveok\fP(3X) has been
enabled, the physical cursor of the terminal is left at the location of the
cursor for that window.
-.PP
-The \fBwnoutrefresh\fR and \fBdoupdate\fR routines allow multiple updates with
-more efficiency than \fBwrefresh\fR alone.
+.SS "wnoutrefresh, doupdate"
+The \fBwnoutrefresh\fP and \fBdoupdate\fP routines allow multiple updates with
+more efficiency than \fBwrefresh\fP alone.
In addition to all the window
-structures, \fBcurses\fR keeps two data structures representing the terminal
-screen: a physical screen, describing what is actually on the screen, and a
-virtual screen, describing what the programmer wants to have on the screen.
+structures, \fBcurses\fP keeps two data structures representing the terminal
+screen:
+.bP
+a \fIphysical screen\fP,
+describing what is actually on the screen, and
+.bP
+a \fIvirtual screen\fP,
+describing what the programmer wants to have on the screen.
.PP
-The routine \fBwrefresh\fR works by first calling \fBwnoutrefresh\fR, which
-copies the named window to the virtual screen, and then calling \fBdoupdate\fR,
-which compares the virtual screen to the physical screen and does the actual
-update.
+The routine \fBwrefresh\fP works by
+.bP
+first calling \fBwnoutrefresh\fP,
+which copies the named window to the \fIvirtual screen\fP, and
+.bP
+then calling \fBdoupdate\fP, which compares
+the \fIvirtual screen\fP to the \fIphysical screen\fP
+and does the actual update.
+.PP
If the programmer wishes to output several windows at once, a series
-of calls to \fBwrefresh\fR results in alternating calls to \fBwnoutrefresh\fR
-and \fBdoupdate\fR, causing several bursts of output to the screen.
+of calls to \fBwrefresh\fP results in alternating calls to \fBwnoutrefresh\fP
+and \fBdoupdate\fP, causing several bursts of output to the screen.
By first
-calling \fBwnoutrefresh\fR for each window, it is then possible to call
-\fBdoupdate\fR once, resulting in only one burst of output, with fewer total
+calling \fBwnoutrefresh\fP for each window, it is then possible to call
+\fBdoupdate\fP once, resulting in only one burst of output, with fewer total
characters transmitted and less CPU time used.
-If the \fIwin\fR argument to
-\fBwrefresh\fR is the global variable \fBcurscr\fR, the screen is immediately
-cleared and repainted from scratch.
.PP
-The phrase "copies the named window to the virtual screen" above is ambiguous.
-What actually happens is that all \fItouched\fR (changed) lines in the window
+If the \fIwin\fP argument to
+\fBwrefresh\fP is the \fIphysical screen\fP
+(i.e., the global variable \fBcurscr\fP),
+the screen is immediately cleared and repainted from scratch.
+.PP
+The phrase \*(``copies the named window
+to the virtual screen\*('' above is ambiguous.
+What actually happens is that all \fItouched\fP (changed) lines in the window
are copied to the virtual screen.
This affects programs that use overlapping
windows; it means that if two windows overlap, you can refresh them in either
order and the overlap region will be modified only when it is explicitly
changed.
-(But see the section on \fBPORTABILITY\fR below for a warning about
+(But see the section on \fBPORTABILITY\fP below for a warning about
exploiting this behavior.)
-.PP
-The \fBwredrawln\fR routine indicates to \fBcurses\fR that some screen lines
+.SS "wredrawln, redrawwin"
+The \fBwredrawln\fP routine indicates to \fBcurses\fP that some screen lines
are corrupted and should be thrown away before anything is written over them.
It touches the indicated lines (marking them changed).
-The routine \fBredrawwin\fR() touches the entire window.
+The routine \fBredrawwin\fP touches the entire window.
.SH RETURN VALUE
-Routines that return an integer return \fBERR\fR upon failure, and \fBOK\fR
-(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
-completion.
+These routines return the integer \fBERR\fP upon failure and \fBOK\fP
+(SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('')
+upon successful completion.
.PP
-X/Open does not define any error conditions.
+X/Open Curses does not specify any error conditions.
In this implementation
-.RS
+.RS 3
.TP 5
\fBwnoutrefresh\fP
returns an error
@@ -122,19 +147,19 @@
if the associated call to \fBtouchln\fP returns an error.
.RE
.SH NOTES
-Note that \fBrefresh\fR and \fBredrawwin\fR may be macros.
+Note that \fBrefresh\fP and \fBredrawwin\fP may be macros.
.SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions.
+X/Open Curses, Issue 4 describes these functions.
.PP
-Whether \fBwnoutrefresh()\fR copies to the virtual screen the entire contents
+Whether \fBwnoutrefresh\fP copies to the virtual screen the entire contents
of a window or just its changed portions has never been well-documented in
historic curses versions (including SVr4).
It might be unwise to rely on
either behavior in programs that might have to be linked with other curses
implementations.
-Instead, you can do an explicit \fBtouchwin()\fR before the
-\fBwnoutrefresh()\fR call to guarantee an entire-contents copy anywhere.
+Instead, you can do an explicit \fBtouchwin\fP before the
+\fBwnoutrefresh\fP call to guarantee an entire-contents copy anywhere.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_outopts\fR(3X)
-\fBcurs_variables\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_outopts\fP(3X)
+\fB\%curs_variables\fP(3X)
diff --git a/man/curs_scanw.3x b/man/curs_scanw.3x
index a3208f5..409c297 100644
--- a/man/curs_scanw.3x
+++ b/man/curs_scanw.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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 *
@@ -26,70 +27,229 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_scanw.3x,v 1.17 2010/12/04 18:40:45 tom Exp $
-.TH curs_scanw 3X ""
+.\" $Id: curs_scanw.3x,v 1.53 2024/04/20 19:18:18 tom Exp $
+.TH curs_scanw 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBscanw\fR,
-\fBwscanw\fR,
-\fBmvscanw\fR,
-\fBmvwscanw\fR,
-\fBvwscanw\fR, \fBvw_scanw\fR \- convert formatted input from a \fBcurses\fR window
+\fB\%scanw\fP,
+\fB\%wscanw\fP,
+\fB\%mvscanw\fP,
+\fB\%mvwscanw\fP,
+\fB\%vwscanw\fP,
+\fB\%vw_scanw\fP \-
+read formatted input from a \fIcurses\fR window
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint scanw(char *fmt, ...);\fR
-.br
-\fBint wscanw(WINDOW *win, char *fmt, ...);\fR
-.br
-\fBint mvscanw(int y, int x, char *fmt, ...);\fR
-.br
-\fBint mvwscanw(WINDOW *win, int y, int x, char *fmt, ...);\fR
-.br
-\fBint vw_scanw(WINDOW *win, char *fmt, va_list varglist);\fR
-.br
-\fBint vwscanw(WINDOW *win, char *fmt, va_list varglist);\fR
+.nf
+\fB#include <curses.h>
+.PP
+\fBint scanw(const char *\fIfmt\fP, ...);
+\fBint wscanw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, ...);
+\fBint mvscanw(int \fIy\fP, int \fIx\fP, const char *\fIfmt\fP, ...);
+\fBint mvwscanw(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const char *\fIfmt\fP, ...);
+.PP
+\fBint vw_scanw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, va_list \fIvarglist\fP);
+.PP
+\fI/* obsolete */\fP
+\fBint vwscanw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, va_list \fIvarglist\fP);
+.fi
.SH DESCRIPTION
-The \fBscanw\fR, \fBwscanw\fR and \fBmvscanw\fR routines are analogous to
-\fBscanf\fR [see \fBscanf\fR(3)]. The effect of these routines is as though
-\fBwgetstr\fR were called on the window, and the resulting line used as input
-for \fBsscanf\fR(3). Fields which do not map to a variable in the \fIfmt\fR
-field are lost.
+\fB\%scanw\fP,
+\fB\%wscanw\fP,
+\fB\%mvscanw\fP,
+and
+\fB\%mvwscanw\fP
+are analogous to \fI\%scanf\fP(3).
+In effect,
+they call \fB\%wgetstr\fP(3X) with
+.I win
+(or
+.BR \%stdscr )
+as its first argument,
+then attempt conversion of the resulting string with \fI\%vsscanf\fP(3).
+Fields in the string that do not map to a variable in the \fIfmt\fP
+parameter are discarded.
.PP
-The \fBvwscanw\fR and \fBvw_scanw\fR routines are analogous to \fBvscanf\fR.
-They perform a \fBwscanw\fR using a variable argument list.
-The third argument is a \fIva_list\fR,
-a pointer to a list of arguments, as defined in \fB<stdarg.h>\fR.
+\fB\%vwscanw\fP
+and
+\fB\%vw_scanw\fP are analogous to \fI\%vscanf\fP(3),
+and perform a \fB\%wscanw\fP using a variable argument list.
+The third argument is a \fI\%va_list\fP,
+a pointer to a list of arguments,
+as defined in \fI\%stdarg.h\fP.
.SH RETURN VALUE
-\fBvwscanw\fR returns \fBERR\fR on failure and an integer equal to the
-number of fields scanned on success.
+These functions return
+.B ERR
+upon failure and otherwise a count of successful conversions;
+this quantity may be zero.
.PP
-Applications may use the return value from the \fBscanw\fR, \fBwscanw\fR,
-\fBmvscanw\fR and \fBmvwscanw\fR routines to determine the number of fields
-which were mapped in the call.
+In
+.IR \%ncurses ,
+failure occurs if \fI\%vsscanf\fP(3) returns
+\fBEOF\fP,
+or if the window pointer
+.I win
+is null.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
+.SH NOTES
+No wide character counterpart functions are defined by the
+\*(``wide\*(''
+.I \%ncurses
+configuration nor by any standard.
+They are unnecessary:
+to retrieve and convert a wide-character string from a
+.I curses
+terminal keyboard,
+use these functions with the \fI\%scanf\fP(3) conversions \*(``%lc\*(''
+and \*(``%ls\*('' for wide characters and strings,
+respectively.
+.PP
+.I \%ncurses
+implements \fI\%vsscanf\fP(3) internally if it is unavailable when the
+library is configured.
.SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions. The function
-\fBvwscanw\fR is marked TO BE WITHDRAWN, and is to be replaced by a function
-\fBvw_scanw\fR using the \fB<stdarg.h>\fR interface.
-The Single Unix Specification, Version 2 states that
-\fBvw_scanw\fR is preferred to \fBvwscanw\fR since the latter requires
-including \fB<varargs.h>\fR, which
-cannot be used in the same file as \fB<stdarg.h>\fR.
-This implementation uses \fB<stdarg.h>\fR for both, because that header
-is included in \fB<curses.h\fR>.
-.LP
-Both XSI and The Single Unix Specification, Version 2 state that these
-functions return ERR or OK.
-Since the underlying \fBscanf\fR can return the number of items scanned,
-and the SVr4 code was documented to use this feature,
-this is probably an editing error which was introduced in XSI,
-rather than being done intentionally.
-Portable applications should only test if the return value is ERR,
-since the OK value (zero) is likely to be misleading.
-One possible way to get useful results would be to use a "%n" conversion
-at the end of the format string to ensure that something was processed.
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+.PP
+.I \%ncurses
+defines \fB\%vw_scanw\fP and \fB\%vwscanw\fP identically to support
+legacy applications.
+However,
+the latter is obsolete.
+.bP
+X/Open Curses,
+Issue 4 Version 2 (1996),
+marked \fB\%vwscanw\fP as requiring \fI\%varargs.h\fP and
+\*(``TO BE WITHDRAWN\*('',
+and specified \fB\%vw_scanw\fP using the \fI\%stdarg.h\fP interface.
+.bP
+X/Open Curses,
+Issue 5,
+Draft 2 (December 2007) marked \fB\%vwscanw\fP (along with
+\fB\%vwscanw\fP and the \fItermcap\fP interface) as withdrawn.
+After incorporating review comments,
+this became
+X/Open Curses, Issue 7 (2009).
+.bP
+.I \%ncurses
+provides \fB\%vwscanw\fP,
+but marks it as deprecated.
+.PP
+X/Open Curses Issues 4 and 7 both state that these functions return
+\fBERR\fP or \fBOK\fP.
+This is likely an erratum.
+.bP
+Since the underlying \fI\%scanf\fP(3) returns the number of successful
+conversions,
+and SVr4
+.I curses
+was documented to use this feature,
+this may have been an editorial solecism introduced by X/Open,
+rather than an intentional change.
+.bP
+This implementation retains compatibility with SVr4
+.IR curses .
+As of 2018,
+NetBSD
+.I curses
+also returns the number of successful conversions.
+Both
+.I \%ncurses\fP
+and NetBSD
+.I curses
+call \fI\%vsscanf\fP(3) to scan the string,
+which returns \fBEOF\fP on error.
+.bP
+Portable applications should test only if the return value is \fBERR\fP,
+and not compare it to \fBOK\fP,
+since that value (zero) might be misleading.
+.IP
+One portable way to get useful results would be to use a \*(``%n\*(''
+conversion at the end of the format string,
+and check the value of the corresponding variable to determine how many
+conversions succeeded.
+.SH HISTORY
+\fB\%scanw\fP was implemented in 4BSD
+(November 1980);
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
+.\" libcurses/scanw.c
+that early version of
+.I curses
+preceded the ANSI C standard of 1989.
+The function was unused in Berkeley distributions for over ten years,
+until 4.4BSD,
+which employed it in a game.
+The 4BSD \fB\%scanw\fP did not use \fI\%varargs.h\fP,
+though that had been available since Seventh Edition Unix (1979).
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/\
+.\" varargs.h
+In 1991
+(a couple of years after SVr4 was generally available,
+and after the C standard was published),
+other developers updated the library,
+using \fI\%stdarg.h\fP internally in 4.4BSD
+.IR curses .
+Even with this improvement,
+BSD
+.I curses
+did not use function prototypes
+(nor even declare functions)
+in \fI\%curses.h\fP until 1992.
+.PP
+SVr2 (1984) documented \fB\%scanw\fP and \fB\%wscanw\fP tersely as
+\*(``scanf through \fB\%stdscr\fP\*('' and
+\*(``scanf through \fIwin\fP\*('',
+respectively.
+.PP
+SVr3 (1987) added
+\fB\%mvscanw\fP, and
+\fB\%mvwscanw\fP, stating
+.RS
+.PP
+\*(``[t]hese routines correspond to \fIscanf\fP(3S),
+as do their arguments and return values.
+\fB\%wgetstr\fP() is called on the window,
+and the resulting line is used as input for the scan.\*(''
+.RE
+.PP
+SVr3 also implemented \fB\%vwscanw\fP,
+describing its third parameter as a \fI\%va_list\fP,
+defined in \fI\%varargs.h\fP,
+and referred the reader to the manual pages for \fI\%varargs\fP and
+\fI\%vprintf\fP for detailed descriptions.
+(Because the SVr3 documentation does not mention \fI\%vscanf\fP,
+the reference to \fI\%vprintf\fP might not be an error).
+.PP
+SVr4 (1989) introduced no new variations of \fI\%scanw\fP,
+but provided for using either \fI\%varargs.h\fP or \fI\%stdarg.h\fP to
+define the \fI\%va_list\fP type.
+.\" either header declares "va_list", but only one can be used
+.PP
+X/Open Curses, Issue 4 (1995),
+defined \fI\%vw_scanw\fP to replace \fI\%vwscanw\fP,
+stating that its \fI\%va_list\fP type is defined in \fI\%stdarg.h\fP.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_getstr\fR(3X), \fBcurs_printw\fR(3X), \fBscanf\fR(3)
+\fB\%curses\fP(3X),
+\fB\%curs_getstr\fP(3X),
+\fB\%curs_printw\fP(3X),
+\fB\%scanf\fP(3),
+\fB\%vscanf\fP(3)
diff --git a/man/curs_scr_dump.3x b/man/curs_scr_dump.3x
index df3e79c..5f14a22 100644
--- a/man/curs_scr_dump.3x
+++ b/man/curs_scr_dump.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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 *
@@ -26,71 +27,126 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_scr_dump.3x,v 1.9 2010/12/04 18:40:45 tom Exp $
-.TH curs_scr_dump 3X ""
-.na
-.hy 0
+.\" $Id: curs_scr_dump.3x,v 1.43 2024/04/20 18:54:36 tom Exp $
+.TH curs_scr_dump 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBscr_dump\fR,
-\fBscr_restore\fR,
-\fBscr_init\fR,
-\fBscr_set\fR \- read (write) a \fBcurses\fR screen from (to) a file
-.ad
-.hy
+\fB\%scr_dump\fP,
+\fB\%scr_restore\fP,
+\fB\%scr_init\fP,
+\fB\%scr_set\fP \-
+read/write a \fIcurses\fR screen from/to a file
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint scr_dump(const char *filename);\fR
-.br
-\fBint scr_restore(const char *filename);\fR
-.br
-\fBint scr_init(const char *filename);\fR
-.br
-\fBint scr_set(const char *filename);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint scr_dump(const char *\fIfilename\fP);
+\fBint scr_restore(const char *\fIfilename\fP);
+\fBint scr_init(const char *\fIfilename\fP);
+\fBint scr_set(const char *\fIfilename\fP);
+.fi
.SH DESCRIPTION
-The \fBscr_dump\fR routine dumps the current contents of the virtual screen
-to the file \fIfilename\fR.
+.I curses
+provides applications the ability to write the contents of the screen
+to a file and read them back.
+To read/write a window
+(rather than the whole screen)
+from/to a file,
+use \fB\%getwin\fP(3X) and
+\fB\%putwin\fP(3X),
+respectively.
+.SS scr_dump
+\fB\%scr_dump\fP writes to
+.I filename
+the contents of the virtual screen;
+see \fB\%curscr\fP(3X).
+.SS scr_restore
+\fB\%scr_restore\fP updates the virtual screen to contain the contents
+of
+.I filename
+(if it was validly written with \fB\%scr_dump\fP).
+No refresh is performed;
+after performing any further desired updates,
+call \fB\%doupdate\fP(3X) or similar.
+.SS scr_init
+\fB\%scr_init\fP reads
+.IR filename ,
+using it to initialize
+.I curses
+data structures describing the state of the terminal screen.
+If these data are valid,
+.I curses
+bases its next update of the screen on this information rather than
+clearing it and starting from scratch.
.PP
-The \fBscr_restore\fR routine sets the virtual screen to the contents
-of \fIfilename\fR, which must have been written using \fBscr_dump\fR. The next
-call to \fBdoupdate\fR restores the screen to the way it looked in the dump
-file.
+The data fail the validity check
+.bP
+if the terminal employs
+.I \%term\%info
+capabilities
+.B \%exit_ca_mode
+.RB ( \%rmcup )
+or
+.B \%non_rev_rmcup
+.RB ( \%nrrmc )
+are defined,
+or
+.bP
+if
+.I curses
+knows that the terminal has been written to since the preceding
+\fB\%scr_dump\fP call.
.PP
-The \fBscr_init\fR routine reads in the contents of \fIfilename\fR and uses
-them to initialize the \fBcurses\fR data structures about what the terminal
-currently has on its screen. If the data is determined to be valid,
-\fBcurses\fR bases its next update of the screen on this information rather
-than clearing the screen and starting from scratch. \fBscr_init\fR is used
-after \fBinitscr\fR or a \fBsystem\fR call to share
-the screen with another process which has done a \fBscr_dump\fR after its
-\fBendwin\fR call. The data is declared invalid if the terminfo capabilities
-\fBrmcup\fR and \fBnrrmc\fR exist; also if the terminal has been written to
-since the preceding \fBscr_dump\fR call.
-.PP
-The \fBscr_set\fR routine is a combination of \fBscr_restore\fR and
-\fBscr_init\fR. It tells the program that the information in \fIfilename\fR is
+\fB\%scr_init\fP could be used after \fB\%initscr\fP(3X) or
+\fB\%system\fP(3) to share the screen with another process that has
+done a \fBscr_dump\fP after \fB\%endwin\fP(3X).
+.SS scr_set
+The \fBscr_set\fP routine is a combination of \fBscr_restore\fP and
+\fBscr_init\fP. It tells the program that the information in \fIfilename\fP is
what is currently on the screen, and also what the program wants on the screen.
This can be thought of as a screen inheritance function.
-.PP
-To read (write) a window from (to) a file, use the \fBgetwin\fR and
-\fBputwin\fR routines [see \fBcurs_util\fR(3X)].
.SH RETURN VALUE
-All routines return the integer \fBERR\fR upon failure and \fBOK\fR
-upon success.
+These functions return \fBOK\fP on success and \fBERR\fP on failure.
.PP
-X/Open defines no error conditions.
+X/Open defines no failure conditions.
In this implementation,
-each will return an error if the file cannot be opened.
+each function fails if it cannot open
+.IR filename .
.SH NOTES
-Note that \fBscr_init\fR, \fBscr_set\fR, and \fBscr_restore\fR may be macros.
+\fB\%scr_init\fP,
+\fB\%scr_set\fP,
+and
+\fB\%scr_restore\fP may be macros.
.SH PORTABILITY
-The XSI Curses standard, Issue 4, describes these functions (adding the const
-qualifiers).
+X/Open Curses,
+Issue 4 describes these functions.
.PP
-The SVr4 docs merely say under \fBscr_init\fR that the dump data is also
-considered invalid "if the time-stamp of the tty is old" but do not define
-"old".
+.\" SVID 4, p. 529
+SVr4 omitted the
+.I \%const
+qualifiers.
+.PP
+SVr4 documentation describes \fB\%scr_init\fP such that the dump data is
+also considered invalid \*(``if the time-stamp of the tty is old\*(''
+but does not define \*(``old\*(''.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_refresh\fR(3X),
-\fBcurs_util\fR(3X), \fBsystem\fR(3)
+\fB\%curses\fP(3X),
+\fB\%curs_initscr\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_util\fP(3X),
+\fB\%system\fP(3),
+\fB\%scr_dump\fP(5)
diff --git a/man/curs_scroll.3x b/man/curs_scroll.3x
index 2cb152d..16d5a50 100644
--- a/man/curs_scroll.3x
+++ b/man/curs_scroll.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2006,2010 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 *
@@ -26,65 +27,111 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_scroll.3x,v 1.15 2010/12/04 18:40:45 tom Exp $
-.TH curs_scroll 3X ""
-.na
-.hy 0
+.\" $Id: curs_scroll.3x,v 1.43 2024/04/20 18:54:36 tom Exp $
+.TH curs_scroll 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBscroll\fR,
-\fBscrl\fR,
-\fBwscrl\fR \- scroll a \fBcurses\fR window
-.ad
-.hy
+\fB\%scroll\fP,
+\fB\%scrl\fP,
+\fB\%wscrl\fP \-
+scroll a \fIcurses\fR window
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint scroll(WINDOW *win);\fR
-.br
-\fBint scrl(int n);\fR
-.br
-\fBint wscrl(WINDOW *win, int n);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint scroll(WINDOW *\fIwin\fP);
+.PP
+\fBint scrl(int \fIn\fP);
+\fBint wscrl(WINDOW *\fIwin\fP, int \fIn\fP);
+.fi
.SH DESCRIPTION
-The \fBscroll\fR routine scrolls the window up one line.
-This involves moving
-the lines in the window data structure.
-As an optimization, if the scrolling
-region of the window is the entire screen, the physical screen may be scrolled
-at the same time.
+\fBscroll\fP scrolls the given window up one line.
+That is,
+every visible line we might number
+.I i
+becomes line
+.IR i "\-1."
+The text of the top line in the window disappears and the bottom line
+is populated with blank characters;
+see \fB\%bkgd\fP(3X) or \fB\%bkgrnd\fP(3X).
+As an optimization,
+if the scrolling region of the window is the entire screen,
+the physical screen may be scrolled at the same time;
+see \fB\%curscr\fP(3X).
.PP
-For positive \fIn\fR, the \fBscrl\fR and \fBwscrl\fR routines scroll the
-window up \fIn\fR lines (line \fIi\fR+\fIn\fR becomes \fIi\fR); otherwise
-scroll the window down \fIn\fR lines.
-This involves moving the lines in the
-window character image structure.
-The current cursor position is not changed.
+\fB\%scrl\fP and \fB\%wscrl\fP scroll
+.B \%stdscr
+or the specified window up or down depending on the sign of
+.IR n .
+.bP
+For positive
+.IR n ,
+line \fIi\fP+\fIn\fP becomes \fIi\fP (scrolling up);
+.bP
+for negative
+.IR n ,
+line \fIi\fP-\fIn\fP becomes \fIi\fP (scrolling down).
.PP
-For these functions to work, scrolling must be enabled via \fBscrollok\fR.
-.SH RETURN VALUE
-These routines return \fBERR\fR upon failure, and \fBOK\fR (SVr4 only specifies
-"an integer value other than \fBERR\fR") upon successful completion.
+The cursor does not move.
+These functions perform no operation unless scrolling is enabled for the
+window via \fB\%scrollok\fP(3X).
+.SH "RETURN VALUE"
+These functions return
+.B ERR
+upon failure and
+.B OK
+upon success.
.PP
-X/Open defines no error conditions.
-.PP
-This implementation returns an error
-if the window pointer is null, or
-if scrolling is not enabled in the window, e.g., with \fBscrollok\fP.
+.I \%ncurses
+returns \fBERR\fP if scrolling is not enabled in the window,
+for example with \fB\%scrollok\fP(3X),
+or if the
+.I \%WINDOW
+pointer is null.
.SH NOTES
-Note that \fBscrl\fR and \fBscroll\fR may be macros.
+Unusually,
+there is no \fB\%wscroll\fP function;
+\fBscroll\fP behaves as one would expect \fB\%wscroll\fP to,
+accepting a \fI\%WINDOW\fP pointer argument.
.PP
-The SVr4 documentation says that the optimization of physically scrolling
-immediately if the scroll region is the entire screen "is" performed, not
-"may be" performed.
-This implementation deliberately does not guarantee
-that this will occur, to leave open the possibility of smarter
-optimization of multiple scroll actions on the next update.
-.PP
-Neither the SVr4 nor the XSI documentation specify whether the current
-attribute or
-current color-pair of blanks generated by the scroll function is zeroed.
-Under this implementation it is.
+\fB\%scrl\fP and \fB\%scroll\fP may be implemented as macros.
.SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions.
+X/Open Curses,
+Issue 4 describes these functions.
+It defines no error conditions.
+.PP
+SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('' as a successful return
+value.
+.PP
+SVr4 indicates that the optimization of physically scrolling immediately
+if the scroll region is the entire screen \*(``is\*('' performed,
+not \*(``may be\*('' performed.
+.I \%ncurses
+deliberately does not guarantee that this will occur,
+to leave open the possibility of smarter optimization of multiple scroll
+actions on the next update.
+.PP
+Neither SVr4
+.I curses
+nor X/Open Curses specify whether the current attribute or current color
+pair of blanks generated by the scroll function are zeroed.
+.I \%ncurses
+does so.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_outopts\fR(3X)
+\fB\%curses\fP(3X),
+\fB\%curs_outopts\fP(3X)
diff --git a/man/curs_slk.3x b/man/curs_slk.3x
index e8f7afb..fbc7181 100644
--- a/man/curs_slk.3x
+++ b/man/curs_slk.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -26,90 +27,96 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_slk.3x,v 1.22 2010/12/04 18:38:55 tom Exp $
-.TH curs_slk 3X ""
-.na
-.hy 0
+.\" $Id: curs_slk.3x,v 1.71 2024/04/20 18:54:36 tom Exp $
+.TH curs_slk 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBslk_init\fR,
-\fBslk_set\fR,
-\fBslk_wset\fR,
-\fBslk_refresh\fR,
-\fBslk_noutrefresh\fR,
-\fBslk_label\fR,
-\fBslk_clear\fR,
-\fBslk_restore\fR,
-\fBslk_touch\fR,
-\fBslk_attron\fR,
-\fBslk_attrset\fR,
-\fBslk_attroff\fR,
-\fBslk_attr_on\fR,
-\fBslk_attr_set\fR,
-\fBslk_attr_off\fR,
-\fBslk_attr\fR,
-\fBslk_color\fR \- \fBcurses\fR soft label routines
-.ad
-.hy
+\fB\%slk_init\fP,
+\fB\%slk_set\fP,
+\fB\%slk_wset\fP,
+\fB\%slk_refresh\fP,
+\fB\%slk_noutrefresh\fP,
+\fB\%slk_label\fP,
+\fB\%slk_clear\fP,
+\fB\%slk_restore\fP,
+\fB\%slk_touch\fP,
+\fB\%slk_attron\fP,
+\fB\%slk_attrset\fP,
+\fB\%slk_attroff\fP,
+\fB\%slk_attr_on\fP,
+\fB\%slk_attr_set\fP,
+\fB\%slk_attr_off\fP,
+\fB\%slk_attr\fP,
+\fB\%slk_color\fP,
+\fB\%extended_slk_color\fP \-
+\fIcurses\fR soft label key routines
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint slk_init(int fmt);\fR
-.br
-\fBint slk_set(int labnum, const char *label, int fmt);\fR
-.br
-\fBint slk_refresh(void);\fR
-.br
-\fBint slk_noutrefresh(void);\fR
-.br
-\fBchar *slk_label(int labnum);\fR
-.br
-\fBint slk_clear(void);\fR
-.br
-\fBint slk_restore(void);\fR
-.br
-\fBint slk_touch(void);\fR
-.br
-\fBint slk_attron(const chtype attrs);\fR
-.br
-\fBint slk_attroff(const chtype attrs);\fR
-.br
-\fBint slk_attrset(const chtype attrs);\fR
-.br
-\fBint slk_attr_on(attr_t attrs, void* opts);\fR
-.br
-\fBint slk_attr_off(const attr_t attrs, void * opts);\fR
-.br
-\fBint slk_attr_set(const attr_t attrs, short color_pair, void* opts);\fR
-.br
-\fBattr_t slk_attr(void);\fR
-.br
-\fBint slk_color(short color_pair);\fR
-.br
-\fBint slk_wset(int labnum, const wchar_t *label, int fmt);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint slk_init(int \fIfmt\fP);
+.PP
+\fBint slk_set(int \fIlabnum\fP, const char *\fIlabel\fP, int \fIalign\fP);
+\fBint slk_wset(int \fIlabnum\fP, const wchar_t *\fIlabel\fP, int \fIalign\fP);
+.PP
+\fBchar *slk_label(int \fIlabnum\fP);
+.PP
+\fBint slk_refresh(void);
+\fBint slk_noutrefresh(void);
+\fBint slk_clear(void);
+\fBint slk_restore(void);
+\fBint slk_touch(void);
+.PP
+\fBint slk_attron(const chtype \fIattrs\fP);
+\fBint slk_attroff(const chtype \fIattrs\fP);
+\fBint slk_attrset(const chtype \fIattrs\fP);
+\fBint slk_attr_on(attr_t \fIattrs\fP, void *\fIopts\fP);
+\fBint slk_attr_off(const attr_t \fIattrs\fP, void *\fIopts\fP);
+\fBint slk_attr_set(const attr_t \fIattrs\fP, short \fIpair\fP, void*\fIopts\fP);
+\fI/* extension */
+\fBattr_t slk_attr(void);
+.PP
+\fBint slk_color(short \fIpair\fP);
+\fI/* extension */
+\fBint extended_slk_color(int \fIpair\fP);
+.fi
.SH DESCRIPTION
-The slk* functions manipulate the set of soft function-key labels that exist on
-many terminals.
+These functions manipulate the soft function key labels that some
+hardware terminals support.
For those terminals that do not have soft labels,
-\fBcurses\fR takes over the bottom line of \fBstdscr\fR, reducing the size of
-\fBstdscr\fR and the variable \fBLINES\fR.
-\fBcurses\fR standardizes on eight
-labels of up to eight characters each.
-In addition to this, the ncurses
-implementation supports a mode where it simulates 12 labels of up to five
-characters each.
-This is useful for today's PC-like enduser devices.
-ncurses simulates this mode by taking over up to two lines at
+\fIcurses\fP takes over the bottom line of \fB\%stdscr\fP,
+reducing its vertical size and the value of \fBLINES\fP by one.
+By default,
+\fIcurses\fP uses eight labels of up to eight characters each.
+.PP
+\fI\%ncurses\fP
+furthermore supports a mode comprising twelve labels of up to five
+characters each,
+following a convention associated with the IBM PC/AT keyboard.
+\fI\%ncurses\fP simulates this mode by taking over up to two lines at
the bottom of the screen;
it does not try to use any hardware support for this
mode.
-.PP
-The \fBslk_init\fR routine must be called before \fBinitscr\fR or \fBnewterm\fR
-is called.
-If \fBinitscr\fR eventually uses a line from \fBstdscr\fR to
+.SS Initialization
+\fB\%slk_init\fP must be called before \fB\%initscr\fP or
+\fB\%newterm\fP.
+If \fB\%initscr\fP eventually uses a line from \fB\%stdscr\fP to
emulate the soft labels,
-then \fIfmt\fR determines how the labels are arranged on the screen:
-.RS
+then \fIfmt\fP determines how the labels are arranged on the screen.
.TP 3
.B 0
indicates a 3\-2\-3 arrangement of
@@ -123,74 +130,104 @@
.TP 3
.B 3
is again the PC-like 4\-4\-4 mode,
-but in addition an index line is generated, helping the user to
-identify the key numbers easily.
-.RE
-.PP
-The \fBslk_set\fR routine
-(and the \fBslk_wset\fR routine for the wide-character library)
-has three parameters:
-.RS
-.TP 5
+but in addition an index line is generated,
+helping the user to associate each label with its numbered function key.
+\fBLINES\fP and the vertical size of \fB\%stdscr\fP are further reduced.
+.SS Labels
+Populate the labels with normal strings
+(\fB\%slk_set\fP)
+or wide-character strings
+(\fB\%slk_wset\fP).
+Each function takes three parameters.
+.TP 8 \" "labnum" + 2n
.I labnum
-is the label number, from \fB1\fR to \fB8\fR
-(12 for \fIfmt\fP in \fBslk_init\fP is \fB2\fP or \fB3\fP);
+is the label number, from \fB1\fP to \fB8\fP
+(12 if \fIfmt\fP in \fB\%slk_init\fP is \fB2\fP or \fB3\fP);
.TP
.I label
is be the string to put on the label,
up to eight
-(five for \fIfmt\fP in \fBslk_init\fP is \fB2\fP or \fB3\fP)
+(five if \fIfmt\fP in \fB\%slk_init\fP is \fB2\fP or \fB3\fP)
characters in length.
-A null string or a null pointer sets up a blank label.
+A empty string or a null pointer sets up a blank label.
.TP
-.I fmt
-is either
-\fB0\fR, \fB1\fR, or \fB2\fR, indicating whether the label is to be
-left-justified, centered, or right-justified, respectively, within the
-label.
-.RE
+.I align
+is
+.BR 0 ,
+.BR 1 ,
+or
+.BR 2 ,
+aligning
+.I label
+to the left,
+center,
+or right,
+respectively,
+within the 8 (5) character cells housing it.
.PP
-The \fBslk_refresh\fR and \fBslk_noutrefresh\fR routines correspond to
-the \fBwrefresh\fR and \fBwnoutrefresh\fR routines.
+\fB\%slk_label\fP obtains the string assigned to label number
+\fIlabnum\fP,
+with any leading and trailing blanks stripped.
+.SS "Screen Updates"
+\fB\%slk_refresh\fP and \fB\%slk_noutrefresh\fP affect the soft key
+label lines as \fB\%wrefresh\fP and \fB\%wnoutrefresh\fP do the
+.I curses
+window.
.PP
-The \fBslk_label\fR routine returns the current label for label number
-\fIlabnum\fR, with leading and trailing blanks stripped.
+The \fB\%slk_clear\fP routine clears the soft labels from the screen.
.PP
-The \fBslk_clear\fR routine clears the soft labels from the screen.
+The \fB\%slk_restore\fP routine restores the soft labels to the screen
+after a \fB\%slk_clear\fP has been performed.
.PP
-The \fBslk_restore\fR routine restores the soft labels to the screen
-after a \fBslk_clear\fR has been performed.
-.PP
-The \fBslk_touch\fR routine forces all the soft labels to be output
-the next time a \fBslk_noutrefresh\fR is performed.
-.PP
-The \fBslk_attron\fR, \fBslk_attrset\fR, \fBslk_attroff\fR and \fBslk_attr\fR
-routines correspond to \fBattron\fR, \fBattrset\fR, \fBattroff\fR and \fBattr_get\fR.
-They have an effect only if soft labels are simulated on the bottom line of
-the screen.
-The default highlight for soft keys is A_STANDOUT (as in
-System V curses, which does not document this fact).
-.PP
-The \fBslk_color\fR routine corresponds to \fBcolor_set\fR.
+The \fB\%slk_touch\fP routine forces all the soft labels to be output
+the next time a \fB\%slk_noutrefresh\fP is performed.
+.SS "Video Attributes"
+The
+\fB\%slk_attron\fP,
+\fB\%slk_attrset\fP,
+\fB\%slk_attroff\fP,
+and
+\fB\%slk_attr\fP
+routines correspond to
+\fB\%attron\fP,
+\fB\%attrset\fP,
+\fB\%attroff\fP,
+and
+\fB\%attr_get\fP,
+respectively.
+They have an effect only if soft labels are simulated on the bottom line
+of the screen.
+The default highlight for soft key labels is \fB\%A_STANDOUT\fP
+(as in System\ V \fIcurses\fP,
+which does not document this fact).
+.SS Colors
+The \fB\%slk_color\fP routine corresponds to \fB\%color_set\fP.
It has an effect only
if soft labels are simulated on the bottom line of the screen.
-.
-.SH RETURN VALUE
-These routines return \fBERR\fR upon failure and OK (SVr4 specifies only "an
-integer value other than \fBERR\fR") upon successful completion.
.PP
-X/Open defines no error conditions.
+Because \fB\%slk_color\fP accepts
+only \fIshort\fP
+(signed 16-bit integer)
+values,
+this implementation provides
+\fB\%extended_slk_color\fP,
+which accepts an \fIint\fP value of at least 32 bits.
+.SH RETURN VALUE
+Routines that return an integer return \fBERR\fP upon failure and
+\fBOK\fP
+(SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('')
+upon successful completion.
+.PP
+X/Open Curses defines no error conditions.
+.PP
In this implementation
-.RS
+.RS 3
.TP 5
-\fBslk_attr\fR
+\fBslk_attr\fP
returns the attribute used for the soft keys.
.TP 5
-.na
-.hy 0
\fBslk_attroff\fP, \fBslk_attron\fP, \fBslk_clear\fP, \fBslk_noutrefresh\fP, \fBslk_refresh\fP, \fBslk_touch\fP
-.ad
-.hy
return an error
if the terminal or the softkeys were not initialized.
.TP 5
@@ -201,20 +238,19 @@
\fBslk_attr_set\fP
returns an error
if the terminal or the softkeys were not initialized, or
-the color pair is outside the range 0..COLOR_PAIRS\-1,
-or opts is not null.
+the color pair is outside the range 0..\fBCOLOR_PAIRS\fP\-1.
.TP 5
\fBslk_color\fP
returns an error
if the terminal or the softkeys were not initialized, or
-the color pair is outside the range 0..COLOR_PAIRS\-1.
+the color pair is outside the range 0..\fBCOLOR_PAIRS\fP\-1.
.TP 5
-\fBslk_init\fR
+\fBslk_init\fP
returns an error
if the format parameter is outside the range 0..3.
.TP 5
-\fBslk_label\fR
-returns \fBNULL\fR on error.
+\fBslk_label\fP
+returns \fBNULL\fP on error.
.TP 5
\fBslk_set\fP
returns an error
@@ -224,19 +260,120 @@
memory for the labels cannot be allocated.
.RE
.SH NOTES
-Most applications would use \fBslk_noutrefresh\fR because a
-\fBwrefresh\fR is likely to follow soon.
+Most applications would use \fB\%slk_noutrefresh\fP because a
+\fB\%wrefresh\fP is likely to follow soon.
+.SH EXTENSIONS
+X/Open Curses documents the \fIopts\fP argument
+as reserved for future use,
+saying that it must be null.
+This implementation
+uses that parameter in ABI 6 for the functions which have a color pair
+parameter to support extended color pairs.
+.PP
+For functions which modify the color,
+e.g.,
+\fB\%slk_attr_set\fP,
+if \fIopts\fP is set it is treated as a pointer to \fIint\fP,
+and used to set the color pair instead of the \fIshort\fP pair
+parameter.
.SH PORTABILITY
-The XSI Curses standard, Issue 4, describes these functions.
-It changes the
-argument type of the attribute-manipulation functions \fBslk_attron\fR,
-\fBslk_attroff\fR, \fBslk_attrset\fR to be \fBattr_t\fR, and adds \fBconst\fR
-qualifiers.
-The format codes \fB2\fR and \fB3\fR for \fBslk_init()\fR and the
-function \fBslk_attr\fR are specific to ncurses.
+X/Open Curses,
+Issue 4 describes these functions,
+with some differences from SVr4 \fIcurses\fP:
+.bP
+X/Open added functions like the SVr4 attribute-manipulation functions
+\fB\%slk_attron\fP,
+\fB\%slk_attroff\fP,
+and
+\fB\%slk_attrset\fP,
+but which use \fI\%attr_t\fP parameters
+(rather than \fI\%chtype\fP),
+along with a reserved \fIopts\fP parameter.
+.IP
+Two of these new functions
+(unlike the SVr4 functions)
+have no provision for color:
+\fB\%slk_attr_on\fP and \fB\%slk_attr_off\fP.
+.IP
+The third function \%(\fBslk_attr_set\fP) has a color pair parameter.
+.bP
+It added \fIconst\fP qualifiers to parameters (unnecessarily),
+and
+.bP
+It added \fB\%slk_color\fP.
+.PP
+Although \fB\%slk_start\fP is declared in the \fIcurses\fP header file,
+it was not documented by SVr4 other than its presence in a list
+of libtermlib.so.1 symbols.
+Reading the source code (i.e., Illumos):
+.bP
+\fB\%slk_start\fP has two parameters:
+.RS
+.bP
+\fIng\fP (number of groups) and
+.bP
+\fIgp\fP (group pointer).
+.RE
+.bP
+Soft-key groups are an array of \fIng\fP integers.
+.bP
+In SVr4, \fB\%slk_init\fP calls \fB\%slk_start\fP passing a null for \fIgp\fP.
+For this case, \fB\%slk_start\fP uses the number of groups \fIng\fP
+(3 for the 3-2-3 layout, 2 for the 4-4 layout) which \fB\%slk_init\fP provided.
+.IP
+If \fIng\fP is neither 2 or 3,
+\fB\%slk_start\fP checks the terminfo \fBfln\fP (label_format) capability,
+interpreting that as a comma-separated list of numbers,
+e.g., \*(``3,2,3\*('' for the 3-2-3 layout.
+.IP
+Finally, if there is no \fBfln\fP capability,
+\fB\%slk_start\fP returns \fBERR\fP.
+.bP
+If \fB\%slk_start\fP is given a non-null \fIgp\fP,
+it copies the \fIng\fP elements of the group of soft-keys, up to 16.
+.IP
+If there are more than 16 elements, \fB\%slk_start\fP returns an error.
+.bP
+The format codes \fB2\fP and \fB3\fP for \fB\%slk_init\fP
+were added by \fI\%ncurses\fP in 1996.
+PDCurses 2.4 added this feature in 2001.
+.PP
+The function \fB\%slk_attr\fP was added by \fI\%ncurses\fP in 1996.
+.PP
+X/Open Curses does not specify a limit for the number of colors and
+color pairs which a terminal can support.
+However, in its use of \fIshort\fP for the parameters,
+it carries over SVr4's implementation detail for the compiled
+terminfo database, which uses signed 16-bit numbers.
+This implementation provides extended versions of those functions
+which use \fIint\fP parameters,
+allowing applications to use larger color- and pair-numbers.
+.SH HISTORY
+SVr3 introduced these functions:
+ \fBslk_clear\fP
+ \fBslk_init\fP
+ \fBslk_label\fP
+ \fBslk_noutrefresh\fP
+ \fBslk_refresh\fP
+ \fBslk_restore\fP
+ \fBslk_set\fP
+ \fBslk_touch\fP
+.PP
+SVr4 added these functions:
+ \fBslk_attroff\fP
+ \fBslk_attron\fP
+ \fBslk_attrset\fP
+ \fBslk_start\fP
+.PP
+X/Open Curses added these:
+ \fBslk_attr_off\fP
+ \fBslk_attr_on\fP
+ \fBslk_attr_set\fP
+ \fBslk_color\fP
+ \fBslk_wset\fP
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_attr\fR(3X),
-\fBcurs_initscr\fR(3X),
-\fBcurs_refresh\fR(3X),
-\fBcurs_variables\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_attr\fP(3X),
+\fB\%curs_initscr\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_variables\fP(3X)
diff --git a/man/curs_sp_funcs.3x b/man/curs_sp_funcs.3x
index c7c55dd..e58a48e 100644
--- a/man/curs_sp_funcs.3x
+++ b/man/curs_sp_funcs.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2010,2013 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 2010-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 *
@@ -26,271 +27,201 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_sp_funcs.3x,v 1.6 2013/06/22 17:53:59 tom Exp $
-.TH curs_sp_funcs 3X ""
-.na
-.hy 0
+.\" $Id: curs_sp_funcs.3x,v 1.50 2024/04/20 18:56:31 tom Exp $
+.TH curs_sp_funcs 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-new_prescr \- \fBcurses\fR screen-pointer extension
-.ad
-.hy
+\fB\%curs_sp_funcs\fP \-
+\fIcurses\fR screen-pointer extension
.SH SYNOPSIS
-\fB#include <curses.h>\fR
.nf
-.sp
-\fBint assume_default_colors_sp(SCREEN*, int, int);\fR
-.br
-\fBint baudrate_sp(SCREEN*);\fR
-.br
-\fBint beep_sp(SCREEN*);\fR
-.br
-\fBbool can_change_color_sp(SCREEN*);\fR
-.br
-\fBint cbreak_sp(SCREEN*);\fR
-.br
-\fBint color_content_sp(SCREEN*, short, short*, short*, short*);\fR
-.br
-\fBint curs_set_sp(SCREEN*, int);\fR
-.br
-\fBint define_key_sp(SCREEN*, const char *, int);\fR
-.br
-\fBint def_prog_mode_sp(SCREEN*);\fR
-.br
-\fBint def_shell_mode_sp(SCREEN*);\fR
-.br
-\fBint delay_output_sp(SCREEN*, int);\fR
-.br
-\fBint doupdate_sp(SCREEN*);\fR
-.br
-\fBint echo_sp(SCREEN*);\fR
-.br
-\fBint endwin_sp(SCREEN*);\fR
-.br
-\fBint erasechar_sp(SCREEN*);\fR
-.br
-\fBint filter_sp(SCREEN*);\fR
-.br
-\fBint flash_sp(SCREEN*);\fR
-.br
-\fBint flushinp_sp(SCREEN*);\fR
-.br
-\fBint get_escdelay_sp(SCREEN*);\fR
-.br
-\fBint getmouse_sp(SCREEN*, MEVENT*);\fR
-.br
-\fBWINDOW* getwin_sp(SCREEN*, FILE*);\fR
-.br
-\fBint halfdelay_sp(SCREEN*);\fR
-.br
-\fBbool has_colors_sp(SCREEN*);\fR
-.br
-\fBbool has_ic_sp(SCREEN*);\fR
-.br
-\fBbool has_il_sp(SCREEN*);\fR
-.br
-\fBint has_key_sp(SCREEN*, int);\fR
-.br
-\fBbool has_mouse_sp(SCREEN*);\fR
-.br
-\fBint init_color_sp(SCREEN*, short, short, short, short);\fR
-.br
-\fBint init_pair_sp(SCREEN*, short, short, short);\fR
-.br
-\fBint intrflush_sp(SCREEN*, WINDOW*, bool);\fR
-.br
-\fBbool isendwin_sp(SCREEN*);\fR
-.br
-\fBbool is_term_resized_sp(SCREEN*, int, int);\fR
-.br
-\fBchar* keybound_sp(SCREEN*, int, int);\fR
-.br
-\fBint key_defined_sp(SCREEN*, const char *);\fR
-.br
-\fBNCURSES_CONST char * keyname_sp(SCREEN*, int);\fR
-.br
-\fBint keyok_sp(SCREEN*, int, bool);\fR
-.br
-\fBchar killchar_sp(SCREEN*);\fR
-.br
-\fBint mcprint_sp(SCREEN*, char *, int);\fR
-.br
-\fBint mouseinterval_sp(SCREEN*, int);\fR
-.br
-\fBmmask_t mousemask_sp(SCREEN*, mmask_t, mmask_t *);\fR
-.br
-\fBint mvcur_sp(SCREEN*, int, int, int, int);\fR
-.br
-\fBint napms_sp(SCREEN*, int);\fR
-.br
-\fBWINDOW* newpad_sp(SCREEN*, int, int);\fR
-.br
-\fBSCREEN* new_prescr(void);\fR
-.br
-\fBSCREEN* newterm_sp(SCREEN*, NCURSES_CONST char *, FILE *, FILE *);\fR
-.br
-\fBWINDOW* newwin_sp(SCREEN*, int, int, int, int);\fR
-.br
-\fBint nl_sp(SCREEN*);\fR
-.br
-\fBint nocbreak_sp(SCREEN*);\fR
-.br
-\fBint noecho_sp(SCREEN*);\fR
-.br
-\fBint nofilter_sp(SCREEN*);\fR
-.br
-\fBint nonl_sp(SCREEN*);\fR
-.br
-\fBvoid noqiflush_sp(SCREEN*);\fR
-.br
-\fBint noraw_sp(SCREEN*);\fR
-.br
-\fBint pair_content_sp(SCREEN*, short, short*, short*);\fR
-.br
-\fBvoid qiflush_sp(SCREEN*);\fR
-.br
-\fBint raw_sp(SCREEN*);\fR
-.br
-\fBint reset_prog_mode_sp(SCREEN*);\fR
-.br
-\fBint reset_shell_mode_sp(SCREEN*);\fR
-.br
-\fBint resetty_sp(SCREEN*);\fR
-.br
-\fBint resize_term_sp(SCREEN*, int, int);\fR
-.br
-\fBint resizeterm_sp(SCREEN*, int, int);\fR
-.br
-\fBint restartterm_sp(SCREEN*, NCURSES_CONST char*, int, int *);\fR
-.br
-\fBint ripoffline_sp(SCREEN*, int, int (*)(WINDOW*, int));\fR
-.br
-\fBint savetty_sp(SCREEN*);\fR
-.br
-\fBint scr_init_sp(SCREEN*, const char *);\fR
-.br
-\fBint scr_restore_sp(SCREEN*, const char *);\fR
-.br
-\fBint scr_set_sp(SCREEN*, const char *);\fR
-.br
-\fBTERMINAL* set_curterm_sp(SCREEN*, TERMINAL*);\fR
-.br
-\fBint set_escdelay_sp(SCREEN*, int);\fR
-.br
-\fBint set_tabsize_sp(SCREEN*, int);\fR
-.br
-\fBint slk_attroff_sp(SCREEN*, const chtype);\fR
-.br
-\fBint slk_attron_sp(SCREEN*, const chtype);\fR
-.br
-\fBint slk_attr_set_sp(SCREEN*, const attr_t, short, void*);\fR
-.br
-\fBint slk_attrset_sp(SCREEN*, const chtype);\fR
-.br
-\fBint slk_attr_sp(SCREEN*);\fR
-.br
-\fBint slk_clear_sp(SCREEN*);\fR
-.br
-\fBint slk_color_sp(SCREEN*, short);\fR
-.br
-\fBint slk_init_sp(SCREEN*, int);\fR
-.br
-\fBint slk_label_sp(SCREEN*, int);\fR
-.br
-\fBint slk_noutrefresh_sp(SCREEN*);\fR
-.br
-\fBint slk_refresh_sp(SCREEN*);\fR
-.br
-\fBint slk_restore_sp(SCREEN*);\fR
-.br
-\fBint slk_set_sp(SCREEN*, int, const char *, int);\fR
-.br
-\fBint slk_touch_sp(SCREEN*);\fR
-.br
-\fBint start_color_sp(SCREEN*);\fR
-.br
-\fBattr_t term_attrs_sp(SCREEN*);\fR
-.br
-\fBchtype termattrs_sp(SCREEN*);\fR
-.br
-\fBchar* termname_sp(SCREEN*);\fR
-.br
-\fBint typeahead_sp(SCREEN*, int);\fR
-.br
-\fBNCURSES_CONST char* unctrl_sp(SCREEN*, chtype);\fR
-.br
-\fBint ungetch_sp(SCREEN*, int);\fR
-.br
-\fBint ungetmouse_sp(SCREEN*,MEVENT *);\fR
-.br
-\fBint unget_wch_sp(SCREEN*, const wchar_t);\fR
-.br
-\fBint use_default_colors_sp(SCREEN*);\fR
-.br
-\fBvoid use_env_sp(SCREEN*, bool);\fR
-.br
-\fBint use_legacy_coding_sp(SCREEN*, int);\fR
-.br
-\fBint vid_attr_sp(SCREEN*, attr_t, short, void *);\fR
-.br
-\fBint vidattr_sp(SCREEN*, chtype);\fR
-.br
-\fBint vid_puts_sp(SCREEN*, attr_t, short, void *, NCURSES_SP_OUTC);\fR
-.br
-\fBint vidputs_sp(SCREEN*, chtype, NCURSES_SP_OUTC);\fR
-.br
-\fBwchar_t* wunctrl_sp(SCREEN*, cchar_t *);\fR
-.sp
-\fB#include <form.h>\fR
-.sp
-\fBint new_form_sp(SCREEN*, FIELD **);\fR
-.sp
-\fB#include <menu.h>\fR
-.sp
-\fBint new_menu_sp(SCREEN*, ITEM **);\fR
-.sp
-\fB#include <panel.h>\fR
-.sp
-\fBint ceiling_panel(SCREEN*);\fR
-.br
-\fBPANEL* ground_panel(SCREEN*);\fR
-.br
-\fBint update_panels_sp(SCREEN*);\fR
-.sp
-\fB#include <term.h>\fR
-.sp
-\fBint del_curterm_sp(SCREEN*, TERMINAL *);\fR
-.br
-\fBint putp_sp(SCREEN*, const char *);\fR
-.br
-\fBint tgetflag_sp(SCREEN*, char *, const char *);\fR
-.br
-\fBint tgetent_sp(SCREEN*, char *, const char *);\fR
-.br
-\fBint tgetnum_sp(SCREEN*, NCURSES_CONST char *);\fR
-.br
-\fBchar* tgetstr_sp(SCREEN*, NCURSES_CONST char *, char **);\fR
-.br
-\fBint tigetflag_sp(SCREEN*, NCURSES_CONST char *);\fR
-.br
-\fBint tigetnum_sp(SCREEN*, NCURSES_CONST char *);\fR
-.br
-\fBchar* tigetstr_sp(SCREEN*, NCURSES_CONST char *);\fR
-.br
-\fBint tputs_sp(SCREEN*, const char *, int, NCURSES_SP_OUTC);\fR
-.ad
-.br
+\fB#include <curses.h>
+.PP
+\fBint alloc_pair_sp(SCREEN* \fIsp\fP, int \fIfg\fP, int \fIbg\fP);
+\fBint assume_default_colors_sp(SCREEN* \fIsp\fP, int \fIfg\fP, int \fIbg\fP);
+\fBint baudrate_sp(SCREEN* \fIsp\fP);
+\fBint beep_sp(SCREEN* \fIsp\fP);
+\fBbool can_change_color_sp(SCREEN* \fIsp\fP);
+\fBint cbreak_sp(SCREEN* \fIsp\fP);
+\fBint color_content_sp(SCREEN* \fIsp\fP, short \fIcolor\fP, short* \fIr\fP, short* \fIg\fP, short* \fIb\fP);
+\fBint curs_set_sp(SCREEN* \fIsp\fP, int \fIvisibility\fP);
+\fBint def_prog_mode_sp(SCREEN* \fIsp\fP);
+\fBint def_shell_mode_sp(SCREEN* \fIsp\fP);
+.PP
+\fBint define_key_sp(SCREEN* \fIsp\fP, const char * \fIdefinition\fP, int \fIkeycode\fP);
+\fBint delay_output_sp(SCREEN* \fIsp\fP, int \fIms\fP);
+\fBint doupdate_sp(SCREEN* \fIsp\fP);
+\fBint echo_sp(SCREEN* \fIsp\fP);
+\fBint endwin_sp(SCREEN* \fIsp\fP);
+\fBchar erasechar_sp(SCREEN* \fIsp\fP);
+\fBint erasewchar_sp(SCREEN* \fIsp\fP, wchar_t *\fIwc\fP);
+\fBint extended_color_content_sp(SCREEN * \fIsp\fP, int \fIcolor\fP, int * \fIr\fP, int * \fIg\fP, int * \fIb\fP);
+\fBint extended_pair_content_sp(SCREEN* \fIsp\fP, int \fIpair\fP, int * \fIfg\fP, int * \fIbg\fP);
+\fBint extended_slk_color_sp(SCREEN* \fIsp\fP, int \fIpair\fP);
+.PP
+\fBvoid filter_sp(SCREEN* \fIsp\fP);
+\fBint find_pair_sp(SCREEN* \fIsp\fP, int \fIfg\fP, int \fIbg\fP);
+\fBint flash_sp(SCREEN* \fIsp\fP);
+\fBint flushinp_sp(SCREEN* \fIsp\fP);
+\fBint free_pair_sp(SCREEN* \fIsp\fP, int \fIpair\fP);
+\fBint get_escdelay_sp(SCREEN* \fIsp\fP);
+\fBint getmouse_sp(SCREEN* \fIsp\fP, MEVENT* \fIevent\fP);
+\fBWINDOW* getwin_sp(SCREEN* \fIsp\fP, FILE* \fIfilep\fP);
+\fBint halfdelay_sp(SCREEN* \fIsp\fP, int \fItenths\fP);
+\fBbool has_colors_sp(SCREEN* \fIsp\fP);
+.PP
+\fBbool has_ic_sp(SCREEN* \fIsp\fP);
+\fBbool has_il_sp(SCREEN* \fIsp\fP);
+\fBint has_key_sp(SCREEN* \fIsp\fP, int \fIc\fP);
+\fBbool has_mouse_sp(SCREEN* \fIsp\fP);
+\fBint init_color_sp(SCREEN* \fIsp\fP, short \fIcolor\fP, short \fIr\fP, short \fIg\fP, short \fIb\fP);
+\fBint init_extended_color_sp(SCREEN* \fIsp\fP, int \fIcolor\fP, int \fIr\fP, int \fIg\fP, int \fIb\fP);
+\fBint init_extended_pair_sp(SCREEN* \fIsp\fP, int \fIpair\fP, int \fIfg\fP, int \fIbg\fP);
+\fBint init_pair_sp(SCREEN* \fIsp\fP, short \fIpair\fP, short \fIfg\fP, short \fIbg\fP);
+\fBint intrflush_sp(SCREEN* \fIsp\fP, WINDOW* \fIwin\fP, bool \fIbf\fP);
+\fBint is_cbreak_sp(SCREEN* \fIsp\fP);
+.PP
+\fBint is_echo_sp(SCREEN* \fIsp\fP);
+\fBint is_nl_sp(SCREEN* \fIsp\fP);
+\fBint is_raw_sp(SCREEN* \fIsp\fP);
+\fBbool is_term_resized_sp(SCREEN* \fIsp\fP, int \fIlines\fP, int \fIcolumns\fP);
+\fBbool isendwin_sp(SCREEN* \fIsp\fP);
+\fBint key_defined_sp(SCREEN* \fIsp\fP, const char *\fIdefinition\fP);
+\fBchar* keybound_sp(SCREEN* \fIsp\fP, int \fIkeycode\fP, int \fIcount\fP);
+\fBNCURSES_CONST char* keyname_sp(SCREEN* \fIsp\fP, int \fIc\fP);
+\fBint keyok_sp(SCREEN* \fIsp\fP, int \fIkeycode\fP, bool \fIenable\fP);
+\fBchar killchar_sp(SCREEN* \fIsp\fP);
+.PP
+\fBint killwchar_sp(SCREEN* \fIsp\fP, wchar_t *\fIwc\fP);
+\fBchar* longname_sp(SCREEN* \fIsp\fP);
+\fBint mcprint_sp(SCREEN* \fIsp\fP, char *\fIdata\fP, int \fIlen\fP);
+\fBint mouseinterval_sp(SCREEN* \fIsp\fP, int \fIerval\fP);
+\fBmmask_t mousemask_sp(SCREEN* \fIsp\fP, mmask_t \fInewmask\fP, mmask_t *\fIoldmask\fP);
+\fBint mvcur_sp(SCREEN* \fIsp\fP, int \fIoldrow\fP, int \fIoldcol\fP, int \fInewrow\fP, int \fInewcol\fP);
+\fBint napms_sp(SCREEN* \fIsp\fP, int \fIms\fP);
+\fBWINDOW* newpad_sp(SCREEN* \fIsp\fP, int \fInrows\fP, int \fIncols\fP);
+\fBSCREEN* new_prescr(void);
+\fBSCREEN* newterm_sp(SCREEN* \fIsp\fP, const char *\fItype\fP, FILE *\fIoutfd\fP, FILE *\fIinfd\fP);
+.PP
+\fBWINDOW* newwin_sp(SCREEN* \fIsp\fP, int \fInlines\fP, int \fIncols\fP, int \fIbegin_y\fP, int \fIbegin_x\fP);
+\fBint nl_sp(SCREEN* \fIsp\fP);
+\fBint nocbreak_sp(SCREEN* \fIsp\fP);
+\fBint noecho_sp(SCREEN* \fIsp\fP);
+\fBvoid nofilter_sp(SCREEN* \fIsp\fP);
+\fBint nonl_sp(SCREEN* \fIsp\fP);
+\fBvoid noqiflush_sp(SCREEN* \fIsp\fP);
+\fBint noraw_sp(SCREEN* \fIsp\fP);
+\fBint pair_content_sp(SCREEN* \fIsp\fP, short \fIpair\fP, short* \fIfg\fP, short* \fIbg\fP);
+\fBvoid qiflush_sp(SCREEN* \fIsp\fP);
+.PP
+\fBint raw_sp(SCREEN* \fIsp\fP);
+\fBvoid reset_color_pairs_sp(SCREEN* \fIsp\fP);
+\fBint reset_prog_mode_sp(SCREEN* \fIsp\fP);
+\fBint reset_shell_mode_sp(SCREEN* \fIsp\fP);
+\fBint resetty_sp(SCREEN* \fIsp\fP);
+\fBint resize_term_sp(SCREEN* \fIsp\fP, int \fIlines\fP, int \fIcolumns\fP);
+\fBint resizeterm_sp(SCREEN* \fIsp\fP, int \fIlines\fP, int \fIcolumns\fP);
+\fBint ripoffline_sp(SCREEN* \fIsp\fP, int \fIline\fP, int (*\fIinit\fP)(WINDOW* \fIwin\fP, int \fIfmt\fP));
+\fBint savetty_sp(SCREEN* \fIsp\fP);
+\fBint scr_init_sp(SCREEN* \fIsp\fP, const char *\fIfilename\fP);
+.PP
+\fBint scr_restore_sp(SCREEN* \fIsp\fP, const char *\fIfilename\fP);
+\fBint scr_set_sp(SCREEN* \fIsp\fP, const char *\fIfilename\fP);
+\fBint set_escdelay_sp(SCREEN* \fIsp\fP, int \fIms\fP);
+\fBint set_tabsize_sp(SCREEN* \fIsp\fP, int \fIcols\fP);
+\fBint slk_attrset_sp(SCREEN* \fIsp\fP, const chtype \fIa\fP);
+\fBint slk_attr_set_sp(SCREEN* \fIsp\fP, const attr_t \fIattrs\fP, short \fIpair\fP, void*\fIopts\fP);
+\fBint slk_attroff_sp(SCREEN* \fIsp\fP, const chtype \fIa\fP);
+\fBint slk_attron_sp(SCREEN* \fIsp\fP, const chtype \fIa\fP);
+\fBattr_t slk_attr_sp(SCREEN* \fIsp\fP);
+\fBint slk_clear_sp(SCREEN* \fIsp\fP);
+.PP
+\fBint slk_color_sp(SCREEN* \fIsp\fP, short \fIpair\fP);
+\fBint slk_init_sp(SCREEN* \fIsp\fP, int \fIfmt\fP);
+\fBchar* slk_label_sp(SCREEN* \fIsp\fP, int \fIlabnum\fP);
+\fBint slk_noutrefresh_sp(SCREEN* \fIsp\fP);
+\fBint slk_refresh_sp(SCREEN* \fIsp\fP);
+\fBint slk_restore_sp(SCREEN* \fIsp\fP);
+\fBint slk_set_sp(SCREEN* \fIsp\fP, int \fIlabnum\fP, const char * \fIlabel\fP, int \fIfmt\fP);
+\fBint slk_touch_sp(SCREEN* \fIsp\fP);
+\fBint start_color_sp(SCREEN* \fIsp\fP);
+\fBattr_t term_attrs_sp(SCREEN* \fIsp\fP);
+.PP
+\fBchtype termattrs_sp(SCREEN* \fIsp\fP);
+\fBchar* termname_sp(SCREEN* \fIsp\fP);
+\fBint typeahead_sp(SCREEN* \fIsp\fP, int \fIfd\fP);
+\fBint unget_wch_sp(SCREEN* \fIsp\fP, const wchar_t \fIwc\fP);
+\fBint ungetch_sp(SCREEN* \fIsp\fP, int \fIc\fP);
+\fBint ungetmouse_sp(SCREEN* \fIsp\fP, MEVENT* \fIevent\fP);
+\fBint use_default_colors_sp(SCREEN* \fIsp\fP);
+\fBvoid use_env_sp(SCREEN* \fIsp\fP, bool \fIbf\fP);
+\fBint use_legacy_coding_sp(SCREEN* \fIsp\fP, int \fIlevel\fP);
+\fBvoid use_tioctl_sp(SCREEN *\fIsp\fP, bool \fIbf\fP);
+.PP
+\fBint vid_attr_sp(SCREEN* \fIsp\fP, attr_t \fIattrs\fP, short \fIpair\fP, void * \fIopts\fP);
+\fBint vid_puts_sp(SCREEN* \fIsp\fP, attr_t \fIattrs\fP, short \fIpair\fP, void * \fIopts\fP, NCURSES_SP_OUTC \fIputc\fP);
+\fBint vidattr_sp(SCREEN* \fIsp\fP, chtype \fIattrs\fP);
+\fBint vidputs_sp(SCREEN* \fIsp\fP, chtype \fIattrs\fP, NCURSES_SP_OUTC \fIputc\fP);
+\fBwchar_t* wunctrl_sp(SCREEN* \fIsp\fP, cchar_t *\fIwch\fP);
+.PP
+\fB#include <form.h>
+.PP
+\fBFORM* new_form_sp(SCREEN* \fIsp\fP, FIELD **\fIfields\fP);
+.PP
+\fB#include <menu.h>
+.PP
+\fBMENU* new_menu_sp(SCREEN* \fIsp\fP, ITEM **\fIitems\fP);
+.PP
+\fB#include <panel.h>
+.PP
+\fBPANEL* ceiling_panel(SCREEN* \fIsp\fP);
+\fBPANEL* ground_panel(SCREEN* \fIsp\fP);
+\fBvoid update_panels_sp(SCREEN* \fIsp\fP);
+.PP
+\fB#include <term.h>
+.PP
+\fBint del_curterm_sp(SCREEN* \fIsp\fP, TERMINAL *\fIoterm\fP);
+\fBint putp_sp(SCREEN* \fIsp\fP, const char *\fIstr\fP);
+\fBint restartterm_sp(SCREEN* \fIsp\fP, NCURSES_CONST char*\fIterm\fP, int \fIfiledes\fP, int *\fIerrret\fP);
+\fBTERMINAL* set_curterm_sp(SCREEN* \fIsp\fP, TERMINAL*\fInterm\fP);
+\fBint tgetent_sp(SCREEN* \fIsp\fP, char *\fIbp\fP, const char *\fIname\fP);
+\fBint tgetflag_sp(SCREEN* \fIsp\fP, const char *\fIcapname\fP);
+\fBint tgetnum_sp(SCREEN* \fIsp\fP, const char *\fIcapname\fP);
+\fBchar* tgetstr_sp(SCREEN* \fIsp\fP, const char *\fIcapname\fP, char **\fIarea\fP);
+\fBchar* tgoto_sp(SCREEN* \fIsp\fP, const char *\fIcapname\fP, int \fIcol\fP, int \fIrow\fP);
+\fBint tigetflag_sp(SCREEN* \fIsp\fP, const char *\fIcapname\fP);
+.PP
+\fBint tigetnum_sp(SCREEN* \fIsp\fP, const char *\fIcapname\fP);
+\fBchar* tigetstr_sp(SCREEN* \fIsp\fP, const char *\fIcapname\fP);
+\fI/* tparm_sp may use 9 long parameters rather than being variadic */
+\fBchar* tparm_sp(SCREEN* \fIsp\fP, const char *\fIstr\fP, ...);
+\fBint tputs_sp(SCREEN* \fIsp\fP, const char *\fIstr\fP, int \fIaffcnt\fP, NCURSES_SP_OUTC \fIputc\fP);
+.PP
+\fB#include <unctrl.h>
+.PP
+\fBNCURSES_CONST char* unctrl_sp(SCREEN* \fIsp\fP, chtype \fIch\fP);
+.fi
.SH DESCRIPTION
This implementation can be configured to provide a set of functions which
improve the ability to manage multiple screens.
-This feature can be added to any of the configurations supported by ncurses;
-it adds new entrypoints
+This feature can be added to any of the configurations supported by
+\fI\%ncurses\fP;
+it adds new symbols
without changing the meaning of any of the existing ones.
-.PP
.\" ***************************************************************************
-.SS IMPROVED FUNCTIONS
+.SS "Improved Functions"
Most of the functions are new versions of existing functions.
A parameter is added at the front of the parameter list.
-It is a SCREEN pointer.
+It is a \fISCREEN\fP pointer.
.PP
The existing functions all use the current screen,
which is a static variable.
@@ -298,7 +229,7 @@
thereby reducing the number of variables which must be modified
to update multiple screens.
.\" ***************************************************************************
-.SS NEW FUNCTIONS
+.SS "New Functions"
Here are the new functions:
.TP 5
ceiling_panel
@@ -314,8 +245,8 @@
there are situations where it must create a current screen before
the unextended library does.
The \fBnew_prescr\fP function is used internally to handle these cases.
-It is also provided as an entrypoint to allow applications to customize
-the library initialization.
+It is also provided to allow applications to customize library
+initialization.
.\" ***************************************************************************
.SH NOTES
This extension introduces some new names:
@@ -328,7 +259,8 @@
NCURSES_SP_NAME
The new functions are named using the macro \fINCURSES_SP_NAME\fP,
which hides the actual implementation.
-Currently this adds a "_sp" suffix to the name of the unextended function.
+Currently this adds a \*(``_sp\*('' suffix
+to the name of the unextended function.
This manual page indexes the extensions showing the full name.
However the proper usage of these functions uses the macro,
to provide for the possibility of changing the naming convention
@@ -341,13 +273,12 @@
NCURSES_OUTC
This is a function-pointer type used for the cases where a function passes
characters to the output stream, e.g., \fBvidputs\fP(3X).
-.PP
.SH PORTABILITY
-These routines are specific to ncurses.
+These 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 ncurses extensions
+It is recommended that any code depending on \fI\%ncurses\fP extensions
be conditioned using \fINCURSES_SP_FUNCS\fP.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_opaque\fR(3X),
-\fBcurs_threads\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_opaque\fP(3X),
+\fB\%curs_threads\fP(3X)
diff --git a/man/curs_termattrs.3x b/man/curs_termattrs.3x
index e19459f..dacd3b0 100644
--- a/man/curs_termattrs.3x
+++ b/man/curs_termattrs.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2015 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -26,110 +27,103 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_termattrs.3x,v 1.13 2015/07/21 00:03:34 tom Exp $
-.TH curs_termattrs 3X ""
+.\" $Id: curs_termattrs.3x,v 1.41 2024/04/20 21:20:07 tom Exp $
+.TH curs_termattrs 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBbaudrate\fR,
-\fBerasechar\fR,
-\fBerasewchar\fR,
-\fBhas_ic\fR,
-\fBhas_il\fR,
-\fBkillchar\fR,
-\fBkillwchar\fR,
-\fBlongname\fR,
-\fBterm_attrs\fR,
-\fBtermattrs\fR,
-\fBtermname\fR \- \fBcurses\fR environment query routines
+\fB\%baudrate\fP,
+\fB\%erasechar\fP,
+\fB\%erasewchar\fP,
+\fB\%has_ic\fP,
+\fB\%has_il\fP,
+\fB\%killchar\fP,
+\fB\%killwchar\fP,
+\fB\%longname\fP,
+\fB\%term_attrs\fP,
+\fB\%termattrs\fP,
+\fB\%termname\fP \-
+\fIcurses\fR environment query routines
.SH SYNOPSIS
-\fB#include <curses.h>\fR
+.nf
+\fB#include <curses.h>
.PP
-\fBint baudrate(void);\fR
-.br
-\fBchar erasechar(void);\fR
-.br
-\fBint erasewchar(wchar_t *\fR\fIch\fR\fB);\fR
-.br
-\fBbool has_ic(void);\fR
-.br
-\fBbool has_il(void);\fR
-.br
-\fBchar killchar(void);\fR
-.br
-\fBint killwchar(wchar_t *\fR\fIch\fR\fB);\fR
-.br
-\fBchar *longname(void);\fR
-.br
-\fBattr_t term_attrs(void);\fR
-.br
-\fBchtype termattrs(void);\fR
-.br
-\fBchar *termname(void);\fR
-.br
+\fBint baudrate(void);
+\fBchar erasechar(void);
+\fBint erasewchar(wchar_t *\fIwc\fP);
+\fBbool has_ic(void);
+\fBbool has_il(void);
+\fBchar killchar(void);
+\fBint killwchar(wchar_t *\fIwc\fP);
+\fBchar *longname(void);
+\fBattr_t term_attrs(void);
+\fBchtype termattrs(void);
+\fBchar *termname(void);
+.fi
.SH DESCRIPTION
.SS baudrate
-The \fBbaudrate\fR routine returns the output speed of the terminal. The
-number returned is in bits per second, for example \fB9600\fR, and is an
+The \fBbaudrate\fP routine returns the output speed of the terminal.
+The
+number returned is in bits per second, for example \fB9600\fP, and is an
integer.
-.SS erasechar, erasewchar
+.SS "erasechar, erasewchar"
+The \fBerasechar\fP routine returns the user's current erase character.
.PP
-The \fBerasechar\fR routine returns the user's current erase character.
-.PP
-The \fBerasewchar\fR routine stores the current erase character
-in the location referenced by \fIch\fR.
+The \fBerasewchar\fP routine stores the current erase character
+in the location referenced by \fIwc\fP.
If no erase character has been defined, the routine fails
-and the location referenced by \fIch\fR is not changed.
-.SS has_is, has_il
-.PP
-The \fBhas_ic\fR routine is true if the terminal has insert- and delete-
+and the location referenced by \fIwc\fP is not changed.
+.SS "has_ic, has_il"
+The \fBhas_ic\fP routine is true if the terminal has insert- and delete-
character capabilities.
.PP
-The \fBhas_il\fR routine is true if the terminal has insert- and delete-line
-capabilities, or can simulate them using scrolling regions. This might
+The \fBhas_il\fP routine is true if the terminal has insert- and delete-line
+capabilities, or can simulate them using scrolling regions.
+This might
be used to determine if it would be appropriate to turn on physical
-scrolling using \fBscrollok\fR.
-.SS killchar, killwchar
+scrolling using \fBscrollok\fP(3X).
+.SS "killchar, killwchar"
+The \fBkillchar\fP routine returns the user's current line kill character.
.PP
-The \fBkillchar\fR routine returns the user's current line kill character.
-.PP
-The \fBkillwchar\fR routine stores the current line-kill character
-in the location referenced by \fIch\fR.
+The \fBkillwchar\fP routine stores the current line-kill character
+in the location referenced by \fIwc\fP.
If no line-kill character has been defined,
-the routine fails and the location referenced by \fIch\fR is not changed.
+the routine fails and the location referenced by \fIwc\fP is not changed.
.SS longname
-.PP
-The \fBlongname\fR routine returns a pointer to a static area
-containing a verbose description of the current terminal. The maximum
-length of a verbose description is 128 characters. It is defined only
-after the call to \fBinitscr\fR or \fBnewterm\fR. The area is
-overwritten by each call to \fBnewterm\fR and is not restored by
-\fBset_term\fR, so the value should be saved between calls to
-\fBnewterm\fR if \fBlongname\fR is going to be used with multiple
+The \fBlongname\fP routine returns a pointer to a static area
+containing a verbose description of the current terminal.
+The maximum
+length of a verbose description is 128 characters.
+It is defined only
+after the call to \fBinitscr\fP or \fBnewterm\fP. The area is
+overwritten by each call to \fBnewterm\fP and is not restored by
+\fBset_term\fP, so the value should be saved between calls to
+\fBnewterm\fP if \fBlongname\fP is going to be used with multiple
terminals.
-.SS termattrs, term_attrs
-.PP
+.SS "termattrs, term_attrs"
If a given terminal does not support a video attribute that an
-application program is trying to use, \fBcurses\fR may substitute a
+application program is trying to use, \fBcurses\fP may substitute a
different video attribute for it.
-The \fBtermattrs\fR and \fBterm_attrs\fR functions
-return a logical \fBOR\fR of all video attributes supported by the
-terminal using \fIA_\fR and \fIWA_\fR constants respectively.
-This information is useful when a \fBcurses\fR program
+The \fBtermattrs\fP and \fBterm_attrs\fP functions
+return a logical \fBOR\fP of all video attributes supported by the
+terminal using \fBA_\fP and \fBWA_\fP constants respectively.
+This information is useful when a \fBcurses\fP program
needs complete control over the appearance of the screen.
.SS termname
-.PP
-The \fBtermname\fR routine returns the terminal name used by \fBsetupterm\fR.
+The \fBtermname\fP routine returns the terminal name used by \fBsetupterm\fP.
.SH RETURN VALUE
-\fBlongname\fR and \fBtermname\fR return \fBNULL\fR on error.
+\fBlongname\fP and \fBtermname\fP return \fBNULL\fP on error.
.PP
-Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
-(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
+Routines that return an integer return \fBERR\fP upon failure and \fBOK\fP
+(SVr4 only specifies "an integer value other than \fBERR\fP") upon successful
completion.
.SH NOTES
-Note that \fBtermattrs\fR may be a macro.
+Note that \fBtermattrs\fP may be a macro.
.SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions. It changes the
-return type of \fBtermattrs\fR to the new type \fBattr_t\fR.
-Most versions of curses truncate the result returned by \fBtermname\fR to
+X/Open Curses, Issue 4 describes these functions.
+It changes the
+return type of \fBtermattrs\fP to the new type \fBattr_t\fP.
+Most versions of curses truncate the result returned by \fBtermname\fP to
14 characters.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_outopts\fR(3X)
+\fB\%curses\fP(3X),
+\fB\%curs_initscr\fP(3X),
+\fB\%curs_outopts\fP(3X)
diff --git a/man/curs_termcap.3x b/man/curs_termcap.3x
index 2f0eea8..6bd2a66 100644
--- a/man/curs_termcap.3x
+++ b/man/curs_termcap.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2013,2015 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 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 *
@@ -26,215 +27,521 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_termcap.3x,v 1.31 2015/04/26 00:49:10 tom Exp $
-.TH curs_termcap 3X ""
+.\" $Id: curs_termcap.3x,v 1.85 2024/04/20 19:13:12 tom Exp $
+.TH curs_termcap 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.na
-.hy 0
-.ds n 5
+.
.SH NAME
-\fBPC\fR,
-\fBUP\fR,
-\fBBC\fR,
-\fBospeed\fR,
-\fBtgetent\fR,
-\fBtgetflag\fR,
-\fBtgetnum\fR,
-\fBtgetstr\fR,
-\fBtgoto\fR,
-\fBtputs\fR \- direct \fBcurses\fR interface to the terminfo capability database
-.ad
-.hy
+\fB\%PC\fP,
+\fB\%UP\fP,
+\fB\%BC\fP,
+\fB\%ospeed\fP,
+\fB\%tgetent\fP,
+\fB\%tgetflag\fP,
+\fB\%tgetnum\fP,
+\fB\%tgetstr\fP,
+\fB\%tgoto\fP,
+\fB\%tputs\fP \-
+\fIcurses\fR emulation of \fItermcap\fR
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.br
-\fB#include <term.h>\fR
-.sp
-\fBextern char PC;\fR
-.br
-\fBextern char * UP;\fR
-.br
-\fBextern char * BC;\fR
-.br
-\fBextern @NCURSES_OSPEED@ ospeed;\fR
-.sp
-\fBint tgetent(char *bp, const char *name);\fR
-.br
-\fBint tgetflag(char *id);\fR
-.br
-\fBint tgetnum(char *id);\fR
-.br
-\fBchar *tgetstr(char *id, char **area);\fR
-.br
-\fBchar *tgoto(const char *cap, int col, int row);\fR
-.br
-\fBint tputs(const char *str, int affcnt, int (*putc)(int));\fR
-.br
-.SH DESCRIPTION
-These routines are included as a conversion aid for programs that use
-the \fItermcap\fR library. Their parameters are the same and the
-routines are emulated using the \fIterminfo\fR database. Thus, they
-can only be used to query the capabilities of entries for which a
-terminfo entry has been compiled.
-.SS INITIALIZATION
+.nf
+\fB#include <curses.h>
+\fB#include <term.h>
.PP
-The \fBtgetent\fR routine loads the entry for \fIname\fR.
-It returns:
+\fBchar PC;
+\fBchar * UP;
+\fBchar * BC;
+\fB@NCURSES_OSPEED@ ospeed;
+.PP
+\fBint tgetent(char *\fIbp\fP, const char *\fIname\fP);
+\fBint tgetflag(const char *\fIid\fP);
+\fBint tgetnum(const char *\fIid\fP);
+\fBchar *tgetstr(const char *\fIid\fP, char **\fIarea\fP);
+\fBchar *tgoto(const char *\fIcap\fP, int \fIcol\fP, int \fIrow\fP);
+\fBint tputs(const char *\fIstr\fP, int \fIaffcnt\fP, int (*\fIputc\fP)(int));
+.fi
+.SH DESCRIPTION
+.I \%ncurses
+provides the foregoing variables and functions as a compatibility layer
+for programs that use the \fItermcap\fP library.
+The API is the same,
+but behavior is emulated using the \fI\%term\%info\fP database.
+Thus,
+it can be used only to query the capabilities of terminal database
+entries for which a \fI\%term\%info\fP entry has been compiled.
+.SS Initialization
+\fB\%tgetent\fP loads the terminal database entry for \fIname\fP;
+see \fBterm\fP(7).
+This must be done before calling any of the other functions.
+It returns
.RS 3
-.TP 3
+.TP 5 \" "-1" + 2n + adjust for PDF
1
on success,
-.TP 3
+.TP
0
if there is no such entry
-(or that it is a generic type, having too little information for curses
-applications to run), and
-.TP 3
+(or if the matching entry describes a generic terminal,
+having too little information for
+.I curses
+applications to run),
+and
+.TP
\-1
-if the terminfo database could not be found.
+if the \fI\%term\%info\fP database could not be found.
.RE
.PP
-This differs from the \fItermcap\fP library in two ways:
+This implementation differs from those of historical \fItermcap\fP
+libraries.
.RS 3
.bP
-The emulation ignores the buffer pointer \fIbp\fR.
-The \fItermcap\fP library would store a copy of the terminal
+.I \%ncurses
+ignores the buffer pointer \fIbp\fP,
+as do other \fItermcap\fP implementations conforming to portions of
+X/Open Curses now withdrawn.
+The BSD \fItermcap\fP library would store a copy of the terminal type
description in the area referenced by this pointer.
-However, ncurses stores its terminal descriptions in compiled
-binary form, which is not the same thing.
+\fI\%term\%info\fP stores terminal type descriptions in compiled form,
+which is not the same thing.
.bP
-There is a difference in return codes.
-The \fItermcap\fP library does not check if the terminal
-description is marked with the \fIgeneric\fP capability,
-or if the terminal description has cursor-addressing.
+The meanings of the return values differ.
+The BSD \fItermcap\fP library does not check whether the terminal type
+description includes the
+.B \%generic
+.RB ( gn )
+capability,
+nor whether the terminal type description supports an addressable
+cursor,
+a property essential for any \fIcurses\fP implementation to operate.
.RE
-.SS CAPABILITY VALUES
-.PP
-The \fBtgetflag\fR routine gets the boolean entry for \fIid\fR,
+.SS "Retrieving Capability Values"
+\fB\%tgetflag\fP reports the Boolean entry for \fIid\fP,
or zero if it is not available.
.PP
-The \fBtgetnum\fR routine gets the numeric entry for \fIid\fR,
+\fB\%tgetnum\fP obtains the numeric entry for \fIid\fP,
or \-1 if it is not available.
.PP
-The \fBtgetstr\fR routine returns the string entry for \fIid\fR,
-or zero if it is not available.
-Use \fBtputs\fR to output the returned string.
-The \fIarea\fP parameter is used as follows:
+\fB\%tgetstr\fP returns the string entry for \fIid\fP,
+or
+.B NULL
+if it is not available.
+Use \fB\%tputs\fP to output the string returned.
+The
+.I area
+parameter is used as follows.
.RS 3
.bP
It is assumed to be the address of a pointer to a buffer managed by the
calling application.
.bP
-However, ncurses checks to ensure that \fBarea\fP is not NULL,
-and also that the resulting buffer pointer is not NULL.
-If either check fails, the \fIarea\fP parameter is ignored.
+However,
+\fI\%ncurses\fP checks to ensure that
+.I area
+is not
+.BR NULL ,
+and also that the resulting buffer pointer is not
+.BR NULL .
+If either check fails,
+.I area
+is ignored.
.bP
-If the checks succeed, ncurses also copies the return value to
-the buffer pointed to by \fIarea\fR,
-and the \fIarea\fR value will be updated to point past the null ending
-this value.
+If the checks succeed,
+\fI\%ncurses\fP also copies the return value to the buffer pointed to by
+\fIarea\fP,
+and the library updates
+.I area
+to point past the null character terminating this value.
.bP
-The return value itself is an address in the terminal description which
-is loaded into memory.
+The return value itself is an address in the terminal type description
+loaded into memory.
.RE
+.SS "Applying String Capabilities"
+String capabilities can be parameterized;
+see subsection \*(``Parameterized Strings\*('' in \fB\%terminfo\fP(5).
+\fB\%tgoto\fP applies its second and third arguments to the parametric
+placeholders in the capability stored in the first argument.
+.bP
+The capability may contain padding specifications;
+see subsection \*(``Delays and Padding\*('' of \fB\%terminfo\fP(5).
+The output of \fB\%tgoto\fP should thus be passed to \fB\%tputs\fP
+rather than some other output function such as \fI\%printf\fP(3).
+.bP
+While \fB\%tgoto\fP is assumed to be used for the two-parameter
+cursor positioning capability,
+\fItermcap\fP applications also use it for single-parameter
+capabilities.
+.IP
+Doing so reveals a quirk in \fB\%tgoto\fP:
+most hardware terminals use cursor addressing with \fIrow\fP first,
+but the original developers of the \fItermcap\fP interface chose to
+put the \fIcol\fP (column) parameter first.
+The \fB\%tgoto\fP function swaps the order of its parameters.
+It does this even for calls requiring only a single parameter.
+In that case,
+the first parameter is merely a placeholder.
+.bP
+Normally the \fI\%ncurses\fP library is compiled without
+full \fI\%termcap\fP support.
+In that case,
+\fB\%tgoto\fP uses an internal version of \fB\%tparm\fP(3X)
+(a more capable function).
+.IP
+Because it uses \fB\%tparm\fP internally,
+\fB\%tgoto\fP is able to use some \fI\%term\%info\fP features,
+but not all.
+In particular,
+it allows only numeric parameters;
+\fB\%tparm\fP supports string parameters.
+.IP
+However,
+\fB\%tparm\fP is not a \fItermcap\fP feature,
+and portable \fItermcap\fP applications should not rely upon its
+availability.
.PP
-Only the first two characters of the \fBid\fR parameter of
-\fBtgetflag\fR,
-\fBtgetnum\fR and
-\fBtgetstr\fR are compared in lookups.
-.SS FORMATTING CAPABILITIES
-.PP
-The \fBtgoto\fR routine instantiates the parameters into the given capability.
-The output from this routine is to be passed to \fBtputs\fR.
-.PP
-The \fBtputs\fR routine is described on the \fBcurs_terminfo\fR(3X) manual
-page. It can retrieve capabilities by either termcap or terminfo name.
-.SS GLOBAL VARIABLES
-.PP
+\fB\%tputs\fP is described in \fB\%curs_terminfo\fP(3X).
+It can retrieve capabilities by either \fItermcap\fP or
+\fI\%term\%info\fP code.
+.SS "Global Variables"
The variables
-\fBPC\fR,
-\fBUP\fR and
-\fBBC\fR
-are set by \fBtgetent\fR to the terminfo entry's data for
-\fBpad_char\fR,
-\fBcursor_up\fR and
-\fBbackspace_if_not_bs\fR,
+\fBPC\fP,
+\fBUP\fP and
+\fBBC\fP
+are set by \fB\%tgetent\fP to the \fI\%term\%info\fP entry's data for
+\fB\%pad_char\fP,
+\fB\%cursor_up\fP and
+\fB\%backspace_if_not_bs\fP,
respectively.
-\fBUP\fR is not used by ncurses.
-\fBPC\fR is used in the \fBtdelay_output\fR function.
-\fBBC\fR is used in the \fBtgoto\fR emulation.
-The variable \fBospeed\fR is set by ncurses in a system-specific coding
-to reflect the terminal speed.
-.
-.SH RETURN VALUE
-Except where explicitly noted,
-routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
-(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
-completion.
+\fBUP\fP is not used by \fI\%ncurses\fP.
+\fBPC\fP is used by \fB\%delay_output\fP(3X).
+\fBBC\fP is used by \fB\%tgoto\fP emulation.
+The variable \fB\%ospeed\fP is set by \fI\%ncurses\fP using a
+system-specific encoding to indicate the terminal's data rate.
+.SS "Releasing Memory"
+The \fItermcap\fP functions provide no means of freeing memory,
+because legacy \fItermcap\fP implementations used only the buffer
+areas provided by the caller via \fB\%tgetent\fP and \fB\%tgetstr\fP.
+Those buffers are unused in \fI\%term\%info\fP.
.PP
-Routines that return pointers return \fBNULL\fR on error.
-.SH BUGS
-If you call \fBtgetstr\fR to fetch \fBca\fR or any other parameterized string,
-be aware that it will be returned in terminfo notation, not the older and
-not-quite-compatible termcap notation. This will not cause problems if all
-you do with it is call \fBtgoto\fR or \fBtparm\fR, which both expand
-terminfo-style strings as terminfo.
-(The \fBtgoto\fR function, if configured to support termcap, will check
-if the string is indeed terminfo-style by looking for "%p" parameters or
-"$<..>" delays, and invoke a termcap-style parser if the string does not
-appear to be terminfo).
+By contrast,
+\fI\%term\%info\fP allocates memory.
+It uses \fB\%setupterm\fP(3X) to obtain the data used by \fB\%tgetent\fP
+and the functions that retrieve capability values.
+One could use
+.RS
+.EX
+del_curterm(cur_term);
+.EE
+.RE
+to free this memory,
+but there is an additional complication with \fI\%ncurses\fP.
+It uses a fixed-size pool of storage locations,
+one per value of the terminal name parameter given to \fB\%tgetent\fP.
+The \fIscreen\fP(1) program relies upon this arrangement to improve its
+performance.
.PP
-Because terminfo conventions for representing padding in string capabilities
-differ from termcap's, \fBtputs("50");\fR will put out a literal "50" rather
-than busy-waiting for 50 milliseconds. Cope with it.
+An application that uses only the \fItermcap\fP functions,
+not the higher level
+.I \%curses
+API,
+could release the memory using \fB\%del_curterm\fP(3X),
+because the pool is freed using other functions;
+see \fB\%curs_memleaks\fP(3X).
+.SH "RETURN VALUE"
+The return values of
+\fB\%tgetent\fP,
+\fB\%tgetflag\fP,
+\fB\%tgetname\fP,
+and
+\fB\%tgetstr\fP
+are documented above.
.PP
-Note that termcap has nothing analogous to terminfo's \fBsgr\fR string.
-One consequence of this is that termcap applications assume \fRme\fR
-(terminfo \fBsgr0\fR) does not reset the alternate character set.
-This implementation checks for, and modifies the data shown to the
-termcap interface to accommodate termcap's limitation in this respect.
+\fB\%tgoto\fP returns
+.B NULL
+on error.
+Error conditions include:
+.bP
+uninitialized state
+(\fB\%tgetent\fP was not called successfully),
+.bP
+.I cap
+being a null pointer,
+.bP
+.I cap
+referring to a canceled capability,
+.bP
+.I cap
+being a capability with string-valued parameters
+(a \fI\%term\%info\fP-only feature),
+and
+.bP
+.I cap
+being a capability with more than two parameters.
+.PP
+See \fB\%curs_terminfo\fP(3X) regarding \fB\%tputs\fP.
+.SH NOTES
+\fI\%ncurses\fP compares only the first two characters of the \fIid\fP
+parameter of
+\fB\%tgetflag\fP,
+\fB\%tgetnum\fP,
+and
+\fB\%tgetstr\fP to the capability names in the database.
.SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions. However, they
-are marked TO BE WITHDRAWN and may be removed in future versions.
+These functions are no longer standardized
+(and the variables never were);
+\fI\%ncurses\fP provides them to support legacy applications.
+They should not be used in new programs.
+.SS Standards
+.bP
+X/Open Curses, Issue 4, Version 2 (1996),
+describes these functions,
+marking them as
+\*(``TO BE WITHDRAWN\*(''.
+.bP
+X/Open Curses, Issue 7 (2009) marks the \fItermcap\fP interface
+(along with \fB\%vwprintw\fP and \fB\%vwscanw\fP) as withdrawn.
.PP
-Neither the XSI Curses standard nor the SVr4 man pages documented the return
-values of \fBtgetent\fR correctly, though all three were in fact returned ever
-since SVr1.
-In particular, an omission in the XSI Curses documentation has been
-misinterpreted to mean that \fBtgetent\fR returns \fBOK\fR or \fBERR\fR.
+Neither X/Open Curses nor the SVr4 man pages documented the return
+values of \fB\%tgetent\fP correctly,
+though all three shown here were in fact returned ever since SVr1.
+In particular,
+an omission in the X/Open Curses specification has been misinterpreted
+to mean that \fB\%tgetent\fP returns \fBOK\fP or \fBERR\fP.
Because the purpose of these functions is to provide compatibility with
-the \fItermcap\fR library, that is a defect in XCurses, Issue 4, Version 2
-rather than in ncurses.
+the \fItermcap\fP library,
+that is a defect in X/Open Curses, Issue 4, Version 2
+rather than in \fI\%ncurses\fP.
+.SS "Compatibility with BSD \fItermcap\fP"
+Externally visible variables are provided for support of certain
+\fItermcap\fP applications.
+However,
+their correct usage is poorly documented;
+for example,
+it is unclear when reading and writing them is meaningful.
+In particular,
+some applications are reported to declare and/or modify \fB\%ospeed\fP.
.PP
-External variables are provided for support of certain termcap applications.
-However, termcap applications' use of those variables is poorly documented,
-e.g., not distinguishing between input and output.
-In particular, some applications are reported to declare and/or
-modify \fBospeed\fR.
+The constraint that only the first two characters of the \fIid\fP
+parameter are used escapes many application developers.
+The BSD \fItermcap\fP library did not require a trailing null character
+on the capability identifier passed to \fB\%tgetstr\fP,
+\fB\%tgetnum\fP,
+and
+\fB\%tgetflag\fP.
+.\" See <https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/\
+.\" termlib/termcap.c>.
+Some applications thus assume that the \fItermcap\fP interface does not
+require the trailing null character for the capability identifier.
+.bP
+.I \%ncurses
+disallows matches by the \fItermcap\fP interface against extended
+capability names that are longer than two characters;
+see \fB\%user_caps\fP(5).
.PP
-The comment that only the first two characters of the \fBid\fR parameter
-are used escapes many application developers.
-The original BSD 4.2 termcap library (and historical relics thereof)
-did not require a trailing null NUL on the parameter name passed
-to \fBtgetstr\fP, \fBtgetnum\fP and \fBtgetflag\fP.
-Some applications assume that the termcap interface does not require
-the trailing NUL for the parameter name.
-Taking into account these issues:
+The BSD \fItermcap\fP function \fB\%tgetent\fP returns the text of a
+\fItermcap\fP entry in the buffer passed as an argument.
+This library,
+like other \fI\%term\%info\fP implementations,
+does not store terminal type descriptions as text.
+It sets the buffer contents to a null-terminated string.
+.SS "Header File"
+This library includes a \fI\%termcap.h\fP header for compatibility with
+other implementations,
+but the header is rarely used because the other implementations are not
+strictly compatible.
+.SH HISTORY
+.\" See https://www.oreilly.com/openbook/opensources/book/kirkmck.html
+.\" for much BSD release history.
+Bill Joy originated a forerunner of \fItermcap\fP called
+\*(``ttycap\*('',
+dated September 1977,
+and released in 1BSD
+(March 1978).
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/s7/ttycap.c
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/man7/ttycap.7
+It used many of the same function names as the later \fItermcap\fP,
+such as
+\fB\%tgetent\fP,
+\fB\%tgetflag\fP,
+\fB\%tgetnum\fP,
+and
+\fB\%tgetstr\fP.
+.PP
+A clear descendant,
+the \fItermlib\fP library,
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/termlib/
+followed in 2BSD
+(May 1979),
+adding \fB\%tgoto\fP and \fB\%tputs\fP.
+The former applied at that time only to cursor positioning capabilities,
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/bin/etc/termcap
+thus the overly specific name.
+Little changed in 3BSD
+(late 1979)
+except the addition of test programs and a \fI\%termlib\fP man page,
+which documented the API shown in section \*(``SYNOPSIS\*('' above.
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/lib/\
+.\" libtermlib/
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/man/man3/\
+.\" termlib.3
+.PP
+4BSD
+(November 1980)
+renamed \fItermlib\fP to \fItermcap\fP
+.\" ...except in the source tree...
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
+.\" libtermlib/makefile
+and added another test program.
+The library remained much the same though 4.3BSD
+(June 1986).
+4.4BSD-Lite
+(June 1994)
+refactored it,
+.\" Observe the `tncktc()`, `tnamatch()`, `tskip()`, and `tdecode()`
+.\" entry points disappearing from termcap.c.
+leaving the API unchanged.
+.PP
+Function prototypes were a feature of ANSI C (1989).
+The library long antedated the standard and thus provided no header file
+declaring them.
+Nevertheless,
+the BSD sources included two different \fI\%termcap.h\fP header files
+over time.
.bP
-As a special case,
-\fBtgetflag\fP matched against a single-character identifier
-provided that was at the end of the terminal description.
-You should not rely upon this behavior in portable programs.
-This implementation disallows matches against single-character capability names.
+One was used internally by \fBjove\fP(1) from 4.3BSD onward.
+.\" 2BSD became a branch retaining support for non-virtual memory
+.\" systems (such as the PDP-11) whereas most BSD development focused on
+.\" the VAX and other VM-enabled systems starting with 3BSD.
+.\"
+.\" This man page previously located a termcap.h in 2BSD, but that may
+.\" be confusion arising from its backport to 2.9BSD (and still present
+.\" in surviving sources for 2.11BSD, the "end of the line" for that
+.\" branch's development).
+.\"
+.\" Observe the copyright notice in
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD/usr/contrib/\
+.\" jove/Makefile
+.\" --much too late for 2BSD (1979).
+It declared global symbols for the \fItermcap\fP variables that it used.
.bP
-This implementation disallows matches by the termcap interface against
-extended capability names which are longer than two characters.
-.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBterminfo\fR(\*n),
-\fBterm_variables\fR(3X),
-\fBputc\fR(3).
-.sp
-http://invisible-island.net/ncurses/tctest.html
+The other appeared in 4.4BSD-Lite Release 2
+(June 1995)
+as part of \fIlibedit\fP
+(also known as the \fI\%edit\%line\fP library).
+CSRG source history shows that this was added in mid-1992.
+The \fIlibedit\fP header file was used internally as a convenience for
+compiling the \fI\%edit\%line\fP library.
+It declared function prototypes,
+but no global variables.
+This header file was added to NetBSD's \fItermcap\fP library in
+mid-1994.
+.PP
+Meanwhile,
+GNU \fItermcap\fP began development in 1990.
+Its first release (1.0) in 1991 included a \fI\%termcap.h\fP header.
+Its second (1.1) in September 1992 modified the header to use
+\fIconst\fP for the function prototypes in the header where one would
+expect the parameters to be read-only.
+BSD \fItermcap\fP did not.
+The prototype for \fB\%tputs\fP also differed,
+but in that instance,
+it was \fIlibedit\fP that differed from BSD \fItermcap\fP.
+.PP
+GNU \fItermcap\fP 1.3 was bundled with \fIbash\fP(1) in mid-1993 to
+support the \fI\%readline\fP(3) library.
+.PP
+\fI\%ncurses\fP 1.8.1
+(November 1993)
+provided a \fI\%termcap.h\fP file.
+It reflected influence from GNU \fItermcap\fP and \fBemacs\fP(1)
+(rather than \fBjove\fP(1)),
+providing the following interface:
+.bP
+global symbols used by \fIemacs\fP,
+.bP
+\fIconst\fP-qualified function prototypes,
+and
+.bP
+a prototype for \fBtparam\fP,
+a GNU \fItermcap\fP feature.
+.PP
+Later
+(in mid-1996)
+the \fB\%tparam\fP function was removed from \fI\%ncurses\fP.
+Any two of the four implementations thus differ,
+and programs that intend to work with all \fItermcap\fP library
+interfaces must account for that fact.
+.SH BUGS
+If you call \fB\%tgetstr\fP to fetch
+.B \%column_address
+.RB ( ch )
+or any other parameterized string capability,
+be aware that it is returned in \fI\%term\%info\fP notation,
+not the older and not-quite-compatible \fItermcap\fP notation.
+This does not cause problems if all you do with it is call \fB\%tgoto\fP
+or \fB\%tparm\fP,
+which both parametrically expand \fI\%term\%info\fP-style string
+capabilities as \fI\%term\%info\fP does.
+(If
+.I \%ncurses
+is configured to support \fItermcap,\fP
+\fB\%tgoto\fP checks whether the string is \fI\%term\%info\fP-style by
+looking for \*(``\fB%p\fP\*('' parameters or
+\*(``\fB<\fP.\|.\|.\fB>\fP\*('' delays,
+and invokes a \fItermcap\fP-style parser if the string appears not to
+use \fI\%term\%info\fP syntax.)
+.PP
+Because \fI\%term\%info\fP's syntax for padding in string capabilities
+differs from \fItermcap\fP's,
+users can be surprised.
+.IP \(bu 4
+\fB\%tputs("50")\fP in a \fI\%term\%info\fP system transmits
+\*(``50\*('' rather than busy-waiting for 50 milliseconds.
+.IP \(bu 4
+However,
+if \fI\%ncurses\fP is configured to support \fItermcap\fP,
+it may also have been configured to support BSD-style padding.
+.IP
+In that case,
+\fB\%tputs\fP inspects strings passed to it,
+looking for digits at the beginning of the string.
+.IP
+\fB\%tputs("50")\fP in a \fItermcap\fP system may busy-wait for 50
+milliseconds rather than transmitting \*(``50\*(''.
+.PP
+\fItermcap\fP has nothing analogous to \fI\%term\%info\fP's
+.B \%set_attributes
+.RB ( sgr )
+capability.
+One consequence is that \fItermcap\fP applications assume that
+.RB \*(`` me \*(''
+(equivalent to \fI\%term\%info\fP's
+.B \%exit_attribute_mode
+.RB ( sgr0 )
+capability)
+does not reset the alternate character set.
+\fI\%ncurses\fP checks for,
+and modifies the data shared with,
+the \fItermcap\fP interface to accommodate the latter's limitation in
+this respect.
+.SH "SEE ALSO"
+\fB\%curses\fP(3X),
+\fB\%curs_terminfo\fP(3X),
+\fB\%putc\fP(3),
+\fB\%term_variables\fP(3X),
+\fB\%terminfo\fP(5)
+.PP
+https://invisible\-island.net/ncurses/tctest.html
diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x
index 7d440bf..10d1fa7 100644
--- a/man/curs_terminfo.3x
+++ b/man/curs_terminfo.3x
@@ -1,5 +1,7 @@
+'\" t
.\"***************************************************************************
-.\" Copyright (c) 1999-2011,2013 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -26,423 +28,1115 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_terminfo.3x,v 1.43 2013/07/20 19:29:59 tom Exp $
-.TH curs_terminfo 3X ""
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: curs_terminfo.3x,v 1.136 2024/04/14 00:14:40 tom Exp $
+.TH curs_terminfo 3X 2024-04-13 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.ds n 5
-.na
-.hy 0
+.
.SH NAME
-\fBdel_curterm\fR,
-\fBmvcur\fR,
-\fBputp\fR,
-\fBrestartterm\fR,
-\fBset_curterm\fR,
-\fBsetterm\fR,
-\fBsetupterm\fR,
-\fBtigetflag\fR,
-\fBtigetnum\fR,
-\fBtigetstr\fR,
-\fBtiparm\fR,
-\fBtparm\fR,
-\fBtputs\fR,
-\fBvid_attr\fR,
-\fBvid_puts\fR,
-\fBvidattr\fR,
-\fBvidputs\fR \- \fBcurses\fR interfaces to terminfo database
-.ad
-.hy
+\fB\%del_curterm\fP,
+\fB\%mvcur\fP,
+\fB\%putp\fP,
+\fB\%restartterm\fP,
+\fB\%set_curterm\fP,
+\fB\%setupterm\fP,
+\fB\%tigetflag\fP,
+\fB\%tigetnum\fP,
+\fB\%tigetstr\fP,
+\fB\%tiparm\fP,
+\fB\%tiparm_s\fP,
+\fB\%tiscan_s\fP,
+\fB\%tparm\fP,
+\fB\%tputs\fP,
+\fB\%vid_attr\fP,
+\fB\%vid_puts\fP,
+\fB\%vidattr\fP,
+\fB\%vidputs\fP \-
+\fIcurses\fR interfaces to \fI\%term\%info\fR database
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fR
-.br
-\fB#include <term.h>\fR
+\fB#include <curses.h>
+\fB#include <term.h>
.PP
-\fBint setupterm(char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
-.br
-\fBint setterm(char *\fR\fIterm\fR\fB);\fR
-.br
-\fBTERMINAL *set_curterm(TERMINAL *\fR\fInterm\fR\fB);\fR
-.br
-\fBint del_curterm(TERMINAL *\fR\fIoterm\fR\fB);\fR
-.br
-\fBint restartterm(char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
-.br
-\fBchar *tparm(char *\fR\fIstr\fR\fB, ...);\fR
-.br
-\fBint tputs(const char *\fR\fIstr\fR\fB, int \fR\fIaffcnt\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
-.br
-\fBint putp(const char *\fR\fIstr\fR\fB);\fR
-.br
-\fBint vidputs(chtype \fR\fIattrs\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
-.br
-\fBint vidattr(chtype \fR\fIattrs\fR\fB);\fR
-.br
-\fBint vid_puts(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
-.br
-\fBint vid_attr(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB);\fR
-.br
-\fBint mvcur(int \fR\fIoldrow\fR\fB, int \fR\fIoldcol\fR\fB, int \fR\fInewrow\fR, int \fR\fInewcol\fR\fB);\fR
-.br
-\fBint tigetflag(char *\fR\fIcapname\fR\fB);\fR
-.br
-\fBint tigetnum(char *\fR\fIcapname\fR\fB);\fR
-.br
-\fBchar *tigetstr(char *\fR\fIcapname\fR\fB);\fR
-.br
-\fBchar *tiparm(const char *\fR\fIstr\fR\fB, ...);\fR
-.br
+\fBTERMINAL *cur_term;
+.PP
+\fBconst char * const boolnames[];
+\fBconst char * const boolcodes[];
+\fBconst char * const boolfnames[];
+\fBconst char * const numnames[];
+\fBconst char * const numcodes[];
+\fBconst char * const numfnames[];
+\fBconst char * const strnames[];
+\fBconst char * const strcodes[];
+\fBconst char * const strfnames[];
+.PP
+\fBint setupterm(const char *\fIterm\fP, int \fIfiledes\fP, int *\fIerrret\fP);
+\fBTERMINAL *set_curterm(TERMINAL *\fInterm\fP);
+\fBint del_curterm(TERMINAL *\fIoterm\fP);
+\fBint restartterm(const char *\fIterm\fP, int \fIfiledes\fP, int *\fIerrret\fP);
+.PP
+\fBchar *tparm(const char *\fIstr\fP, \fR.\|.\|.\fP);
+ \fI/* or */
+\fBchar *tparm(const char *\fIstr\fP, long \fIp1\fP \fR.\|.\|.\fP \fBlong\fP \fIp9\fP);
+.PP
+\fBint tputs(const char *\fIstr\fP, int \fIaffcnt\fP, int (*\fIputc\fP)(int));
+\fBint putp(const char *\fIstr\fP);
+.PP
+\fBint vidputs(chtype \fIattrs\fP, int (*\fIputc\fP)(int));
+\fBint vidattr(chtype \fIattrs\fP);
+\fBint vid_puts(attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP, int (*\fIputc\fP)(int));
+\fBint vid_attr(attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP);
+.PP
+\fBint mvcur(int \fIoldrow\fP, int \fIoldcol\fP, int \fInewrow\fP, int \fInewcol\fP);
+.PP
+\fBint tigetflag(const char *\fIcap-code\fP);
+\fBint tigetnum(const char *\fIcap-code\fP);
+\fBchar *tigetstr(const char *\fIcap-code\fP);
+.PP
+\fBchar *tiparm(const char *\fIstr\fP, \fR.\|.\|.\fP);
+.PP
+\fI/* extensions */
+\fBchar *tiparm_s(int \fIexpected\fP, int \fImask\fP, const char *\fIstr\fP, ...);
+\fBint tiscan_s(int *\fIexpected\fP, int *\fImask\fP, const char *\fIstr\fP);
+.PP
+\fI/* deprecated */
+\fBint setterm(const char *\fIterm\fP);
.fi
.SH DESCRIPTION
-These low-level routines must be called by programs that have to deal
-directly with the \fBterminfo\fR database to handle certain terminal
-capabilities, such as programming function keys. For all other
-functionality, \fBcurses\fR routines are more suitable and their use is
-recommended.
+These low-level functions must be called by programs that deal directly
+with the
+.I \%term\%info
+database to handle certain terminal capabilities,
+such as programming function keys.
+For all other functionality,
+.I curses
+functions are more suitable and their use is recommended.
+.PP
+None of these functions use
+(or are aware of)
+multibyte character strings such as UTF-8.
+.bP
+Capability names and codes use the POSIX portable character set.
+.bP
+Capability string values have no associated encoding;
+they are strings of 8-bit characters.
.SS Initialization
+Initially,
+\fB\%setupterm\fP should be called.
+The high-level
+.I curses
+functions \fB\%initscr\fP and \fB\%newterm\fP call \fB\%setupterm\fP to
+initialize the low-level set of terminal-dependent variables listed in
+\fB\%term_variables\fP(3X).
.PP
-Initially, \fBsetupterm\fR should be called. Note that
-\fBsetupterm\fR is automatically called by \fBinitscr\fR and
-\fBnewterm\fR. This defines the set of terminal-dependent variables
-[listed in \fBterminfo\fR(\*n)].
-.PP
-Each initialization routine provides applications with the
-terminal capabilities either directly (via header definitions),
+Applications can use the terminal capabilities either directly
+(via header definitions),
or by special functions.
-The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this
-order) to get the definitions for these strings, numbers, and flags.
+The header files
+.I \%curses.h
+and
+.I \%term.h
+should be included
+(in that order)
+to get the definitions for these strings,
+numbers,
+and flags.
.PP
-The \fBterminfo\fR variables
-\fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR as
-follows:
+The
+.I \%term\%info
+variables
+.B \%lines
+and
+.B \%columns
+are initialized by \fB\%setupterm\fP as follows.
.bP
-If \fBuse_env(FALSE)\fR has been called, values for
-\fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used.
+If \fB\%use_env(FALSE)\fP has been called,
+values for
+.B \%lines
+and
+.B \%columns
+specified in
+.I \%term\%info
+are used.
.bP
-Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR
-exist, their values are used. If these environment variables do not
-exist and the program is running in a window, the current window size
-is used. Otherwise, if the environment variables do not exist, the
-values for \fBlines\fR and \fBcolumns\fR specified in the
-\fBterminfo\fR database are used.
+Otherwise,
+if the environment variables
+.I LINES
+and
+.I \%COLUMNS
+exist,
+their values are used.
+If these environment variables do not exist and the program is running
+in a window,
+the current window size
+is used.
+Otherwise,
+if the environment variables do not exist,
+the values for
+.B \%lines
+and
+.B \%columns
+specified in the
+.I \%term\%info
+database are used.
.PP
-Parameterized strings should be passed through \fBtparm\fR to instantiate them.
-All \fBterminfo\fR strings [including the output of \fBtparm\fR] should be printed
-with \fBtputs\fR or \fBputp\fR.
-Call \fBreset_shell_mode\fR to restore the
-tty modes before exiting [see \fBcurs_kernel\fR(3X)].
+Parameterized strings should be passed through \fB\%tparm\fP to
+instantiate them.
+All
+.I \%term\%info
+strings
+(including the output of \fB\%tparm\fP)
+should be sent to the terminal device with \fB\%tputs\fP or
+\fB\%putp\fP.
+Call \fB\%reset_shell_mode\fP to restore the terminal modes before
+exiting;
+see \fB\%curs_kernel\fP(3X).
.PP
-Programs which use
+Programs that use
cursor addressing should
.bP
-output \fBenter_ca_mode\fR upon startup and
+output \fB\%enter_ca_mode\fP upon startup and
.bP
-output \fBexit_ca_mode\fR before exiting.
+output \fB\%exit_ca_mode\fP before exiting.
.PP
-Programs which execute shell subprocesses should
+Programs that execute shell subprocesses should
.bP
-call \fBreset_shell_mode\fR and
-output \fBexit_ca_mode\fR before the shell
+call \fB\%reset_shell_mode\fP and
+output \fB\%exit_ca_mode\fP before the shell
is called and
.bP
-output \fBenter_ca_mode\fR and
-call \fBreset_prog_mode\fR after returning from the shell.
+output \fB\%enter_ca_mode\fP and
+call \fB\%reset_prog_mode\fP after returning from the shell.
.PP
-The \fBsetupterm\fR routine reads in the \fBterminfo\fR database,
-initializing the \fBterminfo\fR structures, but does not set up the
-output virtualization structures used by \fBcurses\fR. The terminal
-type is the character string \fIterm\fR; if \fIterm\fR is null, the
-environment variable \fBTERM\fR is used.
-All output is to file descriptor \fBfildes\fR which is initialized for output.
-If \fIerrret\fR is not null,
-then \fBsetupterm\fR returns \fBOK\fR or
-\fBERR\fR and stores a status value in the integer pointed to by
-\fIerrret\fR.
-A return value of \fBOK\fR combined with status of \fB1\fR in \fIerrret\fR
+\fB\%setupterm\fP reads in the
+.I \%term\%info
+database,
+initializing the
+.I \%term\%info
+structures,
+but does not set up the output virtualization structures used by
+.IR curses .
+Its parameters follow.
+.RS 3
+.TP 5
+.I term
+is the terminal type,
+a character string.
+If
+.I term
+is null,
+the environment variable
+.I TERM
+is read.
+.TP 5
+.I filedes
+is the file descriptor used for getting and setting terminal I/O modes.
+.IP
+Higher-level applications use \fB\%newterm\fP(3X) to initialize the
+terminal,
+passing an output
+.I stream
+rather than a
+.IR descriptor .
+In
+.IR curses ,
+the two are the same because \fB\%newterm\fP calls \fB\%setupterm\fP,
+passing the file descriptor derived from its output stream parameter.
+.TP 5
+.I errret
+points to an optional location where an error status can be returned to
+the caller.
+If
+.I errret
+is not null,
+then \fB\%setupterm\fP returns
+.B OK
+or
+.B ERR
+and stores a status value in the integer pointed to by
+.IR errret .
+A return value of
+.B OK
+combined with status of
+.B 1
+in
+.I errret
is normal.
-If \fBERR\fR is returned, examine \fIerrret\fR:
+.IP
+If
+.B ERR
+is returned,
+examine
+.I errret:
+.RS
.TP 5
.B 1
-means that the terminal is hardcopy, cannot be used for curses applications.
+means that the terminal is hardcopy,
+and cannot be used for
+.I curses
+applications.
.IP
-\fBsetupterm\fP determines if the entry is a hardcopy type by
-checking the \fIhc\fP (\fIhardcopy\fP) capability.
+\fB\%setupterm\fP determines if the entry is a hardcopy type by
+checking the
+.B \%hardcopy
+.RB ( hc )
+capability.
.TP 5
.B 0
means that the terminal could not be found,
or that it is a generic type,
-having too little information for curses applications to run.
+having too little information for
+.I curses
+applications to run.
.IP
-\fBsetupterm\fP determines if the entry is a generic type by
-checking the \fIgn\fP (\fIgeneric\fP) capability.
+\fB\%setupterm\fP determines if the entry is a generic type by
+checking the
+.B \%generic_type
+.RB ( gn )
+capability.
.TP 5
.B \-1
-means that the \fBterminfo\fR database could not be found.
-.PP
-If \fIerrret\fR is
-null, \fBsetupterm\fR prints an error message upon finding an error
-and exits. Thus, the simplest call is:
-.sp
- \fBsetupterm((char *)0, 1, (int *)0);\fR,
-.sp
-which uses all the defaults and sends the output to \fBstdout\fR.
-.PP
-The \fBsetterm\fR routine was replaced by \fBsetupterm\fR. The call:
-.sp
- \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR
-.sp
-provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR.
-The \fBsetterm\fR routine is provided for BSD compatibility, and
-is not recommended for new programs.
-.\" ***************************************************************************
-.SS The Terminal State
-.PP
-The \fBsetupterm\fR routine stores its information about the terminal
-in a \fBTERMINAL\fP structure pointed to by the global variable \fBcur_term\fP.
+means that the
+.I \%term\%info
+database could not be found.
+.RE
+.IP
+If
+.I errret
+is null,
+\fB\%setupterm\fP reports an error message upon finding an error and
+exits.
+Thus,
+the simplest call is:
+.RS
+.IP
+.EX
+setupterm((char *)0, 1, (int *)0);
+.EE
+.RE
+.IP
+which uses all the defaults and sends the output to
+.BR stdout .
+.RE
+.\" ********************************************************************
+.SS "The Terminal State"
+\fB\%setupterm\fP stores its information about the terminal in a
+.I \%TERMINAL
+structure pointed to by the global variable \fB\%cur_term\fP.
If it detects an error,
-or decides that the terminal is unsuitable (hardcopy or generic),
+or decides that the terminal is unsuitable
+(hardcopy or generic),
it discards this information,
making it not available to applications.
.PP
-If \fBsetupterm\fP is called repeatedly for the same terminal type,
+If \fB\%setupterm\fP is called repeatedly for the same terminal type,
it will reuse the information.
It maintains only one copy of a given terminal's capabilities in memory.
If it is called for different terminal types,
-\fBsetupterm\fP allocates new storage for each set of terminal capabilities.
+\fB\%setupterm\fP allocates new storage for each set of terminal
+capabilities.
.PP
-The \fBset_curterm\fR routine sets \fBcur_term\fR to
-\fInterm\fR, and makes all of the \fBterminfo\fR boolean, numeric, and
-string variables use the values from \fInterm\fR.
-It returns the old value of \fBcur_term\fR.
+\fB\%set_curterm\fP sets \fB\%cur_term\fP to
+.IR \%nterm ,
+and makes all of the
+.I \%term\%info
+Boolean,
+numeric,
+and string variables use the values from
+.IR \%nterm .
+It returns the old value of \fB\%cur_term\fP.
.PP
-The \fBdel_curterm\fR routine frees the space pointed to by
-\fIoterm\fR and makes it available for further use. If \fIoterm\fR is
-the same as \fBcur_term\fR, references to any of the \fBterminfo\fR
-boolean, numeric, and string variables thereafter may refer to invalid
-memory locations until another \fBsetupterm\fR has been called.
+\fB\%del_curterm\fP frees the space pointed to by
+.I \%oterm
+and makes it available for further use.
+If
+.I \%oterm
+is
+the same as \fB\%cur_term\fP,
+references to any of the
+.I \%term\%info
+Boolean,
+numeric,
+and string variables thereafter may refer to invalid memory locations
+until another \fB\%setupterm\fP has been called.
.PP
-The \fBrestartterm\fR routine is similar to \fBsetupterm\fR and \fBinitscr\fR,
-except that it is called after restoring memory to a previous state (for
-example, when reloading a game saved as a core image dump).
-\fBrestartterm\fP assumes that the windows and the input and output options
-are the same as when memory was saved,
+\fB\%restartterm\fP is similar to \fB\%setupterm\fP and \fB\%initscr\fP,
+except that it is called after restoring memory to a previous state
+(for example,
+when reloading a game saved as a core image dump).
+\fB\%restartterm\fP assumes that the windows and the input and output
+options are the same as when memory was saved,
but the terminal type and baud rate may be different.
-Accordingly, \fBrestartterm\fP saves various tty state bits,
-calls \fBsetupterm\fP, and then restores the bits.
-.\" ***************************************************************************
-.SS Formatting Output
-.PP
-The \fBtparm\fR routine instantiates the string \fIstr\fR with
-parameters \fIpi\fR. A pointer is returned to the result of \fIstr\fR
+Accordingly,
+\fB\%restartterm\fP saves various terminal state bits,
+calls \fB\%setupterm\fP,
+and then restores the bits.
+.\" ********************************************************************
+.SS "Formatting Output"
+\fB\%tparm\fP instantiates the string
+.I str
+with parameters
+.IR pi .
+A pointer is returned to the result of
+.I str
with the parameters applied.
+Application developers should keep in mind these quirks of the
+interface:
+.bP
+Although \fB\%tparm\fP's actual parameters may be integers or strings,
+the prototype expects
+.I long
+(integer) values.
+.bP
+Aside from the
+.B \%set_attributes\fP
+.RB ( sgr )
+capability,
+most terminal capabilities require no more than one or two parameters.
+.bP
+Padding information is ignored by \fB\%tparm\fP;
+it is interpreted by \fB\%tputs\fP.
+.bP
+The capability string is null-terminated.
+Use \*(``\e200\*('' where an ASCII NUL is needed in the output.
.PP
-\fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI<stdarg.h>\fP
+\fB\%tiparm\fP is a newer form of \fB\%tparm\fP which uses
+.I \%stdarg.h
rather than a fixed-parameter list.
-Its numeric parameters are integers (int) rather than longs.
-.\" ***************************************************************************
-.SS Output Functions
+Its numeric parameters are
+.IR int s
+rather than
+.IR long "s."
.PP
-The \fBtputs\fR routine applies padding information to the string
-\fIstr\fR and outputs it. The \fIstr\fR must be a terminfo string
-variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or
-\fBtgoto\fR. \fIaffcnt\fR is the number of lines affected, or 1 if
-not applicable. \fIputc\fR is a \fBputchar\fR-like routine to which
-the characters are passed, one at a time.
+Both \fB\%tparm\fP and \fB\%tiparm\fP assume that the application passes
+parameters consistent with the terminal description.
+Two extensions are provided as alternatives to deal with untrusted data.
+.bP
+\fB\%tiparm_s\fP is an extension which is a safer formatting function
+than \fB\%tparm\fR or \fB\%tiparm\fR,
+because it allows the developer to tell the
+.I curses
+library how many parameters to expect in the parameter list,
+and which may be string parameters.
+.IP
+The \fImask\fP parameter has one bit set for each of the parameters
+(up to 9)
+passed as
+.I char
+pointers rather than numbers.
+.bP
+The extension \fB\%tiscan_s\fP allows the application to inspect a
+formatting capability to see what the
+.I curses
+library would assume.
+.\" ********************************************************************
+.SS "Output Functions"
+String capabilities can contain padding information,
+a time delay
+(accommodating performance limitations of hardware terminals)
+expressed as \fB$<\fIn\fB>\fR,
+where \fIn\fP is a nonnegative integral count of milliseconds.
+If \fIn\fP exceeds 30,000
+(thirty seconds),
+it is capped at that value.
.PP
-The \fBputp\fR routine calls \fBtputs(\fR\fIstr\fR\fB, 1, putchar)\fR.
-Note that the output of \fBputp\fR always goes to \fBstdout\fR, not to
-the \fIfildes\fR specified in \fBsetupterm\fR.
+\fB\%tputs\fP interprets time-delay information in the string
+.I str
+and outputs it,
+executing the delays:
+.bP
+The
+.I str
+parameter must be a
+.I \%term\%info
+string variable or the return value of
+\fB\%tparm\fP,
+\fB\%tiparm\fP,
+\fB\%tgetstr\fP,
+or \fB\%tgoto\fP.
+.IP
+The \fB\%tgetstr\fP and \fB\%tgoto\fP functions are part of the
+.I termcap
+interface,
+which happens to share these function names with the
+.I \%term\%info
+API.
+.bP
+.I affcnt
+is the number of lines affected,
+or
+.B 1
+if not applicable.
+.bP
+.I putc
+is a
+.IR \%putchar -like
+function to which the characters are passed,
+one at a time.
+.IP
+If \fB\%tputs\fP processes a time-delay,
+it uses the \fB\%delay_output\fP(3X) function,
+routing any resulting padding characters through this function.
.PP
-The \fBvidputs\fR routine displays the string on the terminal in the
-video attribute mode \fIattrs\fR, which is any combination of the
-attributes listed in \fBcurses\fR(3X). The characters are passed to
-the \fBputchar\fR-like routine \fIputc\fR.
+\fB\%putp\fR calls
+.RB \%\*(`` tputs(\c
+.IB str ", 1, putchar)\c"
+\*(''.
+The output of \fB\%putp\fP always goes to
+.BR stdout ,
+rather than the
+.I \%file\%des
+specified in \fB\%setupterm\fP.
.PP
-The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except
-that it outputs through \fBputchar\fR.
+\fB\%vidputs\fP displays the string on the terminal in the video
+attribute mode
+.IR attrs ,
+which is any combination of the attributes listed in \fB\%curses\fP(3X).
+The characters are passed to the
+.IR \%putchar -like
+function
+.IR putc .
.PP
-The \fBvid_attr\fR and \fBvid_puts\fR routines correspond to vidattr and vidputs,
+\fB\%vidattr\fP is like \fB\%vidputs\fP,
+except that it outputs through \fI\%putchar\fP(3).
+.PP
+.B \%vid_attr
+and
+.B \%vid_puts
+correspond to
+.B \%vidattr
+and
+.BR \%vidputs ,
respectively.
-They use a set of arguments for representing the video attributes plus color,
-i.e.,
-one of type attr_t for the attributes and one of short for
-the color_pair number.
-The \fBvid_attr\fR and \fBvid_puts\fR routines
-are designed to use the attribute constants with the \fIWA_\fR prefix.
-The opts argument is reserved for future use.
-Currently, applications must provide a null pointer for that argument.
+They use multiple parameters to represent the character attributes and
+color;
+namely,
+.bP
+.IR \%attrs ,
+of type
+.IR \%attr_t ,
+for the attributes and
+.bP
+.IR pair ,
+of type
+.IR short ,
+for the color pair number.
.PP
-The \fBmvcur\fR routine provides low-level cursor motion. It takes
-effect immediately (rather than at the next refresh).
-.\" ***************************************************************************
-.SS Terminal Capability Functions
+Use the attribute constants prefixed with
+.RB \*(`` WA_ \*(''
+with
+.B \%vid_attr
+and
+.BR \%vid_puts .
.PP
-The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return
-the value of the capability corresponding to the \fBterminfo\fR
-\fIcapname\fR passed to them, such as \fBxenl\fR.
-The \fIcapname\fR for each capability is given in the table column entitled
-\fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n).
+X/Open Curses reserves the
+.I opts
+argument for future use,
+saying that applications must provide a null pointer for that argument;
+but see section \*(``EXTENSIONS\*('' below.
.PP
-These routines return special values to denote errors.
+\fB\%mvcur\fP provides low-level cursor motion.
+It takes effect immediately
+(rather than at the next refresh).
+Unlike the other low-level output functions,
+which either write to the standard output or pass an output function
+parameter,
+\fB\%mvcur\fP uses an output file descriptor derived from
+the output stream parameter of \fB\%newterm\fP(3X).
.PP
-The \fBtigetflag\fR routine returns
+While \fB\%putp\fP and \fB\%mvcur\fP are low-level functions that do not
+use high-level
+.I curses
+state,
+.I \%ncurses
+declares them in
+.I \%curses.h
+because System\ V did this
+(see section \*(``HISTORY\*('' below).
+.\" ********************************************************************
+.SS "Terminal Capability Functions"
+\fB\%tigetflag\fP,
+\fB\%tigetnum\fP,
+and \fB\%tigetstr\fP return the value of the capability corresponding to
+the
+.I \%term\%info
+.IR cap-code ,
+such as
+.BR xenl ,
+passed to them.
+The
+.I cap-code
+for each capability is given in the table column entitled
+.I cap-code
+code in the capabilities section of \fB\%terminfo\fP(5).
+.PP
+These functions return special values to denote errors.
+.PP
+\fB\%tigetflag\fP returns
.TP
-\fB\-1\fR
-if \fIcapname\fR is not a boolean capability,
+.B \-1
+if
+.I cap-code
+is not a Boolean capability,
or
.TP
-\fB0\fR
+.B 0
if it is canceled or absent from the terminal description.
.PP
-The \fBtigetnum\fR routine returns
+\fB\%tigetnum\fP returns
.TP
-\fB\-2\fR
-if \fIcapname\fR is not a numeric capability, or
-.TP
-\fB\-1\fR
-if it is canceled or absent from the terminal description.
-.PP
-The \fBtigetstr\fR routine returns
-.TP
-\fB(char *)\-1\fR
-if \fIcapname\fR is not a string capability,
+.B \-2
+if
+.I cap-code
+is not a numeric capability,
or
.TP
-\fB0\fR
+.B \-1
if it is canceled or absent from the terminal description.
-.\" ***************************************************************************
-.SS Terminal Capability Names
+.PP
+\fB\%tigetstr\fP returns
+.TP
+.B "(char *)\-1"
+if
+.I cap-code
+is not a string capability,
+or
+.TP
+.B 0
+if it is canceled or absent from the terminal description.
+.\" ********************************************************************
+.SS "Terminal Capability Names"
These null-terminated arrays contain
-the short terminfo names ("codes"),
-the \fBtermcap\fR names, and the long terminfo names ("fnames")
-for each of the predefined \fBterminfo\fR variables:
+.bP
+the short \fI\%term\%info\fP names (\*(``codes\*(''),
+.bP
+the \fItermcap\fP names (\*(``names\*(''),
+and
+.bP
+the long \fI\%term\%info\fP names (\*(``fnames\*('')
+.PP
+for each of the predefined
+.I \%term\%info
+variables:
+.PP
.RS
-\fBchar *boolnames[]\fR, \fB*boolcodes[]\fR, \fB*boolfnames[]\fR
-.sp
-\fBchar *numnames[]\fR, \fB*numcodes[]\fR, \fB*numfnames[]\fR
-.sp
-\fBchar *strnames[]\fR, \fB*strcodes[]\fR, \fB*strfnames[]\fR
+.nf
+\fBconst char *boolnames[]\fP, \fB*boolcodes[]\fP, \fB*boolfnames[]\fP
+\fBconst char *numnames[]\fP, \fB*numcodes[]\fP, \fB*numfnames[]\fP
+\fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP
+.fi
.RE
+.\" ********************************************************************
+.SS "Releasing Memory"
+Each successful call to \fB\%setupterm\fP allocates memory to hold the
+terminal description.
+As a side effect,
+it sets \fB\%cur_term\fP to point to this memory.
+If an application calls
+.IP
+.EX
+del_curterm(cur_term);
+.EE
+.PP
+the memory will be freed.
+.PP
+The formatting functions \fB\%tparm\fP and \fB\%tiparm\fP extend the
+storage allocated by \fB\%setupterm\fP as follows.
+.bP
+They add the \*(``static\*(''
+.I \%term\%info
+variables [a-z].
+Before
+.I \%ncurses
+6.3,
+those were shared by all screens.
+With
+.I \%ncurses
+6.3,
+those are allocated per screen.
+See \fB\%terminfo\fP(5).
+.bP
+To improve performance,
+.I \%ncurses
+6.3 caches the result of analyzing
+.I \%term\%info
+strings for their parameter types.
+That is stored as a binary tree referenced from the
+.I \%TERMINAL
+structure.
+.PP
+The higher-level \fB\%initscr\fP and \fB\%newterm\fP functions use
+\fB\%setupterm\fP.
+Normally they do not free this memory,
+but it is possible to do that using the \fB\%delscreen\fP(3X) function.
+.\" ********************************************************************
.SH RETURN VALUE
-Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
-(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
-completion, unless otherwise noted in the preceding routine descriptions.
-.PP
-Routines that return pointers always return \fBNULL\fR on error.
-.PP
-X/Open defines no error conditions.
-In this implementation
-.RS 5
+X/Open Curses defines no failure conditions.
+In
+.IR \%ncurses ,
.TP 5
-\fBdel_curterm\fP
-returns an error
-if its terminal parameter is null.
+.B del_curtem
+fails if its terminal parameter is null.
.TP 5
-\fBputp\fP
-calls \fBtputs\fP, returning the same error-codes.
+.B putp
+calls \fB\%tputs\fP,
+returning the same error codes.
.TP 5
-\fBrestartterm\fP
-returns an error
-if the associated call to \fBsetupterm\fP returns an error.
+.B restartterm
+fails if the associated call to \fB\%setupterm\fP returns an error.
.TP 5
-\fBsetupterm\fP
-returns an error
-if it cannot allocate enough memory, or
-create the initial windows (stdscr, curscr, newscr).
+.B setupterm
+fails if it cannot allocate enough memory,
+or create the initial windows
+.RB ( \%stdscr ,
+.BR \%curscr ,
+and
+.BR \%newscr )
Other error conditions are documented above.
.TP 5
-\fBtputs\fP
-returns an error if the string parameter is null.
+.B tparm
+returns a null pointer if the capability would require unexpected
+parameters;
+that is,
+too many,
+too few,
+or incorrect types
+(strings where integers are expected,
+or vice versa).
+.TP 5
+.B tputs
+fails if the string parameter is null.
It does not detect I/O errors:
-X/Open states that \fBtputs\fP ignores the return value
-of the output function \fIputc\fP.
-.RE
+X/Open Curses states that \fB\%tputs\fP ignores the return value
+of the output function \fI\%putc\fP.
+.\" ********************************************************************
+.SH NOTES
+The
+.B \%vid_attr
+function in
+.I \%ncurses
+is a special case.
+It was originally implemented based on a draft of X/Open Curses,
+as a macro,
+before other parts of the
+.I \%ncurses
+wide-character API were developed,
+and unlike the other wide-character functions,
+is also provided in the non-wide-character configuration.
+.\" ********************************************************************
+.SH EXTENSIONS
+The functions marked as extensions were designed for
+.IR \%ncurses ,
+and are not found in SVr4
+.IR curses ,
+4.4BSD
+.IR curses ,
+or any other previous
+.I curses
+implementation.
+.PP
+.I \%ncurses
+allows
+.I opts
+to be a pointer to
+.IR int ,
+which overrides the
+.I pair
+.RI ( short )
+argument.
+.\" ********************************************************************
.SH PORTABILITY
-X/Open notes that \fBvidattr\fR and \fBvidputs\fR may be macros.
-.PP
-The function \fBsetterm\fR is not described by X/Open and must
-be considered non-portable.
+\fB\%setterm\fP is not described by X/Open and must be considered
+non-portable.
All other functions are as described by X/Open.
+.SS "Compatibility Macros"
+This implementation provides a few macros for compatibility with systems
+before SVr4
+(see section \*(``HISTORY\*('' below).
+They include
+\fB\%Bcrmode\fP,
+\fB\%Bfixterm\fP,
+\fB\%Bgettmode\fP,
+\fB\%Bnocrmode\fP,
+\fB\%Bresetterm\fP,
+\fB\%Bsaveterm\fP,
+and
+\fB\%Bsetterm\fP.
.PP
-\fBsetupterm\fP copies the terminal name to the array \fBttytype\fP.
-This is not part of X/Open Curses, but is assumed by some applications.
-.PP
-If configured to use the terminal-driver,
-e.g., for the MinGW port,
-.bP
-\fBsetupterm\fP interprets a missing/empty TERM variable as the
-special value \*(``unknown\*(''.
-.bP
-\fBsetupterm\fP allows explicit use of the
-the windows console driver by checking if $TERM is set to
-\*(``#win32con\*('' or an abbreviation of that string.
-.PP
-Older versions of \fBncurses\fP assumed that the file descriptor passed to
-\fBsetupterm\fP from \fBinitscr\fP or \fBnewterm\fP uses buffered I/O,
-and would write to the corresponding stream.
-In addition to the limitation that the terminal was left in block-buffered
-mode on exit (like SystemV curses),
-it was problematic because \fBncurses\fP
-did not allow a reliable way to cleanup on receiving SIGTSTP.
-The current version uses output buffers managed directly by \fBncurses\fP.
-Some of the low-level functions described in this manual page write
-to the standard output.
-They are not signal-safe.
-The high-level functions in \fBncurses\fP use
-alternate versions of these functions
-using the more reliable buffering scheme.
-.PP
-In System V Release 4, \fBset_curterm\fR has an \fBint\fR return type and
-returns \fBOK\fR or \fBERR\fR. We have chosen to implement the X/Open Curses
-semantics.
-.PP
-In System V Release 4, the third argument of \fBtputs\fR has the type
-\fBint (*putc)(char)\fR.
-.PP
-At least one implementation of X/Open Curses (Solaris) returns a value
-other than OK/ERR from \fBtputs\fP.
-That returns the length of the string, and does no error-checking.
-.PP
-X/Open Curses prototypes \fBtparm\fR with a fixed number of parameters,
-rather than a variable argument list.
-This implementation uses a variable argument list, but can be
-configured to use the fixed-parameter list.
-Portable applications should provide 9 parameters after the format;
-zeroes are fine for this purpose.
-.PP
-In response to comments by Thomas E. Dickey,
-X/Open Curses Issue 7 proposed the \fBtiparm\fP function in mid-2009.
-.PP
-X/Open notes that after calling \fBmvcur\fR, the curses state may not match the
-actual terminal state, and that an application should touch and refresh
-the window before resuming normal curses calls.
-Both \fBncurses\fP and System V Release 4 curses implement \fBmvcur\fR using
-the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR.
-So though it is documented as a terminfo function,
-\fBmvcur\fR is really a curses function which is not well specified.
-.PP
-X/Open states that the old location must be given for \fBmvcur\fP.
-This implementation allows the caller to use \-1's for the old ordinates.
-In that case, the old location is unknown.
+In SVr4,
+these are found in
+.IR \%curses.h ,
+but except for \fB\%setterm\fP,
+are likewise macros.
+The one function,
+\fB\%setterm\fP,
+is mentioned in the manual page.
+It further notes that \fB\%setterm\fP was replaced by \fB\%setupterm\fP,
+stating that the call
+.RS
+.EX
+setupterm(\fIterm\fP, 1, (int *)0)
+.EE
+.RE
+provides the same functionality as \fB\%setterm(\fIterm\fB)\fR,
+discouraging the latter for new programs.
+.I \%ncurses
+implements each of these symbols as macros for BSD
+.I curses
+compatibility.
+.SS "Legacy Data"
+\fB\%setupterm\fP copies the terminal name to the array \fB\%ttytype\fP.
+This is not part of X/Open Curses,
+but is assumed by some applications.
.PP
Other implementions may not declare the capability name arrays.
Some provide them without declaring them.
-X/Open does not specify them.
+X/Open Curses does not specify them.
.PP
-Extended terminal capability names, e.g., as defined by \fB@TIC@\ \-x\fP,
+Extended terminal capability names,
+as defined by
+.RB \%\*(`` "@TIC@ \-x" \*('',
are not stored in the arrays described here.
+.SS "Output Buffering"
+Older versions of \fI\%ncurses\fP assumed that the file descriptor
+passed to \fB\%setupterm\fP from \fB\%initscr\fP or \fB\%newterm\fP uses
+buffered I/O,
+and would write to the corresponding stream.
+In addition to the limitation that the terminal was left in
+block-buffered mode on exit
+(like System\ V
+.IR curses ),
+it was problematic because
+.I \%ncurses
+did not allow a reliable way to clean up on receiving
+.BR SIGTSTP .
+.PP
+The current version (ncurses6)
+uses output buffers managed directly by
+.IR \%ncurses .
+Some of the low-level functions described in this manual page write
+to the standard output.
+They are not signal-safe.
+The high-level functions in
+.I \%ncurses
+employ alternate versions of these functions using the more reliable
+buffering scheme.
+.SS "Function Prototypes"
+The X/Open Curses prototypes are based on the SVr4
+.I curses
+header declarations,
+which were defined at the same time the C language was first
+standardized in the late 1980s.
+.bP
+X/Open Curses uses
+.I \%const
+less effectively than a later design might,
+sometimes applying it needlessly to values that are already constant,
+and in most cases overlooking parameters that normally would use
+.IR \%const .
+Passing
+.IR \%const -qualified
+parameters to functions that do not declare them
+.I \%const
+may prevent the program from compiling.
+On the other hand,
+\*(``writable strings\*('' are an obsolescent feature.
+.IP
+As an extension,
+this implementation can be configured to change the function prototypes
+to use the
+.I \%const
+keyword.
+The
+.I \%ncurses
+ABI 6 enables this feature by default.
+.bP
+X/Open Curses prototypes \fB\%tparm\fP with a fixed number of
+parameters,
+rather than a variable argument list.
+.IP
+This implementation uses a variable argument list,
+but can be configured to use the fixed-parameter list.
+Portable applications should provide nine parameters after the format;
+zeroes are fine for this purpose.
+.IP
+In response to review comments by Thomas E. Dickey,
+X/Open Curses Issue 7 proposed the \fB\%tiparm\fP function in mid-2009.
+.IP
+While \fB\%tiparm\fP is always provided in \fI\%ncurses\fP,
+the older form is only available as a build-time configuration option.
+If not specially configured,
+\fB\%tparm\fP is the same as \fB\%tiparm\fP.
+.PP
+Both forms of \fB\%tparm\fP have drawbacks:
+.bP
+Most of the calls to \fB\%tparm\fP use only one or two parameters.
+Passing nine on each call is awkward.
+.IP
+Using
+.I long
+for the numeric parameter type is a workaround to make the parameter use
+the same amount of stack as a pointer.
+That approach dates back to the mid-1980s,
+before C was standardized.
+Since then,
+there is a standard
+(and pointers are not required to fit in a
+.IR long ).
+.bP
+Providing the right number of parameters for a variadic function
+such as \fB\%tiparm\fP can be a problem,
+in particular for string parameters.
+However,
+only a few
+.I \%term\%info
+capabilities use string parameters
+(for instance,
+the ones used for programmable function keys).
+.IP
+The \fI\%ncurses\fP library checks usage of these capabilities,
+and returns an error if the capability mishandles string parameters.
+But it cannot check if a calling program provides strings in the right
+places for the \fB\%tparm\fP calls.
+.IP
+The \fB\%@TPUT@\fR(1) program checks its use of these capabilities with
+a table,
+so that it calls \fB\%tparm\fP correctly.
+.SS "Special \fITERM\fP treatment"
+If configured to use the terminal driver,
+.\" XXX: as opposed to the Unix terminal driver, termio(s)?
+as with the MinGW port,
+.bP
+\fB\%setupterm\fP interprets a missing/empty \fITERM\fP variable as the
+special value \*(``unknown\*(''.
+.IP
+SVr4
+.I curses
+uses the special value \*(``dumb\*(''.
+.IP
+The difference between the two is that the former uses the
+.B \%generic_type
+.RB ( gn )
+.I \%term\%info
+capability,
+while the latter does not.
+A generic terminal is unsuitable for full-screen applications.
+.bP
+\fB\%setupterm\fP allows explicit use of the
+the windows console driver by checking if \fB$TERM\fP is set to
+\*(``#win32con\*('' or an abbreviation of that string.
+.SS "Other Portability Issues"
+In SVr4,
+\fB\%set_curterm\fP returns an
+.IR int ,
+.B OK
+or
+.BR ERR .
+We have chosen to implement the X/Open Curses semantics.
+.PP
+In SVr4,
+the third argument of \fB\%tputs\fP has the type
+.RB \*(`` "int (*putc)(char)" \*(''.
+.PP
+At least one implementation of X/Open Curses (Solaris) returns a value
+other than
+.B OK
+or
+.B ERR
+from \fB\%tputs\fP.
+It instead returns the length of the string,
+and does no error checking.
+.PP
+X/Open Curses notes that after calling \fB\%mvcur\fP,
+the
+.I curses
+state may not match the actual terminal state,
+and that an application should touch and refresh the window before
+resuming normal
+.I curses
+calls.
+Both
+.I \%ncurses
+and SVr4
+.I curses
+implement \fB\%mvcur\fP using the
+.I SCREEN
+data allocated in either \fB\%initscr\fP or \fB\%newterm\fP.
+So though it is documented as a
+.I \%term\%info
+function,
+\fB\%mvcur\fP is really a
+.I curses
+function that is not well specified.
+.PP
+X/Open Curses states that the old location must be given for
+\fB\%mvcur\fP to accommodate terminals that lack absolute cursor
+positioning.
+.\" X/Open Curses Issue 7, p. 161
+.I \%ncurses
+allows the caller to use \-1 for either or both old coordinates.
+The \-1 tells
+.I \%ncurses
+that the old location is unknown,
+and that it must use only absolute motion,
+as with the
+.B \%cursor_address
+.RB ( cup )
+capability,
+rather than the least costly combination of absolute and relative
+motion.
+.\" ********************************************************************
+.SH HISTORY
+SVr2 (1984) introduced the
+.I \%term\%info
+feature.
+Its programming manual mentioned the following low-level functions.
+.PP
+.TS
+lB lB
+lB lx.
+Function Description
+_
+fixterm restore terminal to \*(``in \fIcurses\fP\*('' state
+gettmode establish current terminal modes
+mvcur low level cursor motion
+putp use \fBtputs\fP to send characters via \fIputchar\fP
+resetterm set terminal modes to \*(``out of \fIcurses\fP\*(''\
+ state
+resetty reset terminal flags to stored value
+saveterm save current modes as \*(``in \fIcurses\fP\*('' state
+savetty store current terminal flags
+setterm establish terminal with given type
+setupterm establish terminal with given type
+tparm interpolate parameters into string capability
+tputs apply padding information to a string
+vidattr like \fBvidputs\fP, but output through \fIputchar\fP
+vidputs T{
+write string to terminal, applying specified attributes
+T}
+.TE
+.PP
+The programming manual also mentioned
+functions provided for
+.I termcap
+compatibility
+(commenting that they \*(``may go away at a later date\*('').
+.PP
+.TS
+lB lB
+lB lx.
+Function Description
+_
+tgetent look up \fItermcap\fP entry for given \fIname\fP
+tgetflag get Boolean entry for given \fIid\fP
+tgetnum get numeric entry for given \fIid\fP
+tgetstr get string entry for given \fIid\fP
+tgoto apply parameters to given capability
+tputs T{
+write characters via a function parameter, applying padding
+T}
+.TE
+.PP
+Early
+.I \%term\%info
+programs obtained capability values from the
+.I \%TERMINAL
+structure initialized by \fB\%setupterm\fP.
+.PP
+SVr3 (1987) extended
+.I \%term\%info
+by adding functions to retrieve capability values
+(like the
+.I termcap
+interface),
+and reusing \fB\%tgoto\fP and \fB\%tputs\fP.
+.PP
+.TS
+lB lB
+lB lx.
+Function Description
+_
+tigetflag get Boolean entry for given \fIid\fP
+tigetnum get numeric entry for given \fIid\fP
+tigetstr get string entry for given \fIid\fP
+.TE
+.PP
+SVr3 also replaced several of the SVr2
+.I \%term\%info
+functions that had no counterpart in the
+.I termcap
+interface,
+documenting them as obsolete.
+.PP
+.TS
+lB lB
+l lx.
+Function Replaced by
+_
+crmode cbreak
+fixterm reset_prog_mode
+gettmode \fIn/a\fP
+nocrmode nocbreak
+resetterm reset_shell_mode
+saveterm def_prog_mode
+setterm setupterm
+.TE
+.PP
+SVr3 kept the \fB\%mvcur\fP,
+\fB\%vidattr\fP,
+and \fB\%vidputs\fP functions,
+along with \fB\%putp\fP,
+\fB\%tparm\fP,
+and \fB\%tputs\fP.
+The latter were needed to support padding,
+and to handle capabilities accessed by functions such as \fB\%vidattr\fP
+(which used more than the two parameters supported by \fB\%tgoto\fP).
+.PP
+SVr3 introduced the functions for switching between terminal
+descriptions;
+for example,
+\fB\%set_curterm\fP.
+Some changes reflected incremental improvements to the SVr2 library.
+.bP
+The
+.I \%TERMINAL
+type definition was introduced in SVr3.01,
+for the
+.I term
+structure provided in SVr2.
+.bP
+Various global variables such as \fB\%boolnames\fP were mentioned
+in the programming manual at this point,
+though the variables had been provided in SVr2.
+.PP
+SVr4 (1989) added the \fB\%vid_attr\fP and \fB\%vid_puts\fP functions.
+.PP
+Other low-level functions are declared in the
+.I curses
+header files of Unix systems,
+but none are documented.
+Those noted as \*(``obsolete\*('' by SVr3 remained in use by System\ V's
+\fIvi\fP(1) editor.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_initscr\fR(3X),
-\fBcurs_kernel\fR(3X),
-\fBcurs_termcap\fR(3X),
-\fBcurs_variables\fR(3X),
-\fBterm_variables\fR(3X),
-\fBputc\fR(3),
-\fBterminfo\fR(\*n)
+\fB\%curses\fP(3X),
+\fB\%curs_initscr\fP(3X),
+\fB\%curs_kernel\fP(3X),
+\fB\%curs_memleaks\fP(3X),
+\fB\%curs_termcap\fP(3X),
+\fB\%curs_variables\fP(3X),
+\fB\%putc\fP(3),
+\fB\%term_variables\fP(3X),
+\fB\%terminfo\fP(5)
diff --git a/man/curs_threads.3x b/man/curs_threads.3x
index 7776459..d49c16e 100644
--- a/man/curs_threads.3x
+++ b/man/curs_threads.3x
@@ -1,5 +1,7 @@
+'\" t
.\"***************************************************************************
-.\" Copyright (c) 2008-2014,2015 Free Software Foundation, Inc. *
+.\" Copyright 2021-2023,2024 Thomas E. Dickey *
+.\" Copyright 2008-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 *
@@ -26,577 +28,611 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_threads.3x,v 1.21 2015/04/11 10:23:49 tom Exp $
-.TH curs_threads 3X ""
+.\" $Id: curs_threads.3x,v 1.56 2024/03/16 15:35:01 tom Exp $
+.TH curs_threads 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.na
-.hy 0
.SH NAME
-\fBuse_screen\fR,
-\fBuse_window\fR \- \fBcurses\fR thread support
-.ad
-.hy
+\fI\%NCURSES_WINDOW_CB\fP,
+\fI\%NCURSES_SCREEN_CB\fP,
+\fB\%get_escdelay\fP,
+\fB\%set_escdelay\fP,
+\fB\%set_tabsize\fP,
+\fB\%use_screen\fP,
+\fB\%use_window\fP \-
+\fIcurses\fR support for multi-threaded applications
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);\fR
-.br
-\fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);\fR
-.br
-\fBint get_escdelay(void);\fR
-.br
-\fBint set_escdelay(int size);\fR
-.br
-\fBint set_tabsize(int size);\fR
-.br
-\fBint use_screen(SCREEN *scr, NCURSES_SCREEN_CB func, void *data);\fR
-.br
-\fBint use_window(WINDOW *win, NCURSES_WINDOW_CB func, void *data);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fI/* data types */
+\fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);
+\fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);
+.PP
+\fBint get_escdelay(void);
+\fBint set_escdelay(int \fIms\fP);
+\fBint set_tabsize(int \fIcols\fP);
+.PP
+\fBint use_screen(SCREEN *\fIscr\fP, NCURSES_SCREEN_CB \fIfunc\fP, void *\fIdata\fP);
+\fBint use_window(WINDOW *\fIwin\fP, NCURSES_WINDOW_CB \fIfunc\fP, void *\fIdata\fP);
+.fi
.SH DESCRIPTION
-This implementation can be configured to provide rudimentary support
-for multi-threaded applications.
-This makes a different set of libraries, e.g., \fIlibncursest\fP since
-the binary interfaces are different.
+The \fI\%ncurses\fP library can be configured to support multi-threaded
+applications in a rudimentary way.
+Such configuration produces a different set of libraries,
+named \fIlibncursest\fP,
+for example,
+since doing so alters \fI\%ncurses\fP's application binary interface
+(ABI).
.PP
-Rather than modify the interfaces to pass a thread specifier to
-each function, it adds a few functions which can be used in any
-configuration which hide the mutex's needed to prevent concurrent
-use of the global variables when configured for threading.
+Instead of modifying the programming interface (API) to make
+\fI\%ncurses\fP functions expect an additional argument specifying a
+thread,
+the library adds functions,
+usable in any configuration,
+that hide the \fImutexes\fP
+(mutual exclusion locks)
+needed to prevent concurrent access to variables shared by multiple
+threads of execution.
.PP
-In addition to forcing access to members of the \fBWINDOW\fP structure
-to be via functions (see \fBcurs_opaque\fP(3x)),
-it makes functions of the common global variables,
-e.g.,
-COLORS,
-COLOR_PAIRS,
-COLS,
-ESCDELAY,
-LINES,
-TABSIZE
-curscr,
-newscr and
-ttytype.
-Those variables are maintained as read-only values, stored in the \fBSCREEN\fP
-structure.
+\fI\%ncurses\fP threading support requires the use of functions to
+access members of the \fI\%WINDOW\fP structure (see
+\fBcurs_opaque\fP(3X)).
+It further makes functions of the common global variables
+\fB\%COLORS\fP,
+\fB\%COLOR_PAIRS\fP,
+\fB\%COLS\fP,
+\fB\%ESCDELAY\fP,
+\fB\%LINES\fP,
+\fB\%TABSIZE\fP,
+\fB\%curscr\fP,
+\fB\%newscr\fP,
+and
+\fB\%ttytype\fP,
+maintaining them as as read-only values in the \fISCREEN\fP structure.
.PP
-Even this is not enough to make a thread-safe application using curses.
-A multi-threaded application would be expected to have threads updating
-separate windows (within the same device),
-or updating on separate screens (on different devices).
-Also, a few of the global variables are considered writable by some
-applications.
+Even this is not enough to make an application using \fIcurses\fP
+thread-safe.
+We would expect a multi-threaded application to have threads updating
+separate windows (on the same device),
+and separate screens (on different devices).
+Further,
+applications expect a few of the global variables to be writable.
The functions described here address these special situations.
.PP
-The ESCDELAY and TABSIZE global variables are modified by some applications.
+The \fB\%ESCDELAY\fP and \fB\%TABSIZE\fP global variables are modified
+by some applications.
To modify them in any configuration,
-use the \fBset_escdelay\fP or \fBset_tabsize\fP functions.
+use the \fB\%set_escdelay\fP or \fB\%set_tabsize\fP functions.
Other global variables are not modifiable.
+\fBget_escdelay\fP retrieves \fB\%ESCDELAY\fP's value.
.PP
-The \fBget_escdelay\fP function returns the value for ESCDELAY.
-.PP
-The \fBuse_window\fP and \fBuse_screen\fP functions provide coarse
-granularity mutexes for their respective \fBWINDOW\fP and \fBSCREEN\fP
-parameters, and call a user-supplied function,
-passing it a \fIdata\fP parameter,
-and returning the value from the user-supplied function to the application.
+The \fBuse_window\fP and \fBuse_screen\fP functions provide
+coarse-grained mutexes for their respective \fI\%WINDOW\fP and
+\fISCREEN\fP parameters;
+they call a user-supplied function,
+pass it a \fIdata\fP parameter,
+and return the value from the user-supplied function to the application.
.\" ***************************************************************************
-.SS USAGE
-All of the ncurses library functions assume that the locale is not
+.SS Usage
+All \fI\%ncurses\fP library functions assume that the locale is not
altered during operation.
In addition,
-they use data which is maintained within a hierarchy of scopes.
-.RS 3
+they use data that is maintained within a hierarchy of scopes.
.bP
-global data, e.g., used in the low-level terminfo or termcap interfaces.
+global data used in the low-level \fIterminfo\fP or \fItermcap\fP
+interfaces
.bP
-terminal data, e.g., associated with a call to \fIset_curterm\fP.
-The terminal data are initialized when screens are created.
-.bP
-screen data, e.g., associated with a call to \fInewterm\fP or \fIinitscr\fP.
-.bP
-window data, e.g., associated with a call to \fInewwin\fP or \fIsubwin\fP.
-Windows are associated with screens.
-Pads are not necessarily associated with a particular screen.
+terminal data associated with a call to \fBset_curterm\fP(3X)
.IP
-Most curses applications operate on one or more windows within a single screen.
+Terminal data are initialized when screens are created.
.bP
-reentrant, i.e., it uses only the data passed as parameters.
-.RE
+screen data associated with a call to \fBnewterm\fP(3X) or
+\fBinitscr\fP(3X)
+.bP
+window data associated with a call to \fBnewwin\fP(3X) or
+\fBsubwin\fP(3X)
+.IP
+Windows are associated with screens.
+Pads are not necessarily associated with any particular screen.
+.IP
+Most \fIcurses\fP applications operate on one or more windows within a
+single screen.
+.bP
+reentrant data associated with \*(``pure\*('' functions that alter no
+shared variables
.PP
-This table lists the scope of data used for each symbol in the
-ncurses library when it is configured to support threading:
+The following table lists the scope of each symbol in the
+\fI\%ncurses\fP library when configured to support multi-threaded
+applications.
+.PP
.TS
-center tab(/);
-l l
-l l .
-Symbol/Scope
-=
-BC/global
-COLORS/screen (readonly)
-COLOR_PAIR/reentrant
-COLOR_PAIRS/screen (readonly)
-COLS/screen (readonly)
-ESCDELAY/screen (readonly, see \fIset_escdelay\fP)
-LINES/screen (readonly)
-PAIR_NUMBER/reentrant
-PC/global
-SP/global
-TABSIZE/screen (readonly)
-UP/global
-acs_map/screen (readonly)
-add_wch/window (stdscr)
-add_wchnstr/window (stdscr)
-add_wchstr/window (stdscr)
-addch/window (stdscr)
-addchnstr/window (stdscr)
-addchstr/window (stdscr)
-addnstr/window (stdscr)
-addnwstr/window (stdscr)
-addstr/window (stdscr)
-addwstr/window (stdscr)
-assume_default_colors/screen
-attr_get/window (stdscr)
-attr_off/window (stdscr)
-attr_on/window (stdscr)
-attr_set/window (stdscr)
-attroff/window (stdscr)
-attron/window (stdscr)
-attrset/window (stdscr)
-baudrate/screen
-beep/screen
-bkgd/window (stdscr)
-bkgdset/window (stdscr)
-bkgrnd/window (stdscr)
-bkgrndset/window (stdscr)
-boolcodes/global (readonly)
-boolfnames/global (readonly)
-boolnames/global (readonly)
-border/window (stdscr)
-border_set/window (stdscr)
-box/window (stdscr)
-box_set/window (stdscr)
-can_change_color/terminal
-cbreak/screen
-chgat/window (stdscr)
-clear/window (stdscr)
-clearok/window
-clrtobot/window (stdscr)
-clrtoeol/window (stdscr)
-color_content/screen
-color_set/window (stdscr)
-copywin/window locks(source, target)
-cur_term/terminal
-curs_set/screen
-curscr/screen (readonly)
-curses_version/global (readonly)
-def_prog_mode/terminal
-def_shell_mode/terminal
-define_key/screen
-del_curterm/screen
-delay_output/screen
-delch/window (stdscr)
-deleteln/window (stdscr)
-delscreen/global locks(screenlist, screen)
-delwin/global locks(windowlist)
-derwin/screen
-doupdate/screen
-dupwin/screen locks(window)
-echo/screen
-echo_wchar/window (stdscr)
-echochar/window (stdscr)
-endwin/screen
-erase/window (stdscr)
-erasechar/window (stdscr)
-erasewchar/window (stdscr)
-filter/global
-flash/terminal
-flushinp/screen
-get_wch/screen (input-operation)
-get_wstr/screen (input-operation)
-getattrs/window
-getbegx/window
-getbegy/window
-getbkgd/window
-getbkgrnd/window
-getcchar/reentrant
-getch/screen (input-operation)
-getcurx/window
-getcury/window
-getmaxx/window
-getmaxy/window
-getmouse/screen (input-operation)
-getn_wstr/screen (input-operation)
-getnstr/screen (input-operation)
-getparx/window
-getpary/window
-getstr/screen (input-operation)
-getwin/screen (input-operation)
-halfdelay/screen
-has_colors/terminal
-has_ic/terminal
-has_il/terminal
-has_key/screen
-hline/window (stdscr)
-hline_set/window (stdscr)
-idcok/window
-idlok/window
-immedok/window
-in_wch/window (stdscr)
-in_wchnstr/window (stdscr)
-in_wchstr/window (stdscr)
-inch/window (stdscr)
-inchnstr/window (stdscr)
-inchstr/window (stdscr)
-init_color/screen
-init_pair/screen
-initscr/global locks(screenlist)
-innstr/window (stdscr)
-innwstr/window (stdscr)
-ins_nwstr/window (stdscr)
-ins_wch/window (stdscr)
-ins_wstr/window (stdscr)
-insch/window (stdscr)
-insdelln/window (stdscr)
-insertln/window (stdscr)
-insnstr/window (stdscr)
-insstr/window (stdscr)
-instr/window (stdscr)
-intrflush/terminal
-inwstr/window (stdscr)
-is_cleared/window
-is_idcok/window
-is_idlok/window
-is_immedok/window
-is_keypad/window
-is_leaveok/window
-is_linetouched/window
-is_nodelay/window
-is_notimeout/window
-is_scrollok/window
-is_syncok/window
-is_term_resized/terminal
-is_wintouched/window
-isendwin/screen
-key_defined/screen
-key_name/global (static data)
-keybound/screen
-keyname/global (static data)
-keyok/screen
-keypad/window
-killchar/terminal
-killwchar/terminal
-leaveok/window
-longname/screen
-mcprint/terminal
-meta/screen
-mouse_trafo/window (stdscr)
-mouseinterval/screen
-mousemask/screen
-move/window (stdscr)
-mvadd_wch/window (stdscr)
-mvadd_wchnstr/window (stdscr)
-mvadd_wchstr/window (stdscr)
-mvaddch/window (stdscr)
-mvaddchnstr/window (stdscr)
-mvaddchstr/window (stdscr)
-mvaddnstr/window (stdscr)
-mvaddnwstr/window (stdscr)
-mvaddstr/window (stdscr)
-mvaddwstr/window (stdscr)
-mvchgat/window (stdscr)
-mvcur/screen
-mvdelch/window (stdscr)
-mvderwin/window (stdscr)
-mvget_wch/screen (input-operation)
-mvget_wstr/screen (input-operation)
-mvgetch/screen (input-operation)
-mvgetn_wstr/screen (input-operation)
-mvgetnstr/screen (input-operation)
-mvgetstr/screen (input-operation)
-mvhline/window (stdscr)
-mvhline_set/window (stdscr)
-mvin_wch/window (stdscr)
-mvin_wchnstr/window (stdscr)
-mvin_wchstr/window (stdscr)
-mvinch/window (stdscr)
-mvinchnstr/window (stdscr)
-mvinchstr/window (stdscr)
-mvinnstr/window (stdscr)
-mvinnwstr/window (stdscr)
-mvins_nwstr/window (stdscr)
-mvins_wch/window (stdscr)
-mvins_wstr/window (stdscr)
-mvinsch/window (stdscr)
-mvinsnstr/window (stdscr)
-mvinsstr/window (stdscr)
-mvinstr/window (stdscr)
-mvinwstr/window (stdscr)
-mvprintw/window (stdscr)
-mvscanw/screen
-mvvline/window (stdscr)
-mvvline_set/window (stdscr)
-mvwadd_wch/window
-mvwadd_wchnstr/window
-mvwadd_wchstr/window
-mvwaddch/window
-mvwaddchnstr/window
-mvwaddchstr/window
-mvwaddnstr/window
-mvwaddnwstr/window
-mvwaddstr/window
-mvwaddwstr/window
-mvwchgat/window
-mvwdelch/window
-mvwget_wch/screen (input-operation)
-mvwget_wstr/screen (input-operation)
-mvwgetch/screen (input-operation)
-mvwgetn_wstr/screen (input-operation)
-mvwgetnstr/screen (input-operation)
-mvwgetstr/screen (input-operation)
-mvwhline/window
-mvwhline_set/window
-mvwin/window
-mvwin_wch/window
-mvwin_wchnstr/window
-mvwin_wchstr/window
-mvwinch/window
-mvwinchnstr/window
-mvwinchstr/window
-mvwinnstr/window
-mvwinnwstr/window
-mvwins_nwstr/window
-mvwins_wch/window
-mvwins_wstr/window
-mvwinsch/window
-mvwinsnstr/window
-mvwinsstr/window
-mvwinstr/window
-mvwinwstr/window
-mvwprintw/window
-mvwscanw/screen
-mvwvline/window
-mvwvline_set/window
-napms/reentrant
-newpad/global locks(windowlist)
-newscr/screen (readonly)
-newterm/global locks(screenlist)
-newwin/global locks(windowlist)
-nl/screen
-nocbreak/screen
-nodelay/window
-noecho/screen
-nofilter/global
-nonl/screen
-noqiflush/terminal
-noraw/screen
-notimeout/window
-numcodes/global (readonly)
-numfnames/global (readonly)
-numnames/global (readonly)
-ospeed/global
-overlay/window locks(source, target)
-overwrite/window locks(source, target)
-pair_content/screen
-pecho_wchar/screen
-pechochar/screen
-pnoutrefresh/screen
-prefresh/screen
-printw/window
-putp/global
-putwin/window
-qiflush/terminal
-raw/screen
-redrawwin/window
-refresh/screen
-reset_prog_mode/screen
-reset_shell_mode/screen
-resetty/terminal
-resize_term/screen locks(windowlist)
-resizeterm/screen
-restartterm/screen
-ripoffline/global (static data)
-savetty/terminal
-scanw/screen
-scr_dump/screen
-scr_init/screen
-scr_restore/screen
-scr_set/screen
-scrl/window (stdscr)
-scroll/window
-scrollok/window
-set_curterm/screen
-set_escdelay/screen
-set_tabsize/screen
-set_term/global locks(screenlist, screen)
-setcchar/reentrant
-setscrreg/window (stdscr)
-setupterm/global
-slk_attr/screen
-slk_attr_off/screen
-slk_attr_on/screen
-slk_attr_set/screen
-slk_attroff/screen
-slk_attron/screen
-slk_attrset/screen
-slk_clear/screen
-slk_color/screen
-slk_init/screen
-slk_label/screen
-slk_noutrefresh/screen
-slk_refresh/screen
-slk_restore/screen
-slk_set/screen
-slk_touch/screen
-slk_wset/screen
-standend/window
-standout/window
-start_color/screen
-stdscr/screen (readonly)
-strcodes/global (readonly)
-strfnames/global (readonly)
-strnames/global (readonly)
-subpad/window
-subwin/window
-syncok/window
-term_attrs/screen
-termattrs/screen
-termname/terminal
-tgetent/global
-tgetflag/global
-tgetnum/global
-tgetstr/global
-tgoto/global
-tigetflag/terminal
-tigetnum/terminal
-tigetstr/terminal
-timeout/window (stdscr)
-touchline/window
-touchwin/window
-tparm/global (static data)
-tputs/screen
-trace/global (static data)
-ttytype/screen (readonly)
-typeahead/screen
-unctrl/screen
-unget_wch/screen (input-operation)
-ungetch/screen (input-operation)
-ungetmouse/screen (input-operation)
-untouchwin/window
-use_default_colors/screen
-use_env/global (static data)
-use_extended_names/global (static data)
-use_legacy_coding/screen
-use_screen/global locks(screenlist, screen)
-use_window/global locks(windowlist, window)
-vid_attr/screen
-vid_puts/screen
-vidattr/screen
-vidputs/screen
-vline/window (stdscr)
-vline_set/window (stdscr)
-vw_printw/window
-vw_scanw/screen
-vwprintw/window
-vwscanw/screen
-wadd_wch/window
-wadd_wchnstr/window
-wadd_wchstr/window
-waddch/window
-waddchnstr/window
-waddchstr/window
-waddnstr/window
-waddnwstr/window
-waddstr/window
-waddwstr/window
-wattr_get/window
-wattr_off/window
-wattr_on/window
-wattr_set/window
-wattroff/window
-wattron/window
-wattrset/window
-wbkgd/window
-wbkgdset/window
-wbkgrnd/window
-wbkgrndset/window
-wborder/window
-wborder_set/window
-wchgat/window
-wclear/window
-wclrtobot/window
-wclrtoeol/window
-wcolor_set/window
-wcursyncup/screen (affects window plus parents)
-wdelch/window
-wdeleteln/window
-wecho_wchar/window
-wechochar/window
-wenclose/window
-werase/window
-wget_wch/screen (input-operation)
-wget_wstr/screen (input-operation)
-wgetbkgrnd/window
-wgetch/screen (input-operation)
-wgetdelay/window
-wgetn_wstr/screen (input-operation)
-wgetnstr/screen (input-operation)
-wgetparent/window
-wgetscrreg/window
-wgetstr/screen (input-operation)
-whline/window
-whline_set/window
-win_wch/window
-win_wchnstr/window
-win_wchstr/window
-winch/window
-winchnstr/window
-winchstr/window
-winnstr/window
-winnwstr/window
-wins_nwstr/window
-wins_wch/window
-wins_wstr/window
-winsch/window
-winsdelln/window
-winsertln/window
-winsnstr/window
-winsstr/window
-winstr/window
-winwstr/window
-wmouse_trafo/window
-wmove/window
-wnoutrefresh/screen
-wprintw/window
-wredrawln/window
-wrefresh/screen
-wresize/window locks(windowlist)
-wscanw/screen
-wscrl/window
-wsetscrreg/window
-wstandend/window
-wstandout/window
-wsyncdown/screen (affects window plus parents)
-wsyncup/screen (affects window plus parents)
-wtimeout/window
-wtouchln/window
-wunctrl/global (static data)
-wvline/window
-wvline_set/window
+center;
+Lb2 Lb
+Lb2 Lx.
+Symbol Scope
+_
+BC global
+COLORS screen (read-only)
+COLOR_PAIR reentrant
+COLOR_PAIRS screen (read-only)
+COLS screen (read-only)
+ESCDELAY screen (read-only; see \fBset_escdelay\fP)
+LINES screen (read-only)
+PAIR_NUMBER reentrant
+PC global
+SP global
+TABSIZE screen (read-only; see \fBset_tabsize\fP)
+UP global
+acs_map screen (read-only)
+add_wch window (\fBstdscr\fP)
+add_wchnstr window (\fBstdscr\fP)
+add_wchstr window (\fBstdscr\fP)
+addch window (\fBstdscr\fP)
+addchnstr window (\fBstdscr\fP)
+addchstr window (\fBstdscr\fP)
+addnstr window (\fBstdscr\fP)
+addnwstr window (\fBstdscr\fP)
+addstr window (\fBstdscr\fP)
+addwstr window (\fBstdscr\fP)
+assume_default_colors screen
+attr_get window (\fBstdscr\fP)
+attr_off window (\fBstdscr\fP)
+attr_on window (\fBstdscr\fP)
+attr_set window (\fBstdscr\fP)
+attroff window (\fBstdscr\fP)
+attron window (\fBstdscr\fP)
+attrset window (\fBstdscr\fP)
+baudrate screen
+beep screen
+bkgd window (\fBstdscr\fP)
+bkgdset window (\fBstdscr\fP)
+bkgrnd window (\fBstdscr\fP)
+bkgrndset window (\fBstdscr\fP)
+boolcodes global (read-only)
+boolfnames global (read-only)
+boolnames global (read-only)
+border window (\fBstdscr\fP)
+border_set window (\fBstdscr\fP)
+box window (\fBstdscr\fP)
+box_set window (\fBstdscr\fP)
+can_change_color terminal
+cbreak screen
+chgat window (\fBstdscr\fP)
+clear window (\fBstdscr\fP)
+clearok window
+clrtobot window (\fBstdscr\fP)
+clrtoeol window (\fBstdscr\fP)
+color_content screen
+color_set window (\fBstdscr\fP)
+copywin window (locks source, target)
+cur_term terminal
+curs_set screen
+curscr screen (read-only)
+curses_version global (read-only)
+def_prog_mode terminal
+def_shell_mode terminal
+define_key screen
+del_curterm screen
+delay_output screen
+delch window (\fBstdscr\fP)
+deleteln window (\fBstdscr\fP)
+delscreen global (locks screen list, screen)
+delwin global (locks window list)
+derwin screen
+doupdate screen
+dupwin screen (locks window)
+echo screen
+echo_wchar window (\fBstdscr\fP)
+echochar window (\fBstdscr\fP)
+endwin screen
+erase window (\fBstdscr\fP)
+erasechar window (\fBstdscr\fP)
+erasewchar window (\fBstdscr\fP)
+filter global
+flash terminal
+flushinp screen
+get_wch screen (input operation)
+get_wstr screen (input operation)
+getattrs window
+getbegx window
+getbegy window
+getbkgd window
+getbkgrnd window
+getcchar reentrant
+getch screen (input operation)
+getcurx window
+getcury window
+getmaxx window
+getmaxy window
+getmouse screen (input operation)
+getn_wstr screen (input operation)
+getnstr screen (input operation)
+getparx window
+getpary window
+getstr screen (input operation)
+getwin screen (input operation)
+halfdelay screen
+has_colors terminal
+has_ic terminal
+has_il terminal
+has_key screen
+hline window (\fBstdscr\fP)
+hline_set window (\fBstdscr\fP)
+idcok window
+idlok window
+immedok window
+in_wch window (\fBstdscr\fP)
+in_wchnstr window (\fBstdscr\fP)
+in_wchstr window (\fBstdscr\fP)
+inch window (\fBstdscr\fP)
+inchnstr window (\fBstdscr\fP)
+inchstr window (\fBstdscr\fP)
+init_color screen
+init_pair screen
+initscr global (locks screen list)
+innstr window (\fBstdscr\fP)
+innwstr window (\fBstdscr\fP)
+ins_nwstr window (\fBstdscr\fP)
+ins_wch window (\fBstdscr\fP)
+ins_wstr window (\fBstdscr\fP)
+insch window (\fBstdscr\fP)
+insdelln window (\fBstdscr\fP)
+insertln window (\fBstdscr\fP)
+insnstr window (\fBstdscr\fP)
+insstr window (\fBstdscr\fP)
+instr window (\fBstdscr\fP)
+intrflush terminal
+inwstr window (\fBstdscr\fP)
+is_cleared window
+is_idcok window
+is_idlok window
+is_immedok window
+is_keypad window
+is_leaveok window
+is_linetouched window
+is_nodelay window
+is_notimeout window
+is_scrollok window
+is_syncok window
+is_term_resized terminal
+is_wintouched window
+isendwin screen
+key_defined screen
+key_name global (static data)
+keybound screen
+keyname global (static data)
+keyok screen
+keypad window
+killchar terminal
+killwchar terminal
+leaveok window
+longname screen
+mcprint terminal
+meta screen
+mouse_trafo window (\fBstdscr\fP)
+mouseinterval screen
+mousemask screen
+move window (\fBstdscr\fP)
+mvadd_wch window (\fBstdscr\fP)
+mvadd_wchnstr window (\fBstdscr\fP)
+mvadd_wchstr window (\fBstdscr\fP)
+mvaddch window (\fBstdscr\fP)
+mvaddchnstr window (\fBstdscr\fP)
+mvaddchstr window (\fBstdscr\fP)
+mvaddnstr window (\fBstdscr\fP)
+mvaddnwstr window (\fBstdscr\fP)
+mvaddstr window (\fBstdscr\fP)
+mvaddwstr window (\fBstdscr\fP)
+mvchgat window (\fBstdscr\fP)
+mvcur screen
+mvdelch window (\fBstdscr\fP)
+mvderwin window (\fBstdscr\fP)
+mvget_wch screen (input operation)
+mvget_wstr screen (input operation)
+mvgetch screen (input operation)
+mvgetn_wstr screen (input operation)
+mvgetnstr screen (input operation)
+mvgetstr screen (input operation)
+mvhline window (\fBstdscr\fP)
+mvhline_set window (\fBstdscr\fP)
+mvin_wch window (\fBstdscr\fP)
+mvin_wchnstr window (\fBstdscr\fP)
+mvin_wchstr window (\fBstdscr\fP)
+mvinch window (\fBstdscr\fP)
+mvinchnstr window (\fBstdscr\fP)
+mvinchstr window (\fBstdscr\fP)
+mvinnstr window (\fBstdscr\fP)
+mvinnwstr window (\fBstdscr\fP)
+mvins_nwstr window (\fBstdscr\fP)
+mvins_wch window (\fBstdscr\fP)
+mvins_wstr window (\fBstdscr\fP)
+mvinsch window (\fBstdscr\fP)
+mvinsnstr window (\fBstdscr\fP)
+mvinsstr window (\fBstdscr\fP)
+mvinstr window (\fBstdscr\fP)
+mvinwstr window (\fBstdscr\fP)
+mvprintw window (\fBstdscr\fP)
+mvscanw screen
+mvvline window (\fBstdscr\fP)
+mvvline_set window (\fBstdscr\fP)
+mvwadd_wch window
+mvwadd_wchnstr window
+mvwadd_wchstr window
+mvwaddch window
+mvwaddchnstr window
+mvwaddchstr window
+mvwaddnstr window
+mvwaddnwstr window
+mvwaddstr window
+mvwaddwstr window
+mvwchgat window
+mvwdelch window
+mvwget_wch screen (input operation)
+mvwget_wstr screen (input operation)
+mvwgetch screen (input operation)
+mvwgetn_wstr screen (input operation)
+mvwgetnstr screen (input operation)
+mvwgetstr screen (input operation)
+mvwhline window
+mvwhline_set window
+mvwin window
+mvwin_wch window
+mvwin_wchnstr window
+mvwin_wchstr window
+mvwinch window
+mvwinchnstr window
+mvwinchstr window
+mvwinnstr window
+mvwinnwstr window
+mvwins_nwstr window
+mvwins_wch window
+mvwins_wstr window
+mvwinsch window
+mvwinsnstr window
+mvwinsstr window
+mvwinstr window
+mvwinwstr window
+mvwprintw window
+mvwscanw screen
+mvwvline window
+mvwvline_set window
+napms reentrant
+newpad global (locks window list)
+newscr screen (read-only)
+newterm global (locks screen list)
+newwin global (locks window list)
+nl screen
+nocbreak screen
+nodelay window
+noecho screen
+nofilter global
+nonl screen
+noqiflush terminal
+noraw screen
+notimeout window
+numcodes global (read-only)
+numfnames global (read-only)
+numnames global (read-only)
+ospeed global
+overlay window (locks source, target)
+overwrite window (locks source, target)
+pair_content screen
+pecho_wchar screen
+pechochar screen
+pnoutrefresh screen
+prefresh screen
+printw window
+putp global
+putwin window
+qiflush terminal
+raw screen
+redrawwin window
+refresh screen
+reset_prog_mode screen
+reset_shell_mode screen
+resetty terminal
+resize_term screen (locks window list)
+resizeterm screen
+restartterm screen
+ripoffline global (static data)
+savetty terminal
+scanw screen
+scr_dump screen
+scr_init screen
+scr_restore screen
+scr_set screen
+scrl window (\fBstdscr\fP)
+scroll window
+scrollok window
+set_curterm screen
+set_escdelay screen
+set_tabsize screen
+set_term global (locks screen list, screen)
+setcchar reentrant
+setscrreg window (\fBstdscr\fP)
+setupterm global
+slk_attr screen
+slk_attr_off screen
+slk_attr_on screen
+slk_attr_set screen
+slk_attroff screen
+slk_attron screen
+slk_attrset screen
+slk_clear screen
+slk_color screen
+slk_init screen
+slk_label screen
+slk_noutrefresh screen
+slk_refresh screen
+slk_restore screen
+slk_set screen
+slk_touch screen
+slk_wset screen
+standend window
+standout window
+start_color screen
+\fBstdscr\fP screen (read-only)
+strcodes global (read-only)
+strfnames global (read-only)
+strnames global (read-only)
+subpad window
+subwin window
+syncok window
+term_attrs screen
+termattrs screen
+termname terminal
+tgetent global
+tgetflag global
+tgetnum global
+tgetstr global
+tgoto global
+tigetflag terminal
+tigetnum terminal
+tigetstr terminal
+timeout window (\fBstdscr\fP)
+touchline window
+touchwin window
+tparm global (static data)
+tputs screen
+trace global (static data)
+ttytype screen (read-only)
+typeahead screen
+unctrl screen
+unget_wch screen (input operation)
+ungetch screen (input operation)
+ungetmouse screen (input operation)
+untouchwin window
+use_default_colors screen
+use_env global (static data)
+use_extended_names global (static data)
+use_legacy_coding screen
+use_screen global (locks screen list, screen)
+use_window global (locks window list, window)
+vid_attr screen
+vid_puts screen
+vidattr screen
+vidputs screen
+vline window (\fBstdscr\fP)
+vline_set window (\fBstdscr\fP)
+vw_printw window
+vw_scanw screen
+vwprintw window
+vwscanw screen
+wadd_wch window
+wadd_wchnstr window
+wadd_wchstr window
+waddch window
+waddchnstr window
+waddchstr window
+waddnstr window
+waddnwstr window
+waddstr window
+waddwstr window
+wattr_get window
+wattr_off window
+wattr_on window
+wattr_set window
+wattroff window
+wattron window
+wattrset window
+wbkgd window
+wbkgdset window
+wbkgrnd window
+wbkgrndset window
+wborder window
+wborder_set window
+wchgat window
+wclear window
+wclrtobot window
+wclrtoeol window
+wcolor_set window
+wcursyncup screen (affects window plus parents)
+wdelch window
+wdeleteln window
+wecho_wchar window
+wechochar window
+wenclose window
+werase window
+wget_wch screen (input operation)
+wget_wstr screen (input operation)
+wgetbkgrnd window
+wgetch screen (input operation)
+wgetdelay window
+wgetn_wstr screen (input operation)
+wgetnstr screen (input operation)
+wgetparent window
+wgetscrreg window
+wgetstr screen (input operation)
+whline window
+whline_set window
+win_wch window
+win_wchnstr window
+win_wchstr window
+winch window
+winchnstr window
+winchstr window
+winnstr window
+winnwstr window
+wins_nwstr window
+wins_wch window
+wins_wstr window
+winsch window
+winsdelln window
+winsertln window
+winsnstr window
+winsstr window
+winstr window
+winwstr window
+wmouse_trafo window
+wmove window
+wnoutrefresh screen
+wprintw window
+wredrawln window
+wrefresh screen
+wresize window (locks window list)
+wscanw screen
+wscrl window
+wsetscrreg window
+wstandend window
+wstandout window
+wsyncdown screen (affects window plus parents)
+wsyncup screen (affects window plus parents)
+wtimeout window
+wtouchln window
+wunctrl global (static data)
+wvline window
+wvline_set window
.TE
.\" ***************************************************************************
.SH RETURN VALUE
-These functions all return \fBTRUE\fP or \fBFALSE\fP, except as noted.
+\fB\%get_escdelay\fP returns the value of \fB\%ESCDELAY\fP.
+\fB\%set_escdelay\fP and \fB\%set_tabsize\fP return \fBERR\fP upon
+failure and \fBOK\fP upon successful completion.
+\fB\%use_screen\fP and \fB\%use_window\fP return the \fIint\fP returned
+by the user-supplied function they are called with.
.SH NOTES
-Both a macro and a function are provided for each name.
+\fI\%ncurses\fP provides both a C function and a preprocessor macro for
+each function documented in this page.
.SH PORTABILITY
-These routines are specific to ncurses.
+These 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 ncurses extensions
-be conditioned using NCURSES_VERSION.
+It is recommended that any code depending on \fI\%ncurses\fP extensions
+be conditioned using \fB\%NCURSES_VERSION\fP.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_opaque\fR(3X),
-\fBcurs_variables\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_opaque\fP(3X),
+\fB\%curs_variables\fP(3X)
diff --git a/man/curs_touch.3x b/man/curs_touch.3x
index f65d2f9..613b695 100644
--- a/man/curs_touch.3x
+++ b/man/curs_touch.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2020,2015 Free Software Foundation, Inc. *
+.\" 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 *
.\" copy of this software and associated documentation files (the *
@@ -26,87 +27,98 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_touch.3x,v 1.15 2015/04/11 10:23:49 tom Exp $
-.TH curs_touch 3X ""
-.na
-.hy 0
+.\" $Id: curs_touch.3x,v 1.47 2024/04/20 21:20:07 tom Exp $
+.TH curs_touch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBtouchwin\fR,
-\fBtouchline\fR,
-\fBuntouchwin\fR,
-\fBwtouchln\fR,
-\fBis_linetouched\fR,
-\fBis_wintouched\fR \- \fBcurses\fR refresh control routines
-.ad
-.hy
+\fB\%touchwin\fP,
+\fB\%touchline\fP,
+\fB\%untouchwin\fP,
+\fB\%wtouchln\fP,
+\fB\%is_linetouched\fP,
+\fB\%is_wintouched\fP \-
+control terminal output refresh in a \fIcurses\fR window
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.br
-\fBint touchwin(WINDOW *win);\fR
-.br
-\fBint touchline(WINDOW *win, int start, int count);\fR
-.br
-\fBint untouchwin(WINDOW *win);\fR
-.br
-\fBint wtouchln(WINDOW *win, int y, int n, int changed);\fR
-.br
-\fBbool is_linetouched(WINDOW *win, int line);\fR
-.br
-\fBbool is_wintouched(WINDOW *win);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint touchline(WINDOW *\fIwin\fP, int \fIstart\fP, int \fIcount\fP);
+.PP
+\fBint touchwin(WINDOW *\fIwin\fP);
+\fBint wtouchln(WINDOW *\fIwin\fP, int \fIy\fP, int \fIn\fP, int \fIchanged\fP);
+.PP
+\fBint untouchwin(WINDOW *\fIwin\fP);
+.PP
+\fBbool is_linetouched(WINDOW *\fIwin\fP, int \fIline\fP);
+\fBbool is_wintouched(WINDOW *\fIwin\fP);
+.fi
.SH DESCRIPTION
-The \fBtouchwin\fR and \fBtouchline\fR routines throw away all
+The \fB\%touchwin\fP and \fB\%touchline\fP routines throw away all
optimization information about which parts of the window have been
-touched, by pretending that the entire window has been drawn on. This
+touched, by pretending that the entire window has been drawn on.
+This
is sometimes necessary when using overlapping windows, since a change
to one window affects the other window, but the records of which lines
-have been changed in the other window do not reflect the change. The
-routine \fBtouchline\fR only pretends that \fIcount\fR lines have been
-changed, beginning with line \fIstart\fR.
+have been changed in the other window do not reflect the change.
+The
+routine \fB\%touchline\fP only pretends that \fIcount\fP lines have been
+changed, beginning with line \fIstart\fP.
.PP
-The \fBuntouchwin\fR routine marks all lines in the window as unchanged since
-the last call to \fBwrefresh\fR.
+The \fB\%untouchwin\fP routine marks all lines in the window as unchanged since
+the last call to \fB\%wrefresh\fP.
.PP
-The \fBwtouchln\fR routine makes \fIn\fR lines in the window, starting
-at line \fIy\fR, look as if they have (\fIchanged\fR\fB=1\fR) or have
-not (\fIchanged\fR\fB=0\fR) been changed since the last call to
-\fBwrefresh\fR.
+The \fB\%wtouchln\fP routine makes \fIn\fP lines in the window, starting
+at line \fIy\fR, look as if they have (\fIchanged\fB=1\fR) or have
+not (\fIchanged\fB=0\fR) been changed since the last call to
+\fB\%wrefresh\fP.
.PP
-The \fBis_linetouched\fR and \fBis_wintouched\fR routines return
-\fBTRUE\fR if the specified line/window was modified since the last
-call to \fBwrefresh\fR; otherwise they return \fBFALSE\fR. In
-addition, \fBis_linetouched\fR returns \fBERR\fR if \fIline\fR is not
+The \fB\%is_linetouched\fP and \fB\%is_wintouched\fP routines return
+\fBTRUE\fP if the specified line/window was modified since the last
+call to \fB\%wrefresh\fP; otherwise they return \fBFALSE\fP. In
+addition, \fB\%is_linetouched\fP returns \fBERR\fP if \fIline\fP is not
valid for the given window.
.SH RETURN VALUE
-All routines return the integer \fBERR\fR upon failure and an integer value
-other than \fBERR\fR upon successful completion, unless otherwise noted in the
+All routines return the integer \fBERR\fP upon failure and an integer value
+other than \fBERR\fP upon successful completion, unless otherwise noted in the
preceding routine descriptions.
.PP
-X/Open does not define any error conditions.
+X/Open Curses does not specify any error conditions.
In this implementation
-.RS
+.RS 3
.TP 5
\fBis_linetouched\fP
-returns an error
+returns an error
if the window pointer is null, or
-if the line number is outside the window.
-Note that ERR is distinct from \fBTRUE\fP and \fBFALSE\fP, which are the normal return values of this function.
+if the line number is outside the window boundaries.
+.IP
+The constant \fBERR\fP is distinct from \fBTRUE\fP and \fBFALSE\fP,
+which are the normal return values of this function.
+Because the function returns a \fBbool\fP,
+returning \fBERR\fP (which is neither \fBTRUE\fP nor \fBFALSE\fP)
+may not be supported by the compiler.
+.IP
+To provide error-checking and also match the X/Open function prototype,
+the \fBERR\fP is provided by a macro named \fB\%is_linetouched\fP.
+The actual function returns \fBFALSE\fP when it detects an error.
.TP 5
\fBwtouchln\fP
-returns an error
+returns an error
if the window pointer is null, or
-if the line number is outside the window.
+if the line number is outside the window boundaries.
.RE
-.SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions.
-.PP
-Some historic curses implementations had, as an undocumented feature, the
-ability to do the equivalent of \fBclearok(..., 1)\fR by saying
-\fBtouchwin(stdscr)\fR or \fBclear(stdscr)\fR. This will not work under
-ncurses.
.SH NOTES
-Note that all routines except \fBwtouchln\fR may be macros.
+All of these routines except \fB\%wtouchln\fP may be macros.
+.SH PORTABILITY
+These functions were introduced by SVr4.
+The Solaris \fIcurses\fP header file,
+for instance, defines both an actual function and macro for each.
+The macros give the same result as the actual functions.
+SVr4 \fIcurses\fP does not check the window parameter \fIwin\fP to ensure
+that it is not \fBNULL\fP;
+otherwise this implementation behaves the same as SVr4.
+.PP
+X/Open Curses, Issue 4 describes these functions,
+but defines no error conditions.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_refresh\fR(3X),
-\fBcurs_variables\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_variables\fP(3X)
diff --git a/man/curs_trace.3x b/man/curs_trace.3x
index 00e7bd6..ddae791 100644
--- a/man/curs_trace.3x
+++ b/man/curs_trace.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2000-2010,2015 Free Software Foundation, Inc. *
+.\" Copyright 2019-2023,2024 Thomas E. Dickey *
+.\" Copyright 2000-2016,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 *
@@ -26,83 +27,135 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_trace.3x,v 1.13 2015/07/20 22:54:44 tom Exp $
+.\" $Id: curs_trace.3x,v 1.50 2024/04/20 21:24:19 tom Exp $
+.TH curs_trace 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.TH curs_trace 3X ""
+.
+.de dS \" Start unfilled display.
+.nr aD \n(.j
.na
-.hy 0
+..
+.
+.de dE \" End unfilled display.
+.ad \n(.j
+.rr aD
+..
+.
.SH NAME
-\fB_tracef\fR,
-\fB_tracedump\fR,
-\fB_traceattr\fR,
-\fB_traceattr2\fR,
-\fB_nc_tracebits\fR,
-\fB_tracecchar_t\fR,
-\fB_tracecchar_t2\fR,
-\fB_tracechar\fR,
-\fB_tracechtype\fR,
-\fB_tracechtype2\fR,
-\fB_tracemouse\fR,
-\fBtrace\fR \- \fBcurses\fR debugging routines
-.ad
-.hy
+\fB\%curses_trace\fP,
+\fB\%trace\fP,
+\fB\%_tracef\fP,
+\fB\%_traceattr\fP,
+\fB\%_traceattr2\fP,
+\fB\%_tracecchar_t\fP,
+\fB\%_tracecchar_t2\fP,
+\fB\%_tracechar\fP,
+\fB\%_tracechtype\fP,
+\fB\%_tracechtype2\fP,
+\fB\%_nc_tracebits\fP,
+\fB\%_tracedump\fP,
+\fB\%_tracemouse\fP \-
+\fIcurses\fR debugging routines
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBvoid _tracef(const char *\fP\fIformat\fP\fB, ...);\fR
-.br
-\fBvoid _tracedump(const char *\fP\fIlabel\fP\fB, WINDOW *\fP\fIwin\fP\fB);\fR
-.br
-\fBchar *_traceattr(attr_t \fP\fIattr\fP\fB);\fR
-.br
-\fBchar *_traceattr2(int \fP\fIbuffer\fP\fB, chtype \fP\fIch\fP\fB);\fR
-.br
-\fBchar *_nc_tracebits(void);\fR
-.br
-\fBchar * _tracecchar_t(const cchar_t *\fP\fIstring\fP\fB);\fR
-.br
-\fBchar * _tracecchar_t2(int \fP\fIbuffer\fP\fB, const cchar_t *\fP\fIstring\fP\fB);\fR
-.br
-\fBchar *_tracechar(int \fP\fIch\fP\fB);\fR
-.br
-\fBchar *_tracechtype(chtype \fP\fIch\fP\fB);\fR
-.br
-\fBchar *_tracechtype2(int \fP\fIbuffer\fP\fB, chtype \fP\fIch\fP\fB);\fR
-.br
-\fBchar *_tracemouse(const MEVENT *\fP\fIevent\fP\fB);\fR
-.br
-\fBvoid trace(const unsigned int \fP\fIparam\fP\fB);\fR
-.SH DESCRIPTION
-The \fBtrace\fR routines are used for debugging the ncurses libraries,
-as well as applications which use the ncurses libraries.
-These functions are normally available only with the debugging library
-e.g., \fIlibncurses_g.a\fR, but may be compiled into any model (shared, static,
-profile) by defining the symbol \fBTRACE\fR.
-Additionally, some functions are only available with the wide-character
-configuration of the libraries.
+.nf
+\fB#include <curses.h>
.PP
+\fBunsigned curses_trace(const unsigned \fItrace-mask\fP);
+.PP
+\fBvoid _tracef(const char *\fIformat\fP, ...);
+.PP
+\fBchar *_traceattr(attr_t \fIattr\fP);
+\fBchar *_traceattr2(int \fIbuffer\fP, chtype \fIch\fP);
+\fBchar *_tracecchar_t(const cchar_t *\fIstring\fP);
+\fBchar *_tracecchar_t2(int \fIbuffer\fP, const cchar_t *\fIstring\fP);
+\fBchar *_tracechar(int \fIc\fP);
+\fBchar *_tracechtype(chtype \fIch\fP);
+\fBchar *_tracechtype2(int \fIbuffer\fP, chtype \fIch\fP);
+.PP
+\fBvoid _tracedump(const char *\fIlabel\fP, WINDOW *\fIwin\fP);
+\fBchar *_nc_tracebits(void);
+\fBchar *_tracemouse(const MEVENT *\fIevent\fP);
+.PP
+\fI/* deprecated */\fP
+\fBvoid trace(const unsigned int \fItrace-mask\fP);
+.fi
+.SH DESCRIPTION
+The \fIcurses trace\fP routines are used for debugging the
+\fI\%ncurses\fP libraries,
+as well as applications which use the \fI\%ncurses\fP libraries.
+Some limitations apply:
+.bP
+Aside from \fBcurses_trace\fP,
+the other functions are normally available only with the debugging library
+e.g., \fBlibncurses_g.a\fP.
+.IP
+All of the trace functions may be compiled into any model (shared, static,
+profile) by defining the symbol \fBTRACE\fP.
+.bP
+Additionally, the functions which use \fBcchar_t\fP
+are only available with the wide-character configuration of the libraries.
+.SS Functions
The principal parts of this interface are
.bP
-\fBtrace\fR, which selectively enables different tracing features, and
+\fBcurses_trace\fP, which selectively enables different tracing features, and
.bP
-\fB_tracef\fR, which writes formatted data to the \fItrace\fR file.
+\fB_tracef\fP, which writes formatted data to the \fItrace\fP file.
+.IP
+The other functions either return a pointer to a string-area
+(allocated by the corresponding function), or return no value
+(such as \fB_tracedump\fP,
+which implements the screen dump for \fBTRACE_UPDATE\fP).
+The caller should not free these strings,
+since the allocation is reused on successive calls.
+To work around the problem of a single string-area per function,
+some use a buffer-number parameter, telling the library to allocate
+additional string-areas.
.PP
-Calling \fBtrace\fR with a nonzero parameter opens the file \fBtrace\fR
-in the current directory for output.
-The parameter is formed by OR'ing
-values from the list of \fBTRACE_\fP\fIxxx\fR definitions in \fB<curses.h>\fR.
+The \fBcurses_trace\fP function is always available,
+whether or not the other trace functions are available:
+.bP
+If tracing is available,
+calling \fBcurses_trace\fP with a nonzero parameter
+updates the trace mask,
+and returns the previous trace mask.
+.IP
+When the trace mask is nonzero,
+\fI\%ncurses\fP creates the file \*(``trace\*('' in the current directory for output.
+If the file already exists, no tracing is done.
+.bP
+If tracing is not available, \fBcurses_trace\fP returns zero (0).
+.SS "Trace Parameter"
+The trace parameter is formed by OR'ing
+values from the list of \fBTRACE_\fIxxx\fR definitions in \fB<curses.h>\fR.
These include:
.TP 5
.B TRACE_DISABLE
-turn off tracing.
+turn off tracing by passing a zero parameter.
+.IP
+The library flushes the output file,
+but retains an open file-descriptor to the trace file
+so that it can resume tracing later if a nonzero parameter is passed
+to the \fBcurses_trace\fP function.
.TP 5
.B TRACE_TIMES
trace user and system times of updates.
.TP 5
.B TRACE_TPUTS
-trace tputs calls.
+trace \fBtputs\fP(3X) calls.
.TP 5
.B TRACE_UPDATE
trace update actions, old & new screens.
@@ -123,7 +176,7 @@
The parameters for each call are traced, as well as return values.
.TP 5
.B TRACE_VIRTPUT
-trace virtual character puts, i.e., calls to \fBaddch\fR.
+trace virtual character puts, i.e., calls to \fBaddch\fP.
.TP 5
.B TRACE_IEVENT
trace low-level input processing, including timeouts.
@@ -146,48 +199,103 @@
.B TRACE_MAXIMUM
maximum trace level, enables all of the separate trace features.
.PP
-Some tracing features are enabled whenever the \fBtrace\fR parameter
+Some tracing features are enabled whenever the \fBcurses_trace\fP parameter
is nonzero.
Some features overlap.
The specific names are used as a guideline.
+.SS "Command-line Utilities"
+The command-line utilities such as \fBtic\fP(1) provide a verbose option
+which extends the set of messages written using the \fBcurses_trace\fP function.
+Both of these (\fB\-v\fP and \fBcurses_trace\fP)
+use the same variable (\fB_nc_tracing\fP),
+which determines the messages which are written.
.PP
-The other functions either return a pointer to a string-area
-(allocated by the corresponding function),
-or return no value (such as \fB_tracedump\fP, which implements the
-screen dump for \fBTRACE_UPDATE\fP).
-The caller should not free these
-strings, since the allocation is reused on successive calls.
-To work around the problem of a single string-area per function,
-some use a buffer-number parameter, telling the library to allocate
-additional string-areas.
+Because the command-line utilities may call initialization functions
+such as \fBsetupterm\fP, \fBtgetent\fP or \fBuse_extended_names\fP,
+some of their debugging output may be directed to the \fItrace\fP file
+if the \fI\%NCURSES_TRACE\fP environment variable is set:
+.bP
+messages produced in the utility are written to the standard error.
+.bP
+messages produced by the underlying library are written to \fItrace\fP.
.PP
-These functions check the \fBNCURSES_TRACE\fP environment variable,
-to set the tracing feature as if \fBtrace\fP was called:
-.RS
-.PP
-.na
-filter,
-initscr,
-new_prescr,
-newterm,
-nofilter,
-restartterm,
-ripoffline,
-setupterm,
-slk_init,
-tgetent,
-use_env,
-use_extended_names,
-use_tioctl
-.ad
-.RE
+If \fI\%ncurses\fP is built without tracing,
+none of the latter are produced,
+and fewer diagnostics are provided by the command-line utilities.
.SH RETURN VALUE
Routines which return a value are designed to be used as parameters
-to the \fB_tracef\fR routine.
+to the \fB_tracef\fP routine.
+.SH ENVIRONMENT
+.SS NCURSES_TRACE
+A positive integral value stored in this variable causes the following
+functions to enable the tracing feature as if
+.B \%curses_trace
+were called.
+.PP
+.dS
+.RS 4
+\fB\%filter\fP,
+\fB\%initscr\fP,
+\fB\%new_prescr\fP,
+\fB\%newterm\fP,
+\fB\%nofilter\fP,
+\fB\%restartterm\fP,
+\fB\%ripoffline\fP,
+\fB\%setupterm\fP,
+\fB\%slk_init\fP,
+\fB\%tgetent\fP,
+\fB\%use_env\fP,
+\fB\%use_extended_names\fP,
+\fB\%use_tioctl\fP
+.RE
+.dE
.SH PORTABILITY
-These functions are not part of the XSI interface.
+These functions are not part of the X/Open Curses interface.
Some other curses implementations are known to
-have similar, undocumented features,
-but they are not compatible with ncurses.
+have similar features,
+but they are not compatible with \fI\%ncurses\fP:
+.bP
+SVr4 provided \fBtraceon\fP and \fBtraceoff\fP,
+to control whether debugging information was written
+to the \*(``trace\*('' file.
+While the functions were always available,
+this feature was only enabled
+if \fBDEBUG\fP was defined when building the library.
+.IP
+The SVr4 tracing feature is undocumented.
+.bP
+PDCurses provides \fBtraceon\fP and \fBtraceoff\fP,
+which (like SVr4) are always available,
+and enable tracing
+to the \*(``trace\*('' file
+only when a debug-library is built.
+.IP
+PDCurses has a short description of these functions,
+with a note that they are not present in X/Open Curses,
+\fI\%ncurses\fP or NetBSD.
+It does not mention SVr4,
+but the functions' inclusion in a header file section
+labeled \*(``Quasi-standard\*('' hints at the origin.
+.bP
+NetBSD does not provide functions for enabling/disabling traces.
+It uses environment variables
+\fI\%CURSES_TRACE_MASK\fP and
+\fI\%CURSES_TRACE_FILE\fP to determine what is traced,
+and where the results are written.
+This is available only when a debug-library is built.
+.IP
+The NetBSD tracing feature is undocumented.
+.PP
+A few \fI\%ncurses\fP functions are not provided when symbol versioning
+is used:
+.RS 4
+.PP
+_nc_tracebits,
+_tracedump,
+_tracemouse
+.RE
+.PP
+The original \fBtrace\fP routine was deprecated because
+it often conflicted with application names.
.SH SEE ALSO
-\fBcurses\fR(3X).
+\fB\%curses\fP(3X)
diff --git a/man/curs_util.3x b/man/curs_util.3x
index 4d027db..1df0a1d 100644
--- a/man/curs_util.3x
+++ b/man/curs_util.3x
@@ -1,6 +1,7 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2013,2015 Free Software Foundation, Inc. *
+.\" 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 *
.\" copy of this software and associated documentation files (the *
@@ -27,107 +28,133 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_util.3x,v 1.43 2015/06/06 23:36:27 tom Exp $
-.TH curs_util 3X ""
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $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
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.na
-.hy 0
.SH NAME
-\fBdelay_output\fR,
-\fBfilter\fR,
-\fBflushinp\fR,
-\fBgetwin\fR,
-\fBkey_name\fR,
-\fBkeyname\fR,
-\fBnofilter\fR,
-\fBputwin\fR,
-\fBunctrl\fR,
-\fBuse_env\fR,
-\fBuse_tioctl\fR,
-\fBwunctrl\fR \- miscellaneous \fBcurses\fR utility routines
-.ad
-.hy
+\fB\%delay_output\fP,
+\fB\%filter\fP,
+\fB\%flushinp\fP,
+\fB\%getwin\fP,
+\fB\%key_name\fP,
+\fB\%keyname\fP,
+\fB\%nofilter\fP,
+\fB\%putwin\fP,
+\fB\%unctrl\fP,
+\fB\%use_env\fP,
+\fB\%use_tioctl\fP,
+\fB\%wunctrl\fP \-
+miscellaneous \fIcurses\fR utility routines
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBchar *unctrl(chtype c);\fR
-.br
-\fBwchar_t *wunctrl(cchar_t *c);\fR
-.br
-\fBchar *keyname(int c);\fR
-.br
-\fBchar *key_name(wchar_t w);\fR
-.br
-\fBvoid filter(void);\fR
-.br
-\fBvoid nofilter(void);\fR
-.br
-\fBvoid use_env(bool f);\fR
-.br
-\fBvoid use_tioctl(bool f);\fR
-.br
-\fBint putwin(WINDOW *win, FILE *filep);\fR
-.br
-\fBWINDOW *getwin(FILE *filep);\fR
-.br
-\fBint delay_output(int ms);\fR
-.br
-\fBint flushinp(void);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\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 \fIwc\fP);
+.PP
+\fBvoid filter(void);
+.PP
+\fBvoid use_env(bool \fIf\fP);
+.PP
+\fBint putwin(WINDOW *\fIwin\fP, FILE *\fIfilep\fP);
+\fBWINDOW *getwin(FILE *\fIfilep\fP);
+.PP
+\fBint delay_output(int \fIms\fP);
+\fBint flushinp(void);
+.PP
+\fI/* extensions */
+\fBvoid nofilter(void);
+\fBvoid use_tioctl(bool \fIf\fP);
+.fi
.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.
-.SS keyname/key_name
-.PP
-The \fBkeyname\fR routine returns a character string
-corresponding to the key \fIc\fR:
+The \fBunctrl\fP routine returns a character string which is a printable
+representation of the character \fIch\fP:
.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.
+Control characters are displayed in the \fB^\fIX\fR notation.
+.bP
+Printing characters are displayed as is.
.bP
DEL (character 127) is displayed as \fB^?\fP.
.bP
Values above 128 are either meta characters
(if the screen has not been initialized,
-or if \fBmeta\fP has been called with a \fBTRUE\fP parameter),
-shown in the \fBM\-\fR\fIX\fR notation,
+or if \fBmeta\fP(3X) has been called with a \fBTRUE\fP parameter),
+shown in the \fBM\-\fIX\fR notation,
or are displayed as themselves.
In the latter case, the values may not be printable;
this follows the X/Open specification.
-.bP
-Values above 256 may be the names of the names of function keys.
-.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.
-.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.
+The corresponding \fBwunctrl\fP returns a printable representation of
+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"
+The \fBkeyname\fP routine returns a character string
+corresponding to the key \fIc\fP.
+Key codes are different from character codes.
+.bP
+Key codes below 256 are characters.
+They are displayed using \fBunctrl\fP.
+.bP
+Values above 256 may be the codes for function keys.
+The function key name is displayed.
+.bP
+Otherwise (if there is no corresponding name and the key is not a character)
+the function returns null, to denote an error.
+X/Open also lists an \*(``UNKNOWN KEY\*('' return value,
+which some implementations return rather than null.
+.LP
+The corresponding \fBkey_name\fP returns
+a multibyte character string corresponding
+to the wide-character value \fIw\fP.
+The two functions (\fBkeyname\fP and \fBkey_name\fP)
+do not return the same set of strings:
+.bP
+\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"
+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:
+.bP
+\fBLINES\fP is set to 1;
+.bP
+the capabilities
+\fBclear\fP,
+\fBcud1\fP,
+\fBcud\fP,
+\fBcup\fP,
+\fBcuu1\fP,
+\fBcuu\fP,
+\fBvpa\fP
+are disabled;
+.bP
+the capability \fBed\fP is disabled if \fBbce\fP is set;
+.bP
+and the \fBhome\fP string is set to the value of \fBcr\fP.
.PP
The \fBnofilter\fP routine cancels the effect of a preceding \fBfilter\fP
call.
@@ -136,91 +163,93 @@
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,
-should be called before \fBinitscr\fR or
-\fBnewterm\fR are called
+The \fBuse_env\fP routine, if used,
+should be called before \fBinitscr\fP or
+\fBnewterm\fP are called
(because those compute the screen size).
-It modifies the way \fBncurses\fP treats environment variables
+It modifies the way \fI\%ncurses\fP treats environment variables
when determining the screen size.
.bP
-Normally ncurses 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
-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,
it overrides the values from the terminal database.
.bP
Finally (unless \fBuse_env\fP was called with \fBFALSE\fP parameter),
-ncurses examines the \fBLINES\fR or \fBCOLUMNS\fR environment variables,
+\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
-Ncurses also updates the screen size in response to SIGWINCH,
-unless overridden by the \fBLINES\fR or \fBCOLUMNS\fR environment variables,
+\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
-.PP
-The \fBuse_tioctl\fR routine, if used,
-should be called before \fBinitscr\fR or \fBnewterm\fR are called
+The \fBuse_tioctl\fP routine, if used,
+should be called before \fBinitscr\fP or \fBnewterm\fP are called
(because those compute the screen size).
-After \fBuse_tioctl\fR is called with \fBTRUE\fR as an argument,
-ncurses modifies the last step in its computation of screen size as follows:
+After \fBuse_tioctl\fP is called with \fBTRUE\fP as an argument,
+\fI\%ncurses\fP modifies the last step in its computation
+of screen size as follows:
.bP
-checks if the \fBLINES\fR and \fBCOLUMNS\fR environment variables
+checks if the \fILINES\fP and \fI\%COLUMNS\fP environment variables
are set to a number greater than zero.
.bP
-for each, ncurses 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
-ncurses 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 \fBuse_env\fP and \fBuse_tioctl\fP routines combine as
-summarized here:
+The \fB\%use_env\fP and \fB\%use_tioctl\fP routines combine as follows.
+.IP
.TS
-center tab(/);
-l l l
-_ _ _
-lw7 lw7 lw40.
-\fIuse_env\fR/\fIuse_tioctl\fR/\fISummary\fR
-TRUE/FALSE/T{
+lB lB lB
+lB lB lx.
+use_env use_tioctl Summary
+_
+TRUE FALSE T{
This is the default behavior.
-ncurses uses operating system calls
-unless overridden by $LINES or $COLUMNS environment variables.
+\fI\%ncurses\fP uses operating system calls
+unless overridden by \fILINES\fP or \fI\%COLUMNS\fP environment
+variables;
+default.
T}
-TRUE/TRUE/T{
-ncurses updates $LINES and $COLUMNS based on operating system calls.
+TRUE TRUE T{
+\fI\%ncurses\fP updates \fILINES\fP and \fI\%COLUMNS\fP based on
+operating system calls.
T}
-FALSE/TRUE/T{
-ncurses ignores $LINES and $COLUMNS, uses operating system calls to obtain size.
-T}
-FALSE/FALSE/T{
-ncurses relies on the terminal database to determine size.
+FALSE TRUE T{
+\fI\%ncurses\fP ignores \fILINES\fP and \fI\%COLUMNS\fP,
+using operating system calls to obtain 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.
+.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.
This information can be later retrieved
-using the \fBgetwin\fR function.
+using the \fBgetwin\fP function.
.PP
-The \fBgetwin\fR routine reads window related data stored in the file by
-\fBputwin\fR.
+The \fBgetwin\fP routine reads window related data stored in the file by
+\fBputwin\fP.
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,
+the data written is a copy of the \fI\%WINDOW\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 (\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),
@@ -232,32 +261,38 @@
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
+The \fBdelay_output\fP routine inserts an \fIms\fP millisecond pause
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.
-.SS flushinp
+Employ this function judiciously when terminal output uses padding,
+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:
+.bP
+the terminal description has \fBnpc\fP (\fBno_pad_char\fP) capability, or
+.bP
+the environment variable \fB\%NCURSES_NO_PADDING\fP is set.
.PP
-The \fBflushinp\fR routine throws away any typeahead that has been typed by the
+If padding is not in use,
+\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.
+.SS flushinp
+The \fBflushinp\fP routine throws away any typeahead that has been typed by the
user and has not yet been read by the program.
.SH RETURN VALUE
-Except for \fBflushinp\fR, routines that return an integer return \fBERR\fR
-upon failure and \fBOK\fR (SVr4 specifies only "an integer value other than
-\fBERR\fR") upon successful completion.
+Except for \fBflushinp\fP, routines that return an integer return \fBERR\fP
+upon failure and \fBOK\fP (SVr4 specifies only "an integer value other than
+\fBERR\fP") upon successful completion.
.PP
-Routines that return pointers return \fBNULL\fR on error.
+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
-\fBflushinp\fR
-returns an error if the terminal was not initialized.
-.TP 5
-\fBmeta\fR
+\fBflushinp\fP
returns an error if the terminal was not initialized.
.TP 5
\fBputwin\fP
@@ -265,31 +300,39 @@
.RE
.SH PORTABILITY
.SS filter
-.PP
-The SVr4 documentation describes the action of \fBfilter\fR only in the vaguest
+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
-erroneously fails to describe the disabling of \fBcuu\fR).
-.SS keyname
+The description here is adapted from X/Open Curses (which
+erroneously fails to describe the disabling of \fBcuu\fP).
+.SS "delay_output padding"
+The limitation to 30 seconds
+and the use of \fBnapms\fP
+differ from other implementations.
+.bP
+SVr4 curses does not delay if no padding character is available.
+.bP
+NetBSD curses uses \fBnapms\fP when no padding character is available,
+but does not take timing into account when using the padding character.
.PP
+Neither limits the delay.
+.SS keyname
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".
+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
+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 ncurses.
+.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 ncurses extensions
-be conditioned using NCURSES_VERSION.
-.SS putwin/getwin
-.PP
+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
portability:
.bP
@@ -304,9 +347,12 @@
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 ncurses versions.
-This implementation (as well as the X/Open variant of Solaris curses, dated 1995)
+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
+(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
@@ -317,10 +363,9 @@
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
+.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:
.bP
@@ -328,7 +373,7 @@
This is the case that X/Open Curses documented.
.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.,
@@ -342,34 +387,49 @@
parameter values outside the 0 to 255 range.
\fBunctrl\fP returns a null pointer.
.PP
-The strings returned by \fBunctrl\fR in this implementation are determined
+The strings returned by \fBunctrl\fP 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
+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
+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
(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 \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 \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)).
+This feature of \fBuse_env\fP
+is not provided by other implementations of curses.
.SH SEE ALSO
-\fBlegacy_coding\fR(3X),
-\fBcurses\fR(3X),
-\fBcurs_initscr\fR(3X),
-\fBcurs_kernel\fR(3X),
-\fBcurs_scr_dump\fR(3X),
-\fBcurs_variables\fR(3X),
-\fBlegacy_coding\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_initscr\fP(3X),
+\fB\%curs_inopts\fP(3X),
+\fB\%curs_kernel\fP(3X),
+\fB\%curs_scr_dump\fP(3X),
+\fB\%curs_sp_funcs\fP(3X),
+\fB\%curs_variables\fP(3X),
+\fB\%legacy_coding\fP(3X)
diff --git a/man/curs_variables.3x b/man/curs_variables.3x
index efbe192..467b694 100644
--- a/man/curs_variables.3x
+++ b/man/curs_variables.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2010,2013 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 2010-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 *
@@ -26,111 +27,303 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_variables.3x,v 1.6 2013/12/21 18:41:32 tom Exp $
-.TH curs_variables 3X ""
+.\" $Id: curs_variables.3x,v 1.47 2024/04/13 22:37:35 tom Exp $
+.TH curs_variables 3X 2024-04-13 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.ie \n(.g .ds : \:
+.el .ds : \" empty
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.ds n 5
-.na
-.hy 0
+.
.SH NAME
-\fBCOLORS\fR,
-\fBCOLOR_PAIRS\fR,
-\fBCOLS\fR,
-\fBESCDELAY\fR,
-\fBLINES\fR,
-\fBTABSIZE\fR,
-\fBcurscr\fR,
-\fBnewscr\fR,
-\fBstdscr\fR
-\- \fBcurses\fR global variables
-.ad
-.hy
+\fI\%bool\fP,
+\fI\%chtype\fP,
+\fI\%cchar_t\fP,
+\fI\%attr_t\fP,
+\fI\%SCREEN\fP,
+\fI\%WINDOW\fP,
+\fB\%TRUE\fP,
+\fB\%FALSE\fP,
+\fB\%ERR\fP,
+\fB\%OK\fP,
+\fB\%curscr\fP,
+\fB\%newscr\fP,
+\fB\%stdscr\fP,
+\fB\%COLORS\fP,
+\fB\%COLOR_PAIRS\fP,
+\fB\%COLS\fP,
+\fB\%LINES\fP,
+\fB\%ESCDELAY\fP,
+\fB\%TABSIZE\fP \-
+\fIcurses\fR data types, constants, and global variables
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fR
+\fB#include <curses.h>
.PP
-\fBint COLOR_PAIRS;\fR
-.br
-\fBint COLORS;\fR
-.br
-\fBint COLS;\fR
-.br
-\fBint ESCDELAY;\fR
-.br
-\fBint LINES;\fR
-.br
-\fBint TABSIZE;\fR
-.br
-\fBWINDOW * curscr;\fR
-.br
-\fBWINDOW * newscr;\fR
-.br
-\fBWINDOW * stdscr;\fR
+\fI/* data types */
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP bool;
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP chtype;
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP cchar_t;
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP attr_t;
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP SCREEN;
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP WINDOW;
+.PP
+\fI/* constants */
+\fBconst bool TRUE;
+\fBconst bool FALSE;
+.PP
+\fBconst \fI/*\fP .\|.\|. \fI*/\fP ERR;
+\fBconst \fI/*\fP .\|.\|. \fI*/\fP OK;
+.PP
+\fI/* variables */
+\fBint COLORS;
+\fBint COLOR_PAIRS;
+\fBint COLS;
+\fBint LINES;
+\fBWINDOW * curscr;
+\fBWINDOW * stdscr;
+.PP
+\fI/* extensions */
+\fBint ESCDELAY;
+\fBint TABSIZE;
+\fBWINDOW * newscr;
.fi
.SH DESCRIPTION
-This page summarizes variables provided by the \fBcurses\fP library.
-A more complete description is given in the \fBcurses\fP(3X) manual page.
+This page summarizes data types,
+constants,
+and variables provided by the \fIcurses\fP library.
+Locate further discussion in \fB\%curses\fP(3X).
.PP
-Depending on the configuration, these may be actual variables,
-or macros (see \fBcurs_threads\fR(3X) and \fBcurs_opaque\fR(3X))
-which provide read-only access to \fIcurses\fP's state.
-In either case, applications should treat them as read-only to avoid
+Depending on \fI\%ncurses\fP's build-time configuration,
+the variables may instead be
+macros (see \fB\%curs_threads\fP(3X) and \fB\%curs_opaque\fP(3X))
+that provide read-only access to the library's state.
+In either case,
+applications should treat them as read-only to avoid
confusing the library.
-.SS COLOR_PAIRS
-After initializing curses, this variable contains the number of color pairs
-which the terminal can support.
-Usually the number of color pairs will be the product \fBCOLORS\fP*\fBCOLORS\fP,
-however this is not always true:
-.bP
-a few terminals use HLS colors, which do not follow this rule
-.bP
-terminals supporting a large number of colors are limited by the number
-of color pairs that can be represented in a \fIsigned short\fP value.
-.SS COLORS
-After initializing curses, this variable contains the number of colors
-which the terminal can support.
-.SS COLS
-After initializing curses, this variable contains the width of the screen,
-i.e., the number of columns.
-.SS ESCDELAY
-This variable holds the number of milliseconds to wait after reading an
-escape character,
-to distinguish between an individual escape character entered on the
-keyboard from escape sequences sent by cursor- and function-keys
-(see curses(3X).
-.SS LINES
-After initializing curses, this variable contains the height of the screen,
-i.e., the number of lines.
-.SS TABSIZE
-This variable holds the number of columns used by the \fIcurses\fP library
-when converting a tab character to spaces as it adds the tab to a window
-(see curs_addch(3X).
-.SS The Current Screen
-This implementation of curses uses a special window \fBcurscr\fP to
-record its updates to the terminal screen.
-.SS The New Screen
-This implementation of curses uses a special window \fBnewscr\fP to
-hold updates to the terminal screen before applying them to \fBcurscr\fP.
-.SS The Standard Screen
-Upon initializing curses,
-a default window called \fBstdscr\fP,
-which is the size of the terminal screen, is created.
-Many curses functions use this window.
-.SH NOTES
-The curses library is initialized using either \fBinitscr\fR(3X),
-or \fBnewterm\fR(3X).
+.SH "CONSTANTS"
+.SS "TRUE, FALSE"
+The \fIcurses\fP library defines \fBTRUE\fP and \fBFALSE\fP
+to represent the values of the Boolean data type.
+.SS "ERR, OK"
+\fIcurses\fP and \fIterminfo\fP routines frequently return these
+constant integral values indicating failure and success,
+respectively.
+.SH "PREDEFINED TYPES"
+.SS "\fIbool\fP"
+X/Open Issue 4 \fIcurses\fP (1996) preceded the ISO C99 and ISO C++98
+standards,
+each of which also defined a Boolean data type.
+The \fIcurses\fP library requires an integral type \fIbool\fP.
.PP
-If \fBcurses\fP is configured to use separate curses/terminfo libraries,
-most of these variables reside in the curses library.
+\fB\%ncurses\fP' configure script attempts to discover the
+data type used by the system's C and C++ compilers,
+to reuse for the \fIcurses\fP \fIbool\fP.
+.SS "\fIchtype\fP"
+The \fI\%chtype\fP integral type combines a
+(\*(``narrow\*('',
+8-bit)
+character with attributes encoding the character's \fIrendition\fP,
+such as the styling of its typeface and/or foreground and background
+colors.
+See,
+for example,
+\fB\%addch\fP(3X),
+\fB\%attron\fP(3X),
+and
+\fB\%inch\fP(3X).
+.SS "\fIcchar_t\fP, \fIattr_t\fP"
+\fI\%chtype\fP is too small for the standard C library's wide-character
+type,
+\fIwchar_t\fP.
+\fI\%cchar_t\fP is a type that can accommodate an \fI\%attr_t\fP and
+enough wide characters to store what Unicode terms a \fIgrapheme cluster\fP
+(a \*(``user-perceived character\*('' [UAX #29],
+which may nevertheless require several character encoding units to
+represent).
+\fI\%attr_t\fP is an integral type storing \*(``wide\*('' attributes that
+apply to \fI\%cchar_t\fPs.
+See,
+for example,
+\fB\%add_wch\fP(3X),
+\fB\%attr_on\fP(3X),
+and
+\fB\%in_wch\fP(3X).
+.SS "\fISCREEN\fP"
+.I curses
+manages a terminal device with this structure type;
+see \fB\%initscr\fP(3X).
+.SS "\fIWINDOW\fP"
+.I curses
+represents rectangular portions of the terminal screen with the
+.I \%WINDOW
+structure type;
+see subsection \*(``Overview\*('' of \fB\%ncurses\fP(3X).
+.SH "VARIABLES"
+.SS "curscr, stdscr, newscr"
+The library records updates to the terminal screen in a window named
+\fB\%curscr\fP.
+This object is referred to as the \*(``physical screen\*('' in
+\fB\%curs_refresh\fP(3X) and
+\fB\%curs_outopts\fP(3X).
+.PP
+\fI\%ncurses\fP collects pending updates to the terminal screen in a
+window named \fB\%newscr\fP.
+This object is referred to as the \*(``virtual screen\*('' in the
+\fB\%curs_kernel\fP(3X),
+\fB\%curs_refresh\fP(3X),
+and
+\fB\%curs_outopts\fP(3X).
+When the screen is refreshed,
+\fIcurses\fP determines a minimal set of updates using the terminal's
+capabilities to make \fB\%curscr\fP look like \fB\%newscr\fP.
+.PP
+Once \fIcurses\fP is initialized,
+it creates a window named \fB\%stdscr\fP.
+It is the same size as the terminal screen and is the default window
+used by routines that do not take a parameter identifying one.
+Many \fIcurses\fP functions use this window.
+.SS COLORS
+Once \fIcurses\fP is initialized,
+\fB\%COLORS\fP
+contains the number of colors supported by the terminal;
+see \fB\%curs_color\fP(3X).
+.SS COLOR_PAIRS
+Once \fIcurses\fP is initialized,
+\fB\%COLOR_PAIRS\fP
+contains the number of color pairs supported by the terminal;
+see \fB\%curs_color\fP(3X).
+.SS "COLS, LINES"
+Once \fIcurses\fP is initialized,
+.B \%COLS
+and
+.B LINES
+contain the screen's width and height in character cells,
+respectively;
+that is,
+the number of columns and lines.
+.SS ESCDELAY
+For
+.I curses
+to distinguish the ESC character resulting from a user's press of the
+\*(``Escape\*('' key on the input device from one beginning an
+.I "escape sequence"
+(as commonly produced by function keys),
+it waits after the escape character to see if further characters are
+available on the input stream within a short interval.
+.B \%ESCDELAY
+stores this interval in milliseconds.
+.PP
+If \fB\%keypad\fP(3X) is disabled for the
+.I curses
+window receiving input,
+a program must disambiguate escape sequences itself.
+.SS TABSIZE
+The \fIcurses\fP library converts a tab character to this number of
+spaces as it adds a tab to a window;
+see \fB\%curs_addch\fP(3X).
+.SH NOTES
+Either \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X) initializes
+\fIcurses\fP.
+.PP
+If
+.I \%ncurses
+is configured to provide separate
+.I curses
+and
+.I \%tinfo
+libraries,
+most of these variables reside in the former.
.SH PORTABILITY
-ESCDELAY and TABSIZE are extensions,
-not provided in most other implementations of curses.
+The X/Open Curses standard documents all of the foregoing types and
+symbols except for \fB\%newscr\fP,
+\fB\%TABSIZE\fP,
+and \fB\%ESCDELAY\fP.
+.PP
+X/Open Curses describes \fB\%curscr\fP only as \*(``an internal data
+structure\*('';
+SVr4 gave more details,
+noting its use \*(``for certain low-level operations like clearing and
+redrawing a screen containing garbage\*(''.
+.\" SVID 4, Volume 3, p. 408
+Neither specified its interaction with the rest of the interface beyond
+use as an argument to \fB\%clearok\fP(3X) and \fB\%wrefresh\fP(3X).
+.PP
+\fB\%newscr\fP is a feature of SVr4 \fIcurses\fP.
+When refreshing the screen,
+it is used as a working area for combining the standard window
+\fB\%stdscr\fP with any others the application may have created with
+\fB\%newwin\fP(3X).
+When the update of \fB\%newscr\fP is complete,
+\fIcurses\fP modifies \fB\%curscr\fP to match \fB\%newscr\fP.
+.PP
+\fB\%TABSIZE\fP is a feature of SVr4 \fIcurses\fP.
+.bP
+SVr4 initially sets \fB\%TABSIZE\fP from the terminal description's
+\fB\%init_tabs\fP capability.
+After that,
+it can be altered by applications using SVr4 \fIcurses\fP.
+.bP
+SVr4 \fIcurses\fP uses the value of \fB\%TABSIZE\fP to compute the
+position of tab stops when updating both
+the virtual screen with \fB\%addch\fP(3X) and
+the physical screen with \fB\%mvcur\fP(3X).
+.bP
+\fI\%ncurses\fP uses the value of \fB\%TABSIZE\fP only to update the
+virtual screen.
+It uses the terminal description's \*(``\fBit\fP\*(''
+(\fB\%init_tabs\fP) capability for computing hardware tabs
+(that is,
+tab stops on the physical screen).
+.bP
+Other implementations differ.
+For instance,
+NetBSD \fIcurses\fP allows \fB\%TABSIZE\fP to be set through an
+environment variable.
+\fI\%ncurses\fP does not.
+.IP
+NetBSD \fIcurses\fP does not support hardware tabs;
+it uses the \fB\%init_tabs\fP capability and the \fB\%TABSIZE\fP
+variable only for updating the virtual screen.
+.PP
+\fB\%ESCDELAY\fP is a feature of AIX \fIcurses\fP.
+.bP
+In AIX,
+the units for \fB\%ESCDELAY\fP are \fIfifths\fP of milliseconds.
+.bP
+The default value for AIX's \fB\%ESCDELAY\fP equals 0.1 seconds.
+.bP
+AIX also enforces a limit of 10,000 seconds for \fB\%ESCDELAY\fP;
+\fI\%ncurses\fP does not enforce any upper limit.
+.PP
+\fI\%ncurses\fP has long used \fB\%ESCDELAY\fP with units of
+milliseconds,
+making it impossible to be completely compatible with AIX.
+Consequently,
+most users have decided either to override the value,
+or to rely upon its default.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_opaque\fR(3X),
-\fBcurs_terminfo\fR(3X),
-\fBcurs_threads\fR(3X),
-\fBterm_variables\fR(3X),
-\fBterminfo\fR(\*n).
+\fB\%curses\fP(3X),
+\fB\%curs_color\fP(3X),
+\fB\%curs_opaque\fP(3X),
+\fB\%curs_terminfo\fP(3X),
+\fB\%curs_threads\fP(3X),
+\fB\%term_variables\fP(3X),
+\fB\%terminfo\fP(5)
+.PP
+[UAX #29] \*(``Unicode Standard Annex #29: Unicode Text
+Segmentation\*('';
+\%<https://\*:unicode\*:.org/\*:reports/\*:tr29/>
diff --git a/man/curs_window.3x b/man/curs_window.3x
index ba9d293..d3d55c7 100644
--- a/man/curs_window.3x
+++ b/man/curs_window.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2014,2015 Free Software Foundation, Inc. *
+.\" Copyright 2020-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2015,2016 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 *
@@ -26,146 +27,152 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_window.3x,v 1.19 2015/07/21 08:25:23 tom Exp $
-.TH curs_window 3X ""
-.na
-.hy 0
+.\" $Id: curs_window.3x,v 1.48 2024/04/20 21:20:07 tom Exp $
+.TH curs_window 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBnewwin\fR,
-\fBdelwin\fR,
-\fBmvwin\fR,
-\fBsubwin\fR,
-\fBderwin\fR,
-\fBmvderwin\fR,
-\fBdupwin\fR,
-\fBwsyncup\fR,
-\fBsyncok\fR,
-\fBwcursyncup\fR,
-\fBwsyncdown\fR \- create \fBcurses\fR windows
-.ad
-.hy
+\fB\%newwin\fP,
+\fB\%delwin\fP,
+\fB\%mvwin\fP,
+\fB\%subwin\fP,
+\fB\%derwin\fP,
+\fB\%mvderwin\fP,
+\fB\%dupwin\fP,
+\fB\%wsyncup\fP,
+\fB\%syncok\fP,
+\fB\%wcursyncup\fP,
+\fB\%wsyncdown\fP \-
+create and manipulate \fIcurses\fR windows
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBWINDOW *newwin(\fR
- \fBint \fP\fInlines\fP\fB, int \fP\fIncols\fP\fB,\fR
- \fBint \fP\fIbegin_y\fP\fB, int \fP\fIbegin_x\fP\fB);\fR
-.br
-\fBint delwin(WINDOW *\fP\fIwin\fP\fB);\fR
-.br
-\fBint mvwin(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR
-.br
-\fBWINDOW *subwin(WINDOW *\fP\fIorig\fP\fB,\fR
- \fBint \fP\fInlines\fP\fB, int \fP\fIncols\fP\fB,\fR
- \fBint \fP\fIbegin_y\fP\fB, int \fP\fIbegin_x\fP\fB);\fR
-.br
-\fBWINDOW *derwin(WINDOW *\fP\fIorig\fP\fB,\fR
- \fBint \fP\fInlines\fP\fB, int \fP\fIncols\fP\fB,\fR
- \fBint \fP\fIbegin_y\fP\fB, int \fP\fIbegin_x\fP\fB);\fR
-.br
-\fBint mvderwin(WINDOW *\fP\fIwin\fP\fB, int \fP\fIpar_y\fP\fB, int \fP\fIpar_x\fP\fB);\fR
-.br
-\fBWINDOW *dupwin(WINDOW *\fP\fIwin\fP\fB);\fR
-.br
-\fBvoid wsyncup(WINDOW *\fP\fIwin\fP\fB);\fR
-.br
-\fBint syncok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
-.br
-\fBvoid wcursyncup(WINDOW *\fP\fIwin\fP\fB);\fR
-.br
-\fBvoid wsyncdown(WINDOW *\fP\fIwin\fP\fB);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBWINDOW *newwin(
+ \fBint \fInlines\fB, int \fIncols\fB,\fR
+ \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR
+\fBint delwin(WINDOW *\fIwin\fB);\fR
+\fBint mvwin(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);\fR
+\fBWINDOW *subwin(WINDOW *\fIorig\fB,\fR
+ \fBint \fInlines\fB, int \fIncols\fB,\fR
+ \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR
+\fBWINDOW *derwin(WINDOW *\fIorig\fB,\fR
+ \fBint \fInlines\fB, int \fIncols\fB,\fR
+ \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR
+\fBint mvderwin(WINDOW *\fIwin\fB, int \fIpar_y\fB, int \fIpar_x\fB);\fR
+\fBWINDOW *dupwin(WINDOW *\fIwin\fB);\fR
+\fBvoid wsyncup(WINDOW *\fIwin\fB);\fR
+\fBint syncok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR
+\fBvoid wcursyncup(WINDOW *\fIwin\fB);\fR
+\fBvoid wsyncdown(WINDOW *\fIwin\fB);\fR
+.fi
.SH DESCRIPTION
.SS newwin
-Calling \fBnewwin\fR creates and returns a pointer to a new window with the
+Calling \fBnewwin\fP creates and returns a pointer to a new window with the
given number of lines and columns.
The upper left-hand corner of the window is
at
.RS
-line \fIbegin\fR_\fIy\fR,
+line \fIbegin\fR_\fIy\fP,
.br
-column \fIbegin\fR_\fIx\fR
+column \fIbegin\fR_\fIx\fP
.RE
.PP
If either
-\fInlines\fR or \fIncols\fR is zero, they default to
+\fInlines\fP or \fIncols\fP is zero, they default to
.RS
-\fBLINES \-\fR \fIbegin\fR_\fIy\fR and
+\fBLINES \-\fP \fIbegin\fR_\fIy\fP and
.br
-\fBCOLS \-\fR \fIbegin\fR_\fIx\fR.
+\fBCOLS \-\fP \fIbegin\fR_\fIx\fP.
.RE
.PP
-A new full-screen window is created by calling \fBnewwin(0,0,0,0)\fR.
-.SS delwin
+A new full-screen window is created by calling \fBnewwin(0,0,0,0)\fP.
.PP
-Calling \fBdelwin\fR deletes the named window, freeing all memory
+Regardless of the function used for creating a new window
+(e.g., \fBnewwin\fP, \fBsubwin\fP, \fBderwin\fP, \fBnewpad\fP),
+rather than a duplicate (with \fBdupwin\fP),
+all of the window modes are initialized to the default values.
+These functions set window modes after a window is created:
+.RS
+.PP
+\fB\%idcok\fP
+\fB\%idlok\fP
+\fB\%immedok\fP
+\fB\%keypad\fP
+\fB\%leaveok\fP
+\fB\%nodelay\fP
+\fB\%scrollok\fP
+\fB\%setscrreg\fP
+\fB\%syncok\fP
+\fB\%wbkgdset\fP
+\fB\%wbkgrndset\fP and
+\fB\%wtimeout\fP.
+.RE
+.SS delwin
+Calling \fBdelwin\fP deletes the named window, freeing all memory
associated with it (it does not actually erase the window's screen
image).
Subwindows must be deleted before the main window can be deleted.
.SS mvwin
-.PP
-Calling \fBmvwin\fR moves the window so that the upper left-hand
-corner is at position (\fIx\fR, \fIy\fR).
+Calling \fBmvwin\fP moves the window so that the upper left-hand
+corner is at position (\fIx\fP, \fIy\fP).
If the move would cause the window to be off the screen,
it is an error and the window is not moved.
Moving subwindows is allowed, but should be avoided.
.SS subwin
-.PP
-Calling \fBsubwin\fR creates and returns a pointer to a new window
-with the given number of lines, \fInlines\fR, and columns, \fIncols\fR.
-The window is at position (\fIbegin\fR_\fIy\fR,
-\fIbegin\fR_\fIx\fR) on the screen.
-The subwindow shares memory with the window \fIorig\fR,
+Calling \fBsubwin\fP creates and returns a pointer to a new window
+with the given number of lines, \fInlines\fP, and columns, \fIncols\fP.
+The window is at position (\fIbegin\fR_\fIy\fP,
+\fIbegin\fR_\fIx\fP) on the screen.
+The subwindow shares memory with the window \fIorig\fP,
+its \fIancestor\fP,
so that changes made to one window
will affect both windows.
When using this routine, it is necessary to call
-\fBtouchwin\fR or \fBtouchline\fR on \fIorig\fR before calling
-\fBwrefresh\fR on the subwindow.
+\fBtouchwin\fP or \fBtouchline\fP on \fIorig\fP before calling
+\fBwrefresh\fP on the subwindow.
.SS derwin
-.PP
-Calling \fBderwin\fR is the same as calling \fBsubwin,\fR except that
-\fIbegin\fR_\fIy\fR and \fIbegin\fR_\fIx\fR are relative to the origin
-of the window \fIorig\fR rather than the screen.
+Calling \fBderwin\fP is the same as calling \fBsubwin,\fP except that
+\fIbegin\fR_\fIy\fP and \fIbegin\fR_\fIx\fP are relative to the origin
+of the window \fIorig\fP rather than the screen.
There is no difference between the subwindows and the derived windows.
-.PP
-Calling \fBmvderwin\fR moves a derived window (or subwindow)
+.SS mvderwin
+Calling \fBmvderwin\fP moves a derived window (or subwindow)
inside its parent window.
The screen-relative parameters of the window are not changed.
This routine is used to display different
parts of the parent window at the same physical position on the
screen.
.SS dupwin
-.PP
-Calling \fBdupwin\fR creates an exact duplicate of the window \fIwin\fR.
+Calling \fBdupwin\fP creates an exact duplicate of the window \fIwin\fP.
.SS wsyncup
-.PP
-Calling \fBwsyncup\fR touches all locations in ancestors of \fIwin\fR that are
-changed in \fIwin\fR.
-If \fBsyncok\fR is called with second argument
-\fBTRUE\fR then \fBwsyncup\fR is called automatically whenever there is a
+Calling \fBwsyncup\fP touches all locations in ancestors of \fIwin\fP that are
+changed in \fIwin\fP.
+If \fBsyncok\fP is called with second argument
+\fBTRUE\fP then \fBwsyncup\fP is called automatically whenever there is a
change in the window.
.SS wsyncdown
-.PP
-The \fBwsyncdown\fR routine touches each location in \fIwin\fR that has been
+The \fBwsyncdown\fP routine touches each location in \fIwin\fP that has been
touched in any of its ancestor windows.
This routine is called by
-\fBwrefresh\fR, so it should almost never be necessary to call it manually.
+\fBwrefresh\fP, so it should almost never be necessary to call it manually.
.SS wcursyncup
-.PP
-The routine \fBwcursyncup\fR updates the current cursor position of all the
+The routine \fBwcursyncup\fP updates the current cursor position of all the
ancestors of the window to reflect the current cursor position of the
window.
.SH RETURN VALUE
-Routines that return an integer return the integer \fBERR\fR upon failure and
-\fBOK\fR (SVr4 only specifies "an integer value other than \fBERR\fR") upon
+Routines that return an integer return the integer \fBERR\fP upon failure and
+\fBOK\fP (SVr4 only specifies "an integer value other than \fBERR\fP") upon
successful completion.
.PP
-Routines that return pointers return \fBNULL\fR on error.
+Routines that return pointers return \fBNULL\fP on error.
.PP
X/Open defines no error conditions.
In this implementation
.TP 5
-\fBdelwin\fR
+\fBdelwin\fP
returns an error if the window pointer is null, or
if the window is the parent of another window.
.TP 5
@@ -210,26 +217,56 @@
Any of these functions will fail if the screen has not been initialized,
i.e., with \fBinitscr\fP or \fBnewterm\fP.
.SH NOTES
-If many small changes are made to the window, the \fBwsyncup\fR option could
+If many small changes are made to the window, the \fBwsyncup\fP option could
degrade performance.
.PP
-Note that \fBsyncok\fR may be a macro.
-.SH BUGS
-The subwindow functions (\fIsubwin\fR, \fIderwin\fR, \fImvderwin\fR,
-\fBwsyncup\fR, \fBwsyncdown\fR, \fBwcursyncup\fR, \fBsyncok\fR) are flaky,
-incompletely implemented, and not well tested.
-.PP
-The System V curses documentation is very unclear about what \fBwsyncup\fR
-and \fBwsyncdown\fR actually do.
-It seems to imply that they are only
-supposed to touch exactly those lines that are affected by ancestor changes.
-The language here, and the behavior of the \fBcurses\fR implementation,
-is patterned on the XPG4 curses standard.
-The weaker XPG4 spec may result in slower updates.
+Note that \fBsyncok\fP may be a macro.
.SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions.
+X/Open Curses, Issue 4 describes these functions.
+.PP
+X/Open Curses states regarding \fBdelwin\fP:
+.bP
+It must delete subwindows before deleting their parent.
+.bP
+If \fBdelwin\fP is asked to delete a parent window,
+it can only succeed if the curses library keeps a list of the subwindows.
+SVr4 curses kept a count of the number of subwindows rather than a list.
+It simply returned \fBERR\fP when asked to delete a subwindow.
+Solaris X/Open curses does not even make that check,
+and will delete a parent window which still has subwindows.
+.bP
+Since release 4.0 (1996),
+\fI\%ncurses\fP maintains a list of windows for each screen,
+to ensure that a window has no subwindows before allowing deletion.
+.bP
+NetBSD copied this feature of \fI\%ncurses\fP in 2003.
+.br
+PDCurses follows the scheme used in Solaris X/Open curses.
+.SH BUGS
+The subwindow functions
+\fB\%subwin\fP,
+\fB\%derwin\fP,
+\fB\%mvderwin\fP,
+\fB\%wsyncup\fP,
+\fB\%wsyncdown\fP,
+\fB\%wcursyncup\fP,
+and
+\fB\%syncok\fP
+are flaky,
+incompletely implemented,
+and not well tested.
+.PP
+System\ V's \fIcurses\fP documentation is unclear about what
+\fB\%wsyncup\fP and \fB\%wsyncdown\fP actually do.
+It seems to imply that they are supposed to touch only those lines that
+are affected by changes to a window's ancestors.
+The language here,
+and behavior of \fI\%ncurses\fP,
+is patterned on the X/Open Curses standard;
+this approach may result in slower updates.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_refresh\fR(3X),
-\fBcurs_touch\fR(3X),
-\fBcurs_variables\fR(3X)
+\fB\%curses\fP(3X),
+\fB\%curs_initscr\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_touch\fP(3X),
+\fB\%curs_variables\fP(3X)
diff --git a/man/default_colors.3x b/man/default_colors.3x
index 0b85598..9612414 100644
--- a/man/default_colors.3x
+++ b/man/default_colors.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2011 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 2000-2011,2016 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 *
@@ -28,22 +29,31 @@
.\"
.\" Author: Thomas E. Dickey 1997,1999,2000,2005
.\"
-.\" $Id: default_colors.3x,v 1.23 2011/01/03 21:52:27 Tim.van.der.Molen Exp $
-.TH default_colors 3X ""
+.\" $Id: default_colors.3x,v 1.52 2024/04/13 22:17:22 tom Exp $
+.TH default_colors 3X 2024-04-13 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-\fBuse_default_colors\fR,
-\fBassume_default_colors\fR \- use terminal's default colors
+\fB\%use_default_colors\fP,
+\fB\%assume_default_colors\fP \-
+use terminal's default colors in \fIcurses\fP
.SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-\fBint use_default_colors(void);\fP
-.br
-\fBint assume_default_colors(int fg, int bg);\fP
+.nf
+\fB#include <curses.h>
+.PP
+\fBint use_default_colors(void);
+\fBint assume_default_colors(int \fIfg\fP, int \fIbg\fP);
+.fi
.SH DESCRIPTION
-The
-.I use_default_colors()
-and
-.I assume_default_colors()
+The \fBuse_default_colors\fP and \fBassume_default_colors\fP
functions are extensions to the curses library.
They are used with terminals that support ISO 6429 color, or equivalent.
These terminals allow the application to reset color to an unspecified
@@ -55,21 +65,22 @@
using colors only for text.
For example, there are several implementations of the \fBls\fP program
which use colors to denote different file types or permissions.
-These "color ls" programs do not necessarily modify the background color,
-typically using only the \fIsetaf\fP terminfo capability to set the
+These \*(``color ls\*('' programs do not necessarily
+modify the background color,
+typically using only the \fBsetaf\fP terminfo capability to set the
foreground color.
Full-screen applications that use default colors can achieve similar
visual effects.
.PP
-The first function,
-.I use_default_colors()
+The first function, \fBuse_default_colors\fP
tells the curses library to assign terminal default
-foreground/background colors to color number \-1. So init_pair(x,COLOR_RED,\-1)
-will initialize pair x as red on default background and init_pair(x,\-1,COLOR_BLUE) will
+foreground/background colors to color number \-1.
+So init_pair(x,COLOR_RED,\-1)
+will initialize pair x as red on default background
+and init_pair(x,\-1,COLOR_BLUE) will
initialize pair x as default foreground on blue.
.PP
-The other,
-.I assume_default_colors()
+The other, \fBassume_default_colors\fP
is a refinement which tells which colors to paint for color pair 0.
This function recognizes a special color number \-1,
which denotes the default terminal color.
@@ -82,37 +93,39 @@
.I assume_default_colors(\-1,\-1);
.RE
.PP
-These are ncurses extensions.
+These are \fI\%ncurses\fP extensions.
For other curses implementations, color
-number \-1 does not mean anything, just as for ncurses before a
-successful call of \fIuse_default_colors()\fP or \fIassume_default_colors()\fP.
+number \-1 does not mean anything, just as for \fI\%ncurses\fP before a
+successful call of \fBuse_default_colors\fP or \fBassume_default_colors\fP.
.PP
Other curses implementations do not allow an application to modify color pair 0.
They assume that the background is COLOR_BLACK,
but do not ensure that the color pair 0 is painted to match the
assumption.
If your application does not use either
-.I use_default_colors()
+.B use_default_colors
or
-.I assume_default_colors()
-ncurses will paint a white foreground (text) with black background
+.B assume_default_colors
+\fI\%ncurses\fP will paint a white foreground (text) with black background
for color pair 0.
.SH RETURN VALUE
-These functions return the integer \fBERR\fP upon failure and \fBOK\fP on success.
+These functions return the integer \fBERR\fP upon failure
+and \fBOK\fP on success.
They will fail if either the terminal does not support
-the \fIorig_pair\fP or \fIorig_colors\fP capability.
-If the \fIinitialize_pair\fP capability is not found, this causes an
+the \fBorig_pair\fP or \fBorig_colors\fP capability.
+If the \fBinitialize_pair\fP capability is not found, this causes an
error as well.
.SH NOTES
-Associated with this extension, the \fBinit_pair\fR function accepts
+Associated with this extension, the \fBinit_pair\fP function accepts
negative arguments to specify default foreground or background colors.
.PP
-The \fIuse_default_colors()\fP function was added to support \fIded\fP.
+The \fBuse_default_colors\fP function was added to support \fBded\fP.
This is a full-screen application which uses curses to manage only part
-of the screen. The bottom portion of the screen, which is of adjustable
+of the screen.
+The bottom portion of the screen, which is of adjustable
size, is left uncolored to display the results from shell commands.
The top portion of the screen colors filenames using a scheme like the
-"color ls" programs.
+\*(``color ls\*('' programs.
Attempting to manage the background color of the screen for this application
would give unsatisfactory results for a variety of reasons.
This extension was devised after
@@ -120,19 +133,21 @@
which does not necessarily correspond to any of the ANSI colors.
While a special terminfo entry could be constructed using nine colors,
there was no mechanism provided within curses to account for the related
-\fIorig_pair\fP and \fIback_color_erase\fP capabilities.
+\fBorig_pair\fP and \fBback_color_erase\fP capabilities.
.PP
-The \fIassume_default_colors()\fP function was added to solve
+The \fBassume_default_colors\fP function was added to solve
a different problem: support for applications which would use
environment variables and other configuration to bypass curses'
notion of the terminal's default colors, setting specific values.
.SH PORTABILITY
-These routines are specific to ncurses. They were not supported on
-Version 7, BSD or System V implementations. It is recommended that
+These 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 them be conditioned using NCURSES_VERSION.
-.SH SEE ALSO
-\fBcurs_color\fR(3X),
-\fBded\fP(1).
-.SH AUTHOR
+.SH AUTHORS
Thomas Dickey (from an analysis of the requirements for color xterm
for XFree86 3.1.2C, February 1996).
+.SH SEE ALSO
+\fB\%ded\fP(1),
+\fB\%curs_color\fP(3X)
diff --git a/man/define_key.3x b/man/define_key.3x
index 18eaff8..667d8cd 100644
--- a/man/define_key.3x
+++ b/man/define_key.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2009,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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 *
@@ -28,36 +29,43 @@
.\"
.\" Author: Thomas E. Dickey 1997
.\"
-.\" $Id: define_key.3x,v 1.14 2010/12/04 18:49:20 tom Exp $
-.TH define_key 3X ""
+.\" $Id: define_key.3x,v 1.42 2024/03/16 15:35:01 tom Exp $
+.TH define_key 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBdefine_key\fP \- define a keycode
+\fB\%define_key\fP \-
+define a \fIcurses\fR keycode
.SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-\fBint define_key(const char *definition, int keycode);\fP
+.nf
+\fB#include <curses.h>
+.PP
+\fBint define_key(const char *\fIdefinition\fP, int \fIkeycode\fP);
+.fi
.SH DESCRIPTION
-This is an extension to the curses library.
+This is an extension to the \fIcurses\fP library.
It permits an application to define keycodes with their corresponding control
-strings, so that the ncurses library will interpret them just as it would
+strings,
+so that the \fI\%ncurses\fP library will interpret them just as it would
the predefined codes in the terminfo database.
.PP
-If the given string is null, any existing definition for the keycode is
-removed.
+If \fIdefinition\fP is \fBNULL\fP,
+any existing one for the keycode is removed.
Similarly, if the given keycode is negative or zero, any existing string
for the given definition is removed.
.SH RETURN VALUE
-The keycode must be greater than zero, and the string non-null,
-otherwise ERR is returned.
-ERR may also be returned if there is insufficient memory to allocate the
+Either \fIkeycode\fP must be greater than zero,
+or \fIdefinition\fP must be non-\fBNULL\fP,
+otherwise \fBERR\fP is returned.
+\fBERR\fP may also be returned if there is insufficient memory to allocate the
data to store the definition.
-If no error is detected, OK is returned.
+If no error is detected, \fBOK\fP is returned.
.SH PORTABILITY
-These routines are specific to ncurses. They were not supported on
-Version 7, BSD or System V implementations. It is recommended that
-any code depending on them be conditioned using NCURSES_VERSION.
+These 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 them be conditioned using \fB\%NCURSES_VERSION\fP.
+.SH AUTHORS
+Thomas Dickey
.SH SEE ALSO
-\fBkeyok\fR(3X),
-\fBkey_defined\fR(3X).
-.SH AUTHOR
-Thomas Dickey.
+\fB\%keyok\fP(3X),
+\fB\%key_defined\fP(3X)
diff --git a/man/form.3x b/man/form.3x
index c379a4d..2f8f884 100644
--- a/man/form.3x
+++ b/man/form.3x
@@ -1,6 +1,7 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2014,2015 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -27,23 +28,41 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form.3x,v 1.26 2015/08/02 18:14:50 tom Exp $
-.TH form 3X ""
+.\" $Id: form.3x,v 1.54 2024/03/16 15:35:01 tom Exp $
+.TH form 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBform\fR \- curses extension for programming forms
+\fBform\fP \-
+curses extension for programming forms
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
+.nf
+\fB#include <form.h>
+.fi
.SH DESCRIPTION
-The \fBform\fR library provides terminal-independent facilities for composing
-form screens on character-cell terminals. The library includes: field
+The \fBform\fP library provides terminal-independent facilities for composing
+form screens on character-cell terminals.
+The library includes: field
routines, which create and modify form fields; and form routines, which group
fields into forms, display forms on the screen, and handle interaction with the
user.
.PP
-The \fBform\fR library uses the \fBcurses\fR libraries.
-To use the \fBform\fR library, link with the options
-\fB\-lform \-lcurses\fR.
+The \fBform\fP library uses the \fBcurses\fP libraries.
+To use the \fBform\fP library, link with the options
+\fB\-lform \-lcurses\fP.
.PP
Your program should set up the locale, e.g.,
.sp
@@ -51,106 +70,111 @@
.sp
so that input/output processing will work.
.PP
-A curses initialization routine such as \fBinitscr\fR must be called
+A curses initialization routine such as \fBinitscr\fP must be called
before using any of these functions.
.
-.SS Current Default Values for Field Attributes
+.SS "Current Default Values for Field Attributes"
.
-The \fBform\fR library maintains a default value for field attributes. You
-can get or set this default by calling the appropriate \fBset_\fR
+The \fBform\fP library maintains a default value for field attributes.
+You
+can get or set this default by calling the appropriate \fBset_\fP
or retrieval
-routine with a \fBNULL\fR field pointer. Changing this default with a
-\fBset_\fR function affects future field creations, but does not change the
+routine with a \fBNULL\fP field pointer.
+Changing this default with a
+\fBset_\fP function affects future field creations, but does not change the
rendering of fields already created.
.
-.SS Routine Name Index
+.SS "Routine Name Index"
.
-The following table lists each \fBform\fR routine and the name of
+The following table lists each \fBform\fP routine and the name of
the manual page on which it is described.
-.
+Routines flagged with \*(``*\*(''
+are \fI\%ncurses\fP-specific, not present in SVr4.
+.PP
.TS
l l
l l .
-\fBcurses\fR Routine Name Manual Page Name
+\fBcurses\fP Routine Name Manual Page Name
=
-current_field \fBform_page\fR(3X)
-data_ahead \fBform_data\fR(3X)
-data_behind \fBform_data\fR(3X)
-dup_field \fBform_field_new\fR(3X)
-dynamic_field_info \fBform_field_info\fR(3X)
-field_arg \fBform_field_validation\fR(3X)
-field_back \fBform_field_attributes\fR(3X)
-field_buffer \fBform_field_buffer\fR(3X)
-field_count \fBform_field\fR(3X)
-field_fore \fBform_field_attributes\fR(3X)
-field_index \fBform_page\fR(3X)
-field_info \fBform_field_info\fR(3X)
-field_init \fBform_hook\fR(3X)
-field_just \fBform_field_just\fR(3X)
-field_opts \fBform_field_opts\fR(3X)
-field_opts_off \fBform_field_opts\fR(3X)
-field_opts_on \fBform_field_opts\fR(3X)
-field_pad \fBform_field_attributes\fR(3X)
-field_status \fBform_field_buffer\fR(3X)
-field_term \fBform_hook\fR(3X)
-field_type \fBform_field_validation\fR(3X)
-field_userptr \fBform_field_userptr\fR(3X)
-form_driver \fBform_driver\fR(3X)
-form_driver_w \fBform_driver\fR(3X)*
-form_fields \fBform_field\fR(3X)
-form_init \fBform_hook\fR(3X)
-form_opts \fBform_opts\fR(3X)
-form_opts_off \fBform_opts\fR(3X)
-form_opts_on \fBform_opts\fR(3X)
-form_page \fBform_page\fR(3X)
-form_request_by_name \fBform_requestname\fR(3X)
-form_request_name \fBform_requestname\fR(3X)
-form_sub \fBform_win\fR(3X)
-form_term \fBform_hook\fR(3X)
-form_userptr \fBform_userptr\fR(3X)
-form_win \fBform_win\fR(3X)
-free_field \fBform_field_new\fR(3X)
-free_fieldtype \fBform_fieldtype\fR(3X)
-free_form \fBform_new\fR(3X)
-link_field \fBform_field_new\fR(3X)
-link_fieldtype \fBform_fieldtype\fR(3X)
-move_field \fBform_field\fR(3X)
-new_field \fBform_field_new\fR(3X)
-new_fieldtype \fBform_fieldtype\fR(3X)
-new_form \fBform_new\fR(3X)
-new_page \fBform_new_page\fR(3X)
-pos_form_cursor \fBform_cursor\fR(3X)
-post_form \fBform_post\fR(3X)
-scale_form \fBform_win\fR(3X)
-set_current_field \fBform_page\fR(3X)
-set_field_back \fBform_field_attributes\fR(3X)
-set_field_buffer \fBform_field_buffer\fR(3X)
-set_field_fore \fBform_field_attributes\fR(3X)
-set_field_init \fBform_hook\fR(3X)
-set_field_just \fBform_field_just\fR(3X)
-set_field_opts \fBform_field_opts\fR(3X)
-set_field_pad \fBform_field_attributes\fR(3X)
-set_field_status \fBform_field_buffer\fR(3X)
-set_field_term \fBform_hook\fR(3X)
-set_field_type \fBform_field_validation\fR(3X)
-set_field_userptr \fBform_field_userptr\fR(3X)
-set_fieldtype_arg \fBform_fieldtype\fR(3X)
-set_fieldtype_choice \fBform_fieldtype\fR(3X)
-set_form_fields \fBform_field\fR(3X)
-set_form_init \fBform_hook\fR(3X)
-set_form_opts \fBform_field_opts\fR(3X)
-set_form_page \fBform_page\fR(3X)
-set_form_sub \fBform_win\fR(3X)
-set_form_term \fBform_hook\fR(3X)
-set_form_userptr \fBform_userptr\fR(3X)
-set_form_win \fBform_win\fR(3X)
-set_max_field \fBform_field_buffer\fR(3X)
-set_new_page \fBform_new_page\fR(3X)
-unpost_form \fBform_post\fR(3X)
+current_field \fBform_page\fP(3X)
+data_ahead \fBform_data\fP(3X)
+data_behind \fBform_data\fP(3X)
+dup_field \fBform_field_new\fP(3X)
+dynamic_field_info \fBform_field_info\fP(3X)
+field_arg \fBform_field_validation\fP(3X)
+field_back \fBform_field_attributes\fP(3X)
+field_buffer \fBform_field_buffer\fP(3X)
+field_count \fBform_field\fP(3X)
+field_fore \fBform_field_attributes\fP(3X)
+field_index \fBform_page\fP(3X)
+field_info \fBform_field_info\fP(3X)
+field_init \fBform_hook\fP(3X)
+field_just \fBform_field_just\fP(3X)
+field_opts \fBform_field_opts\fP(3X)
+field_opts_off \fBform_field_opts\fP(3X)
+field_opts_on \fBform_field_opts\fP(3X)
+field_pad \fBform_field_attributes\fP(3X)
+field_status \fBform_field_buffer\fP(3X)
+field_term \fBform_hook\fP(3X)
+field_type \fBform_field_validation\fP(3X)
+field_userptr \fBform_field_userptr\fP(3X)
+form_driver \fBform_driver\fP(3X)
+form_driver_w \fBform_driver\fP(3X)*
+form_fields \fBform_field\fP(3X)
+form_init \fBform_hook\fP(3X)
+form_opts \fBform_opts\fP(3X)
+form_opts_off \fBform_opts\fP(3X)
+form_opts_on \fBform_opts\fP(3X)
+form_page \fBform_page\fP(3X)
+form_request_by_name \fBform_requestname\fP(3X)*
+form_request_name \fBform_requestname\fP(3X)*
+form_sub \fBform_win\fP(3X)
+form_term \fBform_hook\fP(3X)
+form_userptr \fBform_userptr\fP(3X)
+form_win \fBform_win\fP(3X)
+free_field \fBform_field_new\fP(3X)
+free_fieldtype \fBform_fieldtype\fP(3X)
+free_form \fBform_new\fP(3X)
+link_field \fBform_field_new\fP(3X)
+link_fieldtype \fBform_fieldtype\fP(3X)
+move_field \fBform_field\fP(3X)
+new_field \fBform_field_new\fP(3X)
+new_fieldtype \fBform_fieldtype\fP(3X)
+new_form \fBform_new\fP(3X)
+new_page \fBform_new_page\fP(3X)
+pos_form_cursor \fBform_cursor\fP(3X)
+post_form \fBform_post\fP(3X)
+scale_form \fBform_win\fP(3X)
+set_current_field \fBform_page\fP(3X)
+set_field_back \fBform_field_attributes\fP(3X)
+set_field_buffer \fBform_field_buffer\fP(3X)
+set_field_fore \fBform_field_attributes\fP(3X)
+set_field_init \fBform_hook\fP(3X)
+set_field_just \fBform_field_just\fP(3X)
+set_field_opts \fBform_field_opts\fP(3X)
+set_field_pad \fBform_field_attributes\fP(3X)
+set_field_status \fBform_field_buffer\fP(3X)
+set_field_term \fBform_hook\fP(3X)
+set_field_type \fBform_field_validation\fP(3X)
+set_field_userptr \fBform_field_userptr\fP(3X)
+set_fieldtype_arg \fBform_fieldtype\fP(3X)
+set_fieldtype_choice \fBform_fieldtype\fP(3X)
+set_form_fields \fBform_field\fP(3X)
+set_form_init \fBform_hook\fP(3X)
+set_form_opts \fBform_field_opts\fP(3X)
+set_form_page \fBform_page\fP(3X)
+set_form_sub \fBform_win\fP(3X)
+set_form_term \fBform_hook\fP(3X)
+set_form_userptr \fBform_userptr\fP(3X)
+set_form_win \fBform_win\fP(3X)
+set_max_field \fBform_field_buffer\fP(3X)
+set_new_page \fBform_new_page\fP(3X)
+unfocus_current_field \fBform_page\fP(3X)*
+unpost_form \fBform_post\fP(3X)
.TE
.SH RETURN VALUE
-Routines that return pointers return \fBNULL\fR on error,
-and set errno to the corresponding error-code returned by functions
+Routines that return pointers return \fBNULL\fP on error,
+and set \fBerrno\fP to the corresponding error-code returned by functions
returning an integer.
Routines that return
an integer return one of the following error codes:
@@ -186,26 +210,37 @@
The form driver could not process the request.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fP(3)).
.TP 5
.B E_UNKNOWN_COMMAND
The form driver code saw an unknown request code.
.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header files
-\fB<curses.h>\fR and \fB<eti.h>\fR.
-.PP
-In your library list, libform.a should be before libncurses.a; that is,
-you want to say `\-lform \-lncurses', not the other way around (which would
-give you a link error using most linkers).
+The header file \fI\%form.h\fP itself includes \fI\%curses.h\fP.
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
+.PP
+A form facility was documented in SVr4.2's
+\fICharacter User Interface Programming\fP document.
+.PP
+It is not part of X/Open Curses.
+.PP
+Aside from \fI\%ncurses\fP, there are few implementations:
+.bP
+systems based on SVr4 source code, e.g., Solaris.
+.bP
+NetBSD curses.
+.PP
+A few functions in this implementation are extensions added for
+\fI\%ncurses\fP,
+but not provided by other implementations, e.g.,
+\fBform_driver_w\fP,
+\fBunfocus_current_field\fP.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for ncurses by Eric
+Juergen Pfeifer.
+Manual pages and adaptation for \fI\%ncurses\fP by Eric
S. Raymond.
.SH SEE ALSO
-\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed
-descriptions of the entry points.
-.PP
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
+\fBcurses\fP(3X) and related pages whose names begin \*(``form_\*('' for
+detailed descriptions of the entry points.
diff --git a/man/form_cursor.3x b/man/form_cursor.3x
index ed4b420..ed8bab1 100644
--- a/man/form_cursor.3x
+++ b/man/form_cursor.3x
@@ -1,6 +1,7 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,19 +28,22 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_cursor.3x,v 1.8 2010/12/04 18:40:45 tom Exp $
-.TH form_cursor 3X ""
+.\" $Id: form_cursor.3x,v 1.31 2024/03/16 15:35:01 tom Exp $
+.TH form_cursor 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBform_cursor\fR \- position a form window cursor
+\fBpos_form_cursor\fP \-
+position a form window cursor
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-int pos_form_cursor(FORM *form);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBint pos_form_cursor(FORM *\fIform\fP);
+.fi
.SH DESCRIPTION
-The function \fBpos_form_cursor\fR restores the cursor to the position required
-for the forms driver to continue processing requests. This is useful after
-\fBcurses\fR routines have been called to do screen-painting in response to a
+The function \fBpos_form_cursor\fP restores the cursor to the position required
+for the forms driver to continue processing requests.
+This is useful after
+\fBcurses\fP routines have been called to do screen-painting in response to a
form operation.
.SH RETURN VALUE
This routine returns one of the following:
@@ -54,16 +58,14 @@
The form has not been posted.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBform\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X)
diff --git a/man/form_data.3x b/man/form_data.3x
index ed39bf5..ded82eb 100644
--- a/man/form_data.3x
+++ b/man/form_data.3x
@@ -1,6 +1,7 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,31 +28,34 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_data.3x,v 1.10 2010/12/04 18:40:45 tom Exp $
-.TH form_data 3X ""
+.\" $Id: form_data.3x,v 1.32 2024/03/16 15:35:01 tom Exp $
+.TH form_data 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBform_data\fR \- test for off-screen data in given forms
+\fBdata_ahead\fP,
+\fBdata_behind\fP \-
+test for off-screen data in given forms
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-bool data_ahead(const FORM *form);
-.br
-bool data_behind(const FORM *form);
-.br
-.SH DESCRIPTION
-The function \fBdata_ahead\fR tests whether there is off-screen data
-ahead in the given form. It returns TRUE (1) or FALSE (0).
+.nf
+\fB#include <form.h>
.PP
-The function \fBdata_behind\fR tests whether there is off-screen data
-behind in the given form. It returns TRUE (1) or FALSE (0).
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBform\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+\fBbool data_ahead(const FORM *\fIform\fP);
+\fBbool data_behind(const FORM *\fIform\fP);
+.fi
+.SH DESCRIPTION
+The function \fBdata_ahead\fP tests whether there is off-screen data
+ahead in the given form.
+It returns TRUE (1) or FALSE (0).
+.PP
+The function \fBdata_behind\fP tests whether there is off-screen data
+behind in the given form.
+It returns TRUE (1) or FALSE (0).
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X)
diff --git a/man/form_driver.3x b/man/form_driver.3x
index 4084eac..882a49d 100644
--- a/man/form_driver.3x
+++ b/man/form_driver.3x
@@ -1,5 +1,7 @@
+'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2015 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -26,28 +28,32 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_driver.3x,v 1.24 2015/08/02 18:21:11 tom Exp $
-.TH form_driver 3X ""
+.\" $Id: form_driver.3x,v 1.61 2024/04/20 18:55:09 tom Exp $
+.TH form_driver 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.SH NAME
-\fBform_driver\fR \- command-processing loop of the form system
+\fBform_driver\fP,
+\fBform_driver_w\fP \-
+command-processing loop of the form system
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-\fBint form_driver(FORM *\fP\fIform\fP\fB, int \fP\fIc\fP\fB);\fP
-.br
-\fBint form_driver_w(FORM *\fP\fIform\fP\fB, int \fP\fIc\fP\fB, wchar_t \fP\fIwch\fP\fB);\fP
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBint form_driver(FORM *\fIform\fP, int \fIc\fP);
+\fBint form_driver_w(FORM *\fIform\fP, int \fIc\fP, wchar_t \fIwc\fP);
+.fi
.SH DESCRIPTION
.SS form_driver
Once a form has been posted (displayed), you should funnel input events to it
-through \fBform_driver\fR. This routine has three major input cases:
+through \fBform_driver\fP. This routine has three major input cases:
.bP
The input is a form navigation request.
Navigation request codes are constants defined in \fB<form.h>\fP,
-which are distinct from the key- and character codes returned by \fBwgetch\fP(3X).
+which are distinct from the key- and character codes returned
+by \fBwgetch\fP(3X).
.bP
The input is a printable character.
Printable characters (which must be positive, less than 256) are
@@ -55,33 +61,32 @@
.bP
The input is the KEY_MOUSE special key associated with an mouse event.
.SS form_driver_w
-.PP
This extension simplifies the use of the forms library using wide characters.
The input is either a key code (a request) or a wide character
returned by \fBget_wch\fP(3X).
The type must be passed as well,
to enable the library to determine whether the parameter
is a wide character or a request.
-.SS Form-driver requests
-.PP
+.SS "Form Driver Requests"
The form driver requests are as follows:
+.PP
.TS
-l l
-_ _ _
-l l.
-\fIName\fR \fIDescription\fR
-REQ_BEG_FIELD Move to the beginning of the field.
-REQ_BEG_LINE Move to the beginning of the line.
+Lb Lb
+Lb Lx.
+Name Description
+_
+REQ_BEG_FIELD Move to beginning of field.
+REQ_BEG_LINE Move to beginning of the line.
REQ_CLR_EOF Clear to end of field from cursor.
REQ_CLR_EOL Clear to end of line from cursor.
REQ_CLR_FIELD Clear the entire field.
REQ_DEL_CHAR Delete character at the cursor.
REQ_DEL_LINE Delete line at the cursor.
REQ_DEL_PREV Delete character before the cursor.
-REQ_DEL_WORD Delete blank-delimited word at the cursor.
-REQ_DOWN_CHAR Move down in the field.
+REQ_DEL_WORD Delete blank-delimited word at cursor.
+REQ_DOWN_CHAR Move down in field.
REQ_DOWN_FIELD Move down to a field.
-REQ_END_FIELD Move to the end of the field.
+REQ_END_FIELD Move to the end of field.
REQ_END_LINE Move to the end of the line.
REQ_FIRST_FIELD Move to the first field.
REQ_FIRST_PAGE Move to the first page.
@@ -90,7 +95,7 @@
REQ_INS_MODE Enter insert mode.
REQ_LAST_FIELD Move to the last field.
REQ_LAST_PAGE Move to the last field.
-REQ_LEFT_CHAR Move left in the field.
+REQ_LEFT_CHAR Move left in field.
REQ_LEFT_FIELD Move left to a field.
REQ_NEW_LINE Insert or overlay a new line.
REQ_NEXT_CHAR Move to the next char.
@@ -107,34 +112,61 @@
REQ_PREV_LINE Move to the previous line.
REQ_PREV_PAGE Move to the previous page.
REQ_PREV_WORD Move to the previous word.
-REQ_RIGHT_CHAR Move right in the field.
+REQ_RIGHT_CHAR Move right in field.
REQ_RIGHT_FIELD Move right to a field.
-REQ_SCR_BCHAR Scroll the field backward a character.
-REQ_SCR_BHPAGE Scroll the field backward half a page.
-REQ_SCR_BLINE Scroll the field backward a line.
-REQ_SCR_BPAGE Scroll the field backward a page.
-REQ_SCR_FCHAR Scroll the field forward a character.
-REQ_SCR_FHPAGE Scroll the field forward half a page.
-REQ_SCR_FLINE Scroll the field forward a line.
-REQ_SCR_FPAGE Scroll the field forward a page.
-REQ_SCR_HBHALF Horizontal scroll the field backward half a line.
-REQ_SCR_HBLINE Horizontal scroll the field backward a line.
-REQ_SCR_HFHALF Horizontal scroll the field forward half a line.
-REQ_SCR_HFLINE Horizontal scroll the field forward a line.
+REQ_SCR_BCHAR Scroll field backward 1 character.
+REQ_SCR_BHPAGE Scroll field backward \(12 page.
+REQ_SCR_BLINE Scroll field backward 1 line.
+REQ_SCR_BPAGE Scroll field backward 1 page.
+REQ_SCR_FCHAR Scroll field forward 1 character.
+REQ_SCR_FHPAGE Scroll field forward \(12 page.
+REQ_SCR_FLINE Scroll field forward 1 line.
+REQ_SCR_FPAGE Scroll field forward 1 page.
+REQ_SCR_HBHALF Horizontal scroll field backward \(12 line.
+REQ_SCR_HBLINE Horizontal scroll field backward 1 line.
+REQ_SCR_HFHALF Horizontal scroll field forward \(12 line.
+REQ_SCR_HFLINE Horizontal scroll field forward 1 line.
REQ_SFIRST_FIELD Move to the sorted first field.
REQ_SLAST_FIELD Move to the sorted last field.
REQ_SNEXT_FIELD Move to the sorted next field.
REQ_SPREV_FIELD Move to the sorted previous field.
-REQ_UP_CHAR Move up in the field.
+REQ_UP_CHAR Move up in field.
REQ_UP_FIELD Move up to a field.
REQ_VALIDATION Validate field.
.TE
.PP
If the second argument is a printable character, the driver places it
-in the current position in the current field. If it is one of the forms
+in the current position in the current field.
+If it is one of the forms
requests listed above, that request is executed.
-.SS Mouse handling
+.SS "Field Validation"
+The form library makes updates to the window associated
+with form fields rather than directly to the field buffers.
.PP
+The form driver provides low-level control over updates to the form fields.
+The form driver also provides for validating modified fields
+to ensure that the contents
+meet whatever constraints an application may attach using \fBset_field_type\fP.
+.PP
+You can validate a field without making any changes to it using
+\fBREQ_VALIDATION\fP.
+The form driver also validates a field in these cases:
+.bP
+a call to \fBset_current_field\fP attempts to move to a different field.
+.bP
+a call to \fBset_current_page\fP attempts to move
+to a different page of the form.
+.bP
+a request attempts to move to a different field.
+.bP
+a request attempts to move to a different page of the form.
+.PP
+In each case, the move fails if the field is invalid.
+.PP
+If the modified field is valid, the form driver copies the modified
+data from the window associated with the field
+to the field buffer.
+.SS "Mouse Handling"
If the second argument is the KEY_MOUSE special key, the associated
mouse event is translated into one of the above pre-defined requests.
Currently only clicks in the user window (e.g., inside the form display
@@ -167,7 +199,7 @@
.bP
If you double-click a field,
the form cursor is positioned to that field
-and \fBE_UNKNOWN_COMMAND\fR is returned.
+and \fBE_UNKNOWN_COMMAND\fP is returned.
This return value makes sense,
because a double click usually means that an field-specific action should
be returned.
@@ -175,20 +207,20 @@
application specific command should be executed.
.bP
If a translation
-into a request was done, \fBform_driver\fR returns the result of this request.
+into a request was done, \fBform_driver\fP returns the result of this request.
.RE
.PP
-If you clicked outside the user window or the mouse event could not be translated
-into a form request an \fBE_REQUEST_DENIED\fR is returned.
-.SS Application-defined commands
-.PP
+If you clicked outside the user window
+or the mouse event could not be translated
+into a form request an \fBE_REQUEST_DENIED\fP is returned.
+.SS "Application-defined Commands"
If the second argument is neither printable nor one of the above
pre-defined form requests, the driver assumes it is an application-specific
-command and returns \fBE_UNKNOWN_COMMAND\fR. Application-defined commands
-should be defined relative to \fBMAX_COMMAND\fR, the maximum value of these
+command and returns \fBE_UNKNOWN_COMMAND\fP. Application-defined commands
+should be defined relative to \fBMAX_COMMAND\fP, the maximum value of these
pre-defined requests.
.SH RETURN VALUE
-\fBform_driver\fR returns one of the following error codes:
+\fBform_driver\fP returns one of the following error codes:
.TP 5
.B E_OK
The routine succeeded.
@@ -205,26 +237,29 @@
.B E_INVALID_FIELD
Contents of field is invalid.
.TP 5
+.B E_NOT_CONNECTED
+No fields are connected to the form.
+.TP 5
.B E_REQUEST_DENIED
The form driver could not process the request.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fP(3)).
.TP 5
.B E_UNKNOWN_COMMAND
The form driver code saw an unknown request code.
-.
-.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBform\fR(3X),
-\fBform_variables\fR(3X),
-\fBgetch\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header files
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X),
+\fB\%form_fieldtype\fP(3X),
+\fB\%form_field_buffer\fP(3X),
+\fB\%form_field_validation\fP(3X),
+\fB\%form_variables\fP(3X),
+\fB\%getch\fP(3X)
diff --git a/man/form_field.3x b/man/form_field.3x
index 19a8b88..9799d0c 100644
--- a/man/form_field.3x
+++ b/man/form_field.3x
@@ -1,6 +1,7 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2012 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 *
@@ -27,39 +28,38 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field.3x,v 1.11 2012/11/03 23:03:59 tom Exp $
-.TH form_field 3X ""
+.\" $Id: form_field.3x,v 1.34 2024/03/16 15:35:01 tom Exp $
+.TH form_field 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBform_field\fR \- make and break connections between fields and forms
+\fBform_field\fP \-
+make and break connections between fields and forms
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-int set_form_fields(FORM *form, FIELD **fields);
-.br
-FIELD **form_fields(const FORM *form);
-.br
-int field_count(const FORM *form);
-.br
-int move_field(FIELD *field, int frow, int fcol);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBint set_form_fields(FORM *\fIform\fP, FIELD **\fIfields\fP);
+\fBFIELD **form_fields(const FORM *\fIform\fP);
+\fBint field_count(const FORM *\fIform\fP);
+\fBint move_field(FIELD *\fIfield\fP, int \fIfrow\fP, int \fIfcol\fP);
+.fi
.SH DESCRIPTION
-The function \fBset_form_fields\fR changes the field pointer array of
-the given \fIform\fR. The array must be terminated by a \fBNULL\fR.
+The function \fBset_form_fields\fP changes the field pointer array of
+the given \fIform\fP. The array must be terminated by a \fBNULL\fP.
.PP
-The function \fBform_fields\fR returns the field array of the given form.
+The function \fBform_fields\fP returns the field array of the given form.
.PP
-The function \fBfield_count\fR returns the count of fields in \fIform\fR.
+The function \fBfield_count\fP returns the count of fields in \fIform\fP.
.PP
-The function \fBmove_field\fR moves the given field (which must be disconnected)
+The function \fBmove_field\fP moves the given field (which must be disconnected)
to a specified location on the screen.
.SH RETURN VALUE
-The function \fBform_fields\fR returns a pointer (which may be \fBNULL\fR).
-It does not set errno.
+The function \fBform_fields\fP returns a pointer (which may be \fBNULL\fP).
+It does not set \fBerrno\fP.
.PP
-The function \fBfield_count\fR returns \fBERR\fR if the \fIform\fP parameter
+The function \fBfield_count\fP returns \fBERR\fP if the \fIform\fP parameter
is \fBNULL\fP.
.PP
-The functions \fBset_form_fields\fR and \fBmove_field\fR return one of
+The functions \fBset_form_fields\fP and \fBmove_field\fP return one of
the following codes on error:
.TP 5
.B E_OK
@@ -75,18 +75,17 @@
The form is already posted.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBform\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.PP
-The SVr4 forms library documentation specifies the \fBfield_count\fR error value
-as \-1 (which is the value of \fBERR\fR).
+The SVr4 forms library documentation specifies the \fBfield_count\fP error value
+as \-1 (which is the value of \fBERR\fP).
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X)
diff --git a/man/form_field_attributes.3x b/man/form_field_attributes.3x
index da3ad79..687e909 100644
--- a/man/form_field_attributes.3x
+++ b/man/form_field_attributes.3x
@@ -1,6 +1,7 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2006,2010 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 *
@@ -27,38 +28,51 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_attributes.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
-.TH form_field_attributes 3X ""
+.\" $Id: form_field_attributes.3x,v 1.35 2024/03/16 15:35:01 tom Exp $
+.TH form_field_attributes 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-\fBform_field_attributes\fR \- color and attribute control for form fields
+\fBform_field_attributes\fP \-
+color and attribute control for form fields
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-int set_field_fore(FIELD *field, chtype attr);
-.br
-chtype field_fore(const FIELD *field);
-.br
-int set_field_back(FIELD *field, chtype attr);
-.br
-chtype field_back(const FIELD *field);
-.br
-int set_field_pad(FIELD *field, int pad);
-.br
-int field_pad(const FIELD *field);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBint set_field_fore(FIELD *\fIfield\fP, chtype \fIattr\fP);
+\fBchtype field_fore(const FIELD *\fIfield\fP);
+.PP
+\fBint set_field_back(FIELD *\fIfield\fP, chtype \fIattr\fP);
+\fBchtype field_back(const FIELD *\fIfield\fP);
+.PP
+\fBint set_field_pad(FIELD *\fIfield\fP, int \fIpad\fP);
+\fBint field_pad(const FIELD *\fIfield\fP);
+.fi
.SH DESCRIPTION
-The function \fBset_field_fore\fR sets the foreground attribute of
-\fIfield\fR. This is the highlight used to display the field contents. The
-function \fBfield_fore\fR returns the foreground attribute. The default is
-\fBA_STANDOUT\fR.
+The function \fBset_field_fore\fP sets the foreground attribute of
+\fIfield\fP. This is the highlight used to display the field contents. The
+function \fBfield_fore\fP returns the foreground attribute.
+The default is
+\fBA_STANDOUT\fP.
.PP
-The function \fBset_field_back\fR sets the background attribute of
-\fIform\fR. This is the highlight used to display the extent fields in the
-form. The function \fBfield_back\fR returns the background attribute. The
-default is \fBA_NORMAL\fR.
+The function \fBset_field_back\fP sets the background attribute of
+\fIform\fP. This is the highlight used to display the extent fields in the
+form.
+The function \fBfield_back\fP returns the background attribute.
+The
+default is \fBA_NORMAL\fP.
.PP
-The function \fBset_field_pad\fR sets the character used to fill the field.
-The function \fBfield_pad\fR returns the given form's pad character. The
+The function \fBset_field_pad\fP sets the character used to fill the field.
+The function \fBfield_pad\fP returns the given form's pad character.
+The
default is a blank.
.SH RETURN VALUE
These routines return one of the following:
@@ -70,17 +84,14 @@
Routine detected an incorrect or out-of-range argument.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.
-.SH SEE ALSO
-\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed
-descriptions of the entry points.
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X) and related pages whose names begin \*(``form_\*(''
+for detailed descriptions of the entry points.
diff --git a/man/form_field_buffer.3x b/man/form_field_buffer.3x
index b4ff8cb..ba176d3 100644
--- a/man/form_field_buffer.3x
+++ b/man/form_field_buffer.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2008,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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 *
@@ -27,39 +27,51 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_buffer.3x,v 1.19 2010/12/04 18:38:55 tom Exp $
-.TH form_field_buffer 3X ""
+.\" $Id: form_field_buffer.3x,v 1.45 2024/03/16 15:35:01 tom Exp $
+.TH form_field_buffer 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.SH NAME
-\fBform_field_buffer\fR \- field buffer control
+\fBform_field_buffer\fP \-
+field buffer control
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.sp
-int set_field_buffer(FIELD *field, int buf, const char *value);
-.br
-char *field_buffer(const FIELD *field, int buffer);
-.br
-int set_field_status(FIELD *field, bool status);
-.br
-bool field_status(const FIELD *field);
-.br
-int set_max_field(FIELD *field, int max);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBint set_field_buffer(FIELD *\fIfield\fP, int \fIbuf\fP, const char *\fIvalue\fP);
+\fBchar *field_buffer(const FIELD *\fIfield\fP, int \fIbuffer\fP);
+.PP
+\fBint set_field_status(FIELD *\fIfield\fP, bool \fIstatus\fP);
+\fBbool field_status(const FIELD *\fIfield\fP);
+.PP
+\fBint set_max_field(FIELD *\fIfield\fP, int \fImax\fP);
+.fi
.SH DESCRIPTION
-The function \fBset_field_buffer\fR sets the numbered buffer of the given field
+The function \fBset_field_buffer\fP sets the numbered buffer of the given field
to contain a given string:
.RS 3
.bP
Buffer 0 is the displayed value of the field.
.bP
-Other numbered buffers may be allocated by applications through the \fBnbuf\fR
-argument of (see \fBform_field_new\fR(3X))
+Other numbered buffers may be allocated by applications through the \fBnbuf\fP
+argument of (see \fBform_field_new\fP(3X))
but are not manipulated by the forms library.
.RE
.PP
-The function \fBfield_buffer\fR returns a pointer to
+The function \fBfield_buffer\fP returns a pointer to
the contents of the given numbered buffer:
.RS 3
.bP
@@ -84,15 +96,16 @@
for long-term storage of form data.
.RE
.PP
-The function \fBset_field_status\fR sets the associated status flag of
-\fIfield\fR; \fBfield_status\fR gets the current value. The status flag
+The function \fBset_field_status\fP sets the associated status flag of
+\fIfield\fP; \fBfield_status\fP gets the current value.
+The status flag
is set to a nonzero value whenever the field changes.
.PP
-The function \fBset_max_field\fR sets the maximum size for a dynamic field.
+The function \fBset_max_field\fP sets the maximum size for a dynamic field.
An argument of 0 turns off any maximum size threshold for that field.
.SH RETURN VALUE
-The \fBfield_buffer\fR function returns NULL on error.
-It sets errno according to their success:
+The \fBfield_buffer\fP function returns NULL on error.
+It sets \fBerrno\fP according to their success:
.TP 5
.B E_OK
The routine succeeded.
@@ -100,7 +113,7 @@
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.PP
-The \fBfield_status\fR function returns \fBTRUE\fR or \fBFALSE\fR.
+The \fBfield_status\fP function returns \fBTRUE\fP or \fBFALSE\fP.
.PP
The remaining routines return one of the following:
.TP 5
@@ -108,25 +121,27 @@
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fP(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
-.SH SEE ALSO
-\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed
-descriptions of the entry points.
.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-.PP
When configured for wide characters, \fBfield_buffer\fP returns a pointer
to temporary storage (allocated and freed by the library).
The application should not attempt to modify the data.
It will be freed on the next call to \fBfield_buffer\fP to return the
same buffer.
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
+.PP
+The \fBset_max_field\fP function checks for an \fI\%ncurses\fP extension
+\fBO_INPUT_FIELD\fP which allows a dynamic field to shrink if the new
+limit is smaller than the current field size.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X) and related pages whose names begin \*(``form_\*(''
+for detailed descriptions of the entry points.
diff --git a/man/form_field_info.3x b/man/form_field_info.3x
index 6a1af6c..84b10d9 100644
--- a/man/form_field_info.3x
+++ b/man/form_field_info.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,29 +27,47 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_info.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
-.TH form_field_info 3X ""
+.\" $Id: form_field_info.3x,v 1.32 2024/03/16 15:35:01 tom Exp $
+.TH form_field_info 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-\fBform_field_info\fR \- retrieve field characteristics
+\fBdynamic_field_info\fP,
+\fBfield_info\fP \-
+retrieve field characteristics
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-int field_info(const FIELD *field, int *rows, int *cols,
- int *frow, int *fcol, int *nrow, int *nbuf);
-.br
-int dynamic_field_info(const FIELD *field, int *rows, int *cols, int *max);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBint field_info(const FIELD *\fIfield\fP,
+ \fBint *\fIrows\fB, int *\fIcols\fB,\fR
+ \fBint *\fIfrow\fB, int *\fIfcol\fB,\fR
+ \fBint *\fInrow\fB, int *\fInbuf\fB);\fR
+.PP
+\fBint dynamic_field_info(const FIELD *\fIfield\fB,\fR
+ \fBint *\fIrows\fB, int *\fIcols\fB, int *\fImax\fB);\fR
+.fi
.SH DESCRIPTION
-The function \fBfield_info\fR returns the sizes and other attributes passed in
-to the field at its creation time. The attributes are: height, width, row of
+The function \fBfield_info\fP returns the sizes and other attributes passed in
+to the field at its creation time.
+The attributes are: height, width, row of
upper-left corner, column of upper-left corner, number off-screen rows, and
number of working buffers.
.PP
-The function \fBdynamic_field_info\fR returns the actual size of the field, and
-its maximum possible size. If the field has no size limit, the location
+The function \fBdynamic_field_info\fP returns the actual size of the field, and
+its maximum possible size.
+If the field has no size limit, the location
addressed by the third argument will be set to 0.
A field can be made dynamic
-by turning off the \fBO_STATIC\fR option with \fBfield_opts_off\fR.
+by turning off the \fBO_STATIC\fP option with \fBfield_opts_off\fP.
.SH RETURN VALUE
These routines return one of the following:
.TP 5
@@ -57,23 +75,21 @@
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fP(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
-.SH SEE ALSO
-\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed
-descriptions of the entry points.
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.PP
A null (zero pointer) is accepted for any of the return values,
to ignore that value.
Not all implementations allow this, e.g., Solaris 2.7 does not.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X) and related pages whose names begin \*(``form_\*(''
+for detailed descriptions of the entry points.
diff --git a/man/form_field_just.3x b/man/form_field_just.3x
index 2f223e9..c1fd554 100644
--- a/man/form_field_just.3x
+++ b/man/form_field_just.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,46 +27,56 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_just.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
-.TH form_field_just 3X ""
+.\" $Id: form_field_just.3x,v 1.35 2024/03/16 15:35:01 tom Exp $
+.TH form_field_just 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-\fBform_field_just\fR \- retrieve field characteristics
+\fBset_field_just\fP,
+\fBfield_just\fP \-
+retrieve field characteristics
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-int set_field_just(FIELD *field, int justification);
-.br
-int field_just(const FIELD *field);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBint set_field_just(FIELD *\fIfield\fP, int \fIjustification\fP);
+\fBint field_just(const FIELD *\fIfield\fP);
+.fi
.SH DESCRIPTION
-The function \fBset_field_just\fR sets the justification attribute of
-a field; \fBfield_just\fR returns a field's justification attribute.
+The function \fBset_field_just\fP sets the justification attribute of
+a field; \fBfield_just\fP returns a field's justification attribute.
The attribute may be one of NO_JUSTIFICATION, JUSTIFY_RIGHT,
JUSTIFY_LEFT, or JUSTIFY_CENTER.
.
.SH RETURN VALUE
-The function \fBfield_just\fR returns one of: NO_JUSTIFICATION,
+The function \fBfield_just\fP returns one of: NO_JUSTIFICATION,
JUSTIFY_RIGHT, JUSTIFY_LEFT, or JUSTIFY_CENTER.
.PP
-The function \fBset_field_just\fR returns one of the following:
+The function \fBset_field_just\fP returns one of the following:
.TP 5
.B E_OK
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fP(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
-.SH SEE ALSO
-\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed
-descriptions of the entry points.
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X) and related pages whose names begin \*(``form_\*(''
+for detailed descriptions of the entry points.
diff --git a/man/form_field_new.3x b/man/form_field_new.3x
index 23a3516..9cf08ad 100644
--- a/man/form_field_new.3x
+++ b/man/form_field_new.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,42 +27,47 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_new.3x,v 1.18 2010/12/04 18:40:45 tom Exp $
-.TH form_field_new 3X ""
+.\" $Id: form_field_new.3x,v 1.41 2024/03/16 15:35:01 tom Exp $
+.TH form_field_new 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBform_field_new\fR \- create and destroy form fields
+\fBnew_field\fP,
+\fBdup_field\fP,
+\fBlink_field\fP,
+\fBfree_field\fP \-
+create and destroy form fields
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-FIELD *new_field(int height, int width,
- int toprow, int leftcol,
- int offscreen, int nbuffers);
-.br
-FIELD *dup_field(FIELD *field, int toprow, int leftcol);
-.br
-FIELD *link_field(FIELD *field, int toprow, int leftcol);
-.br
-int free_field(FIELD *field);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBFIELD *new_field(int \fIheight\fP, int \fIwidth\fP,
+ \fBint \fItoprow\fB, int \fIleftcol\fB,\fR
+ \fBint \fIoffscreen\fB, int \fInbuffers\fB);\fR
+\fBFIELD *dup_field(FIELD *\fIfield\fB, int \fItoprow\fB, int \fIleftcol\fB);\fR
+\fBFIELD *link_field(FIELD *\fIfield\fB, int \fItoprow\fB, int \fIleftcol\fB);\fR
+\fBint free_field(FIELD *\fIfield\fB);\fR
+.fi
.SH DESCRIPTION
-The function \fBnew_field\fR allocates a new field and initializes it from the
+The function \fBnew_field\fP allocates a new field and initializes it from the
parameters given: height, width, row of upper-left corner, column of upper-left
corner, number off-screen rows, and number of additional working buffers.
.PP
-The function \fBdup_field\fR duplicates a field at a new location. Most
+The function \fBdup_field\fP duplicates a field at a new location.
+Most
attributes (including current contents, size, validation type, buffer count,
growth threshold, justification, foreground, background, pad character,
-options, and user pointer) are copied. Field status and the field page bit are
+options, and user pointer) are copied.
+Field status and the field page bit are
not copied.
.PP
-The function \fBlink_field\fR acts like \fBdup_field\fR, but the new field
-shares buffers with its parent. Attribute data is separate.
+The function \fBlink_field\fP acts like \fBdup_field\fP, but the new field
+shares buffers with its parent.
+Attribute data is separate.
.PP
-The function \fBfree_field\fR de-allocates storage associated with a field.
+The function \fBfree_field\fP de-allocates storage associated with a field.
.SH RETURN VALUE
-The function, \fBnew_field\fR, \fBdup_field\fR, \fBlink_field\fR return
-\fBNULL\fR on error.
-They set errno according to their success:
+The functions \fBnew_field\fP, \fBdup_field\fP, \fBlink_field\fP return
+\fBNULL\fP on error.
+They set \fBerrno\fP according to their success:
.TP 5
.B E_OK
The routine succeeded.
@@ -73,7 +78,7 @@
.B E_SYSTEM_ERROR
System error occurred, e.g., malloc failure.
.PP
-The function \fBfree_field\fR returns one of the following:
+The function \fBfree_field\fP returns one of the following:
.TP 5
.B E_OK
The routine succeeded.
@@ -83,18 +88,17 @@
.TP 5
.B E_CONNECTED
field is connected.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBform\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.PP
It may be unwise to count on the set of attributes copied by
-\fBdup_field\fR being portable; the System V forms library documents are
+\fBdup_field\fP being portable; the System V forms library documents are
not very explicit about what gets copied and what does not.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X)
diff --git a/man/form_field_opts.3x b/man/form_field_opts.3x
index ff27fe1..9ab3ad0 100644
--- a/man/form_field_opts.3x
+++ b/man/form_field_opts.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2014 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2014,2015 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 *
@@ -27,38 +27,43 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_opts.3x,v 1.17 2014/07/26 21:21:57 tom Exp $
-.TH form_field_opts 3X ""
+.\" $Id: form_field_opts.3x,v 1.44 2024/03/16 15:35:01 tom Exp $
+.TH form_field_opts 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBform_field_opts\fR \- set and get field options
+\fBset_field_opts\fP,
+\fBfield_opts_on\fP,
+\fBfield_opts_off\fP,
+\fBfield_opts\fP \-
+set and get field options
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-int set_field_opts(FIELD *field, Field_Options opts);
-.br
-int field_opts_on(FIELD *field, Field_Options opts);
-.br
-int field_opts_off(FIELD *field, Field_Options opts);
-.br
-Field_Options field_opts(const FIELD *field);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBint set_field_opts(FIELD *\fIfield\fP, Field_Options \fIopts\fP);
+\fBField_Options field_opts(const FIELD *\fIfield\fP);
+.PP
+\fBint field_opts_on(FIELD *\fIfield\fP, Field_Options \fIopts\fP);
+\fBint field_opts_off(FIELD *\fIfield\fP, Field_Options \fIopts\fP);
+.fi
.SH DESCRIPTION
-The function \fBset_field_opts\fR sets all the given field's option bits (field
+The function \fBset_field_opts\fP sets all the given field's option bits (field
option bits may be logically-OR'ed together).
.PP
-The function \fBfield_opts_on\fR turns on the given option bits, and leaves
+The function \fBfield_opts_on\fP turns on the given option bits, and leaves
others alone.
.PP
-The function \fBfield_opts_off\fR turns off the given option bits, and leaves
+The function \fBfield_opts_off\fP turns off the given option bits, and leaves
others alone.
.PP
-The function \fBfield_opts\fR returns the field's current option bits.
+The function \fBfield_opts\fP returns the field's current option bits.
.PP
The following standard options are defined (all are on by default):
.TP 5
O_ACTIVE
-The field is visited during processing. If this option is off, the field will
-not be reachable by navigation keys. Please notice that an invisible field
+The field is visited during processing.
+If this option is off, the field will
+not be reachable by navigation keys.
+Please notice that an invisible field
appears to be inactive also.
.TP 5
O_AUTOSKIP
@@ -84,19 +89,38 @@
Turn this option off to create a dynamic field.
.TP 5
O_VISIBLE
-The field is displayed. If this option is off, display of the field is
+The field is displayed.
+If this option is off, display of the field is
suppressed.
.TP 5
O_WRAP
-Words that do not fit on a line are wrapped to the next line. Words are
+Words that do not fit on a line are wrapped to the next line.
+Words are
blank-separated.
.PP
-One extension option is defined (extensions are off by default):
+These extension options are defined (extensions are off by default):
.TP 5
O_DYNAMIC_JUSTIFY
Permit dynamic fields to be justified, like static fields.
+.TP 5
+O_NO_LEFT_STRIP
+Preserve leading whitespace in the field buffer, which is normally discarded.
+.TP 5
+O_EDGE_INSERT_STAY
+When inserting into a field up to the boundary position,
+optionally delay the scrolling,
+so that the last inserted character remains visible,
+but advance the cursor to reflect the insertion.
+This allows the form library to display the
+inserted character in one-character fields
+as well as allowing the library to maintain consistent state.
+.TP 5
+O_INPUT_FIELD
+The \fBset_max_field\fP function checks for this extension,
+which allows a dynamic field to shrink if the new
+limit is smaller than the current field size.
.SH RETURN VALUE
-Except for \fBfield_opts\fR, each routine returns one of the following:
+Except for \fBfield_opts\fP, each routine returns one of the following:
.TP 5
.B E_OK
The routine succeeded.
@@ -108,17 +132,15 @@
The field is the current field.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBform\fR(3X).
-\fBform_field_just\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X),
+\fB\%form_field_just\fP(3X)
diff --git a/man/form_field_userptr.3x b/man/form_field_userptr.3x
index 898da97..6eea092 100644
--- a/man/form_field_userptr.3x
+++ b/man/form_field_userptr.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,37 +27,39 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_userptr.3x,v 1.10 2010/12/04 18:40:45 tom Exp $
-.TH form_field_userptr 3X ""
+.\" $Id: form_field_userptr.3x,v 1.30 2024/03/16 15:35:01 tom Exp $
+.TH form_field_userptr 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBform_field_userptr\fR \- associate application data with a form field
+\fBset_field_userptr\fP,
+\fBfield_userptr\fP \-
+associate application data with a form field
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-int set_field_userptr(FIELD *field, void*userptr);
-.br
-void *field_userptr(const FIELD *field);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBint set_field_userptr(FIELD *\fIfield\fP, void *\fIuserptr\fP);
+\fBvoid *field_userptr(const FIELD *\fIfield\fP);
+.fi
.SH DESCRIPTION
Every form field has a field that can be used to hold application-specific data
-(that is, the form-driver code leaves it alone). These functions get and set
+(that is, the form-driver code leaves it alone).
+These functions get and set
that field.
.SH RETURN VALUE
-The function \fBfield_userptr\fR returns a pointer (which may be \fBNULL\fR).
-It does not set errno.
+The function \fBfield_userptr\fP returns a pointer (which may be \fBNULL\fP).
+It does not set \fBerrno\fP.
.PP
-The function \fBset_field_userptr\fR returns \fBE_OK\fP (success).
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBform\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+The function \fBset_field_userptr\fP returns \fBE_OK\fP (success).
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.PP
The user pointer is a void pointer.
We chose not to leave it as a char pointer for SVr4 compatibility.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X)
diff --git a/man/form_field_validation.3x b/man/form_field_validation.3x
index 3505fdb..54fa2a7 100644
--- a/man/form_field_validation.3x
+++ b/man/form_field_validation.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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 *
@@ -26,113 +27,183 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_validation.3x,v 1.20 2010/12/04 18:38:55 tom Exp $
-.TH form_field_validation 3X ""
+.\" $Id: form_field_validation.3x,v 1.53 2024/03/16 15:35:01 tom Exp $
+.TH form_field_validation 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBform_field_validation\fR \- data type validation for fields
+\fBform_field_validation\fP \-
+data type validation for fields
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-int set_field_type(FIELD *field, FIELDTYPE *type, ...);
-.br
-FIELDTYPE *field_type(const FIELD *field);
-.br
-void *field_arg(const FIELD *field);
-.sp
-FIELDTYPE *TYPE_ALNUM;
-.br
-FIELDTYPE *TYPE_ALPHA;
-.br
-FIELDTYPE *TYPE_ENUM;
-.br
-FIELDTYPE *TYPE_INTEGER;
-.br
-FIELDTYPE *TYPE_NUMERIC;
-.br
-FIELDTYPE *TYPE_REGEXP;
-.br
-FIELDTYPE *TYPE_IPV4;
-.br
-.SH DESCRIPTION
-The function \fBset_field_type\fR declares a data type for a given form field.
-This is the type checked by validation functions.
-The predefined types are as follows:
-.TP 5
-TYPE_ALNUM
-Alphanumeric data. Requires a third \fBint\fR argument, a minimum field width.
-.TP 5
-TYPE_ALPHA
-Character data. Requires a third \fBint\fR argument, a minimum field width.
-.TP 5
-TYPE_ENUM
-Accept one of a specified set of strings. Requires a third \fB(char **)\fR
-argument pointing to a string list; a fourth \fBint\fR flag argument to enable
-case-sensitivity; and a fifth \fBint\fR flag argument specifying whether a partial
-match must be a unique one (if this flag is off, a prefix matches the first
-of any set of more than one list elements with that prefix). Please notice
-that the string list is copied. So you may use a list that lives in automatic variables on the stack.
-.TP 5
-TYPE_INTEGER
-Integer data, parsable to an integer by \fBatoi(3)\fR. Requires a third
-\fBint\fR argument controlling the precision, a fourth \fBlong\fR argument
-constraining minimum value, and a fifth \fBlong\fR constraining maximum value.
-If the maximum value is less than or equal to the minimum value, the range is
-simply ignored. On return the field buffer is formatted according to the
-\fBprintf\fR format specification ".*ld", where the '*' is replaced by the
-precision argument.
-For details of the precision handling see \fBprintf's\fR man-page.
-.TP 5
-TYPE_NUMERIC
-Numeric data (may have a decimal-point part). Requires a third
-\fBint\fR argument controlling the precision, a fourth \fBdouble\fR
-argument constraining minimum value, and a fifth \fBdouble\fR constraining
-maximum value. If your system supports locales, the decimal point character
-to be used must be the one specified by your locale.
-If the maximum value is less than or equal to the minimum value, the range is
-simply ignored. On return the field buffer is formatted according to the
-\fBprintf\fR format specification ".*f", where the '*' is replaced by the
-precision argument.
-For details of the precision handling see \fBprintf's\fR man-page.
-.TP 5
-TYPE_REGEXP
-Regular expression data. Requires a regular expression \fB(char *)\fR third argument;
-the data is valid if the regular expression matches it. Regular expressions
-are in the format of \fBregcomp\fR and \fBregexec\fR. Please notice
-that the regular expression must match the whole field. If you have for
-example an eight character wide field, a regular expression "^[0\-9]*$" always
-means that you have to fill all eight positions with digits. If you want to
-allow fewer digits, you may use for example "^[0\-9]* *$" which is good for
-trailing spaces (up to an empty field), or "^ *[0\-9]* *$" which is good for
-leading and trailing spaces around the digits.
-.TP 5
-TYPE_IPV4
-An Internet Protocol Version 4 address. This requires no additional argument. It
-is checked whether or not the buffer has the form a.b.c.d, where a,b,c and d are
-numbers between 0 and 255. Trailing blanks in the buffer are ignored. The address
-itself is not validated. Please note that this is an ncurses extension. This
-field type may not be available in other curses implementations.
+.nf
+\fB#include <form.h>
.PP
-It is possible to set up new programmer-defined field types. See the
-\fBform_fieldtype\fR(3X) manual page.
+\fBvoid *field_arg(const FIELD *\fIfield\fP);
+\fBFIELDTYPE *field_type(const FIELD *\fIfield\fP);
+\fBint set_field_type(FIELD *\fIfield\fP, FIELDTYPE *\fItype\fP, ...);
+.PP
+\fI/* predefined field types */\fP
+\fBFIELDTYPE *TYPE_ALNUM;
+\fBFIELDTYPE *TYPE_ALPHA;
+\fBFIELDTYPE *TYPE_ENUM;
+\fBFIELDTYPE *TYPE_INTEGER;
+\fBFIELDTYPE *TYPE_NUMERIC;
+\fBFIELDTYPE *TYPE_REGEXP;
+\fBFIELDTYPE *TYPE_IPV4;
+.fi
+.SH DESCRIPTION
+By default, no validation is done on form fields.
+You can associate a form with with a \fIfield type\fP,
+making the form library validate input.
+.SS field_arg
+Returns a pointer to the field's argument block.
+The \fIargument block\fP is an opaque structure containing
+a copy of the arguments provided in a \fBset_field_type\fP call.
+.SS field_type
+Returns a pointer to the \fIfield type\fP associated with the form field,
+i.e., by calling \fBset_field_type\fP.
+.SS set_field_type
+The function \fBset_field_type\fP associates
+a field type with a given form field.
+This is the type checked by validation functions.
+Most field types are configurable,
+via arguments which the caller provides when calling \fBset_field_type\fP.
+.PP
+Several field types are predefined by the form library.
+.SH PREDEFINED TYPES
+It is possible to set up new programmer-defined field types.
+Field types are implemented via the \fBFIELDTYPE\fP data
+structure, which contains several pointers to functions.
+.PP
+See the \fBform_fieldtype\fP(3X) manual page,
+which describes functions which can be used to construct
+a field-type dynamically.
+.PP
+The predefined types are as follows:
+.SS TYPE_ALNUM
+Alphanumeric data.
+Required parameter:
+.bP
+a third \fBint\fP argument, a minimum field width.
+.SS TYPE_ALPHA
+Character data.
+Required parameter:
+.bP
+a third \fBint\fP argument, a minimum field width.
+.SS TYPE_ENUM
+Accept one of a specified set of strings.
+Required parameters:
+.bP
+a third \fB(char **)\fP argument pointing to a string list;
+.bP
+a fourth \fBint\fP flag argument to enable case-sensitivity;
+.bP
+a fifth \fBint\fP flag argument specifying whether a partial
+match must be a unique one.
+If this flag is off, a prefix matches the first
+of any set of more than one list elements with that prefix.
+.PP
+The library copies the string list,
+so you may use a list that lives in automatic variables on the stack.
+.SS TYPE_INTEGER
+Integer data, parsable to an integer by \fBatoi\fP(3).
+Required parameters:
+.bP
+a third \fBint\fP argument controlling the precision,
+.bP
+a fourth \fBlong\fP argument constraining minimum value,
+.bP
+a fifth \fBlong\fP constraining maximum value.
+If the maximum value is less than or equal to the minimum value, the range is
+simply ignored.
+.PP
+On return, the field buffer is formatted according to the
+\fBprintf\fP format specification \*(``.*ld\*('',
+where the \*(``*\*('' is replaced by the precision argument.
+.PP
+For details of the precision handling see \fBprintf\fP(3).
+.SS TYPE_NUMERIC
+Numeric data (may have a decimal-point part).
+Required parameters:
+.bP
+a third \fBint\fP argument controlling the precision,
+.bP
+a fourth \fBdouble\fP argument constraining minimum value,
+.bP
+and a fifth \fBdouble\fP constraining maximum value.
+If your system supports locales,
+the decimal point character must be the one specified by your locale.
+If the maximum value is less than or equal to the minimum value,
+the range is simply ignored.
+.PP
+On return, the field buffer is formatted according to the
+\fBprintf\fP format specification \*(``.*f\*('',
+where the \*(``*\*('' is replaced by the precision argument.
+.PP
+For details of the precision handling see \fBprintf\fP(3).
+.SS TYPE_REGEXP
+Regular expression data.
+Required parameter:
+.bP
+a third argument, a regular expression \fB(char *)\fP string.
+The data is valid if the regular expression matches it.
+.PP
+Regular expressions
+are in the format of \fBregcomp\fP and \fBregexec\fP.
+.PP
+The regular expression must match the whole field.
+If you have for example, an eight character wide field,
+a regular expression "^[0\-9]*$" always
+means that you have to fill all eight positions with digits.
+If you want to allow fewer digits,
+you may use for example "^[0\-9]* *$" which is good for
+trailing spaces (up to an empty field),
+or "^ *[0\-9]* *$" which is good for
+leading and trailing spaces around the digits.
+.SS TYPE_IPV4
+An Internet Protocol Version 4 address.
+Required parameter:
+.bP
+none
+.PP
+The form library checks whether or not the buffer has the form \fIa.b.c.d\fP,
+where \fIa\fP, \fIb\fP, \fIc\fP, and \fId\fP are numbers in the range 0 to 255.
+Trailing blanks in the buffer are ignored.
+The address itself is not validated.
+.PP
+This is an \fI\%ncurses\fP extension;
+this field type may not be available in other curses implementations.
.SH RETURN VALUE
-The functions \fBfield_type\fR and \fBfield_arg\fR return \fBNULL\fR on
-error. The function \fBset_field_type\fR returns one of the following:
+The functions \fBfield_type\fP and \fBfield_arg\fP return \fBNULL\fP on error.
+The function \fBset_field_type\fP returns one of the following:
.TP 5
.B E_OK
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBform\fR(3X),
-\fBform_variables\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X),
+\fB\%form_fieldtype\fP(3X),
+\fB\%form_variables\fP(3X)
diff --git a/man/form_fieldtype.3x b/man/form_fieldtype.3x
index 028e9b0..81a58b1 100644
--- a/man/form_fieldtype.3x
+++ b/man/form_fieldtype.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2006,2010 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 *
@@ -27,77 +27,102 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_fieldtype.3x,v 1.16 2010/12/04 18:40:45 tom Exp $
-.TH form_fieldtype 3X ""
+.\" $Id: form_fieldtype.3x,v 1.46 2024/03/16 15:35:01 tom Exp $
+.TH form_fieldtype 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBform_fieldtype\fR \- define validation-field types
+\fBform_fieldtype\fP \-
+define validation-field types
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-FIELDTYPE *new_fieldtype(
- bool (* const field_check)(FIELD *, const void *),
- bool (* const char_check)(int, const void *));
-.br
-int free_fieldtype(FIELDTYPE *fieldtype);
-.br
-int set_fieldtype_arg(
- FIELDTYPE *fieldtype,
- void *(* const make_arg)(va_list *),
- void *(* const copy_arg)(const void *),
- void (* const free_arg)(void *));
-.br
-int set_fieldtype_choice(
- FIELDTYPE *fieldtype,
- bool (* const next_choice)(FIELD *, const void *),
- bool (* const prev_choice)(FIELD *, const void *));
-.br
-FIELDTYPE *link_fieldtype(FIELDTYPE *type1,
- FIELDTYPE *type2);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBFIELDTYPE *new_fieldtype(
+ \fBbool (* const \fIfield_check\fB)(FIELD *, const void *),\fR
+ \fBbool (* const \fIchar_check\fB)(int, const void *));\fR
+\fBint free_fieldtype(FIELDTYPE *\fIfieldtype\fB);\fR
+.PP
+\fBint set_fieldtype_arg(\fP
+ \fBFIELDTYPE *\fIfieldtype\fB,\fR
+ \fBvoid *(* const \fImake_arg\fB)(va_list *),\fR
+ \fBvoid *(* const \fIcopy_arg\fB)(const void *),\fR
+ \fBvoid (* const \fIfree_arg\fB)(void *));\fR
+\fBint set_fieldtype_choice(\fP
+ \fBFIELDTYPE *\fIfieldtype\fB,\fR
+ \fBbool (* const \fInext_choice\fB)(FIELD *, const void *),\fR
+ \fBbool (* const \fIprev_choice\fB)(FIELD *, const void *));\fR
+.PP
+\fBFIELDTYPE *link_fieldtype(FIELDTYPE *\fItype1\fB,\fR
+ \fBFIELDTYPE *\fItype2\fB);\fR
+.fi
.SH DESCRIPTION
-The function \fBnew_fieldtype\fR creates a new field type usable for data
-validation. You supply it with \fIfield_check\fR, a predicate to check the
+.SS new_fieldtype
+The function \fBnew_fieldtype\fP creates a new field type usable for data
+validation.
+Its parameters are function pointers:
+.TP 5
+\fIfield_check\fP
+This function checks the
validity of an entered data string whenever the user attempts to leave a field.
+It has two arguments:
+.RS
+.bP
The (FIELD *) argument is passed in so the validation predicate can see the
-field's buffer, sizes and other attributes; the second argument is an
+field's buffer, sizes and other attributes.
+.bP
+The second argument is an
argument-block structure, about which more below.
+.RE
+.TP 5
+\fIchar_check\fP
+This function validates input characters as they are entered.
+The form library passes it the character to be checked
+and a pointer to an argument-block structure.
+.SS free_fieldtype
+The \fBfree_fieldtype\fP function
+frees the space allocated for a given validation type by \fBnew_fieldtype\fP.
+.SS set_fieldtype_arg
+The function \fBset_fieldtype_arg\fP associates
+three storage-management functions with a field type:
+.TP 5
+\fImake_arg\fP
+This function is automatically applied to the
+list of arguments you give \fBset_field_type\fP when attaching validation
+to a field.
+It stores the arguments in an allocated argument-block
+object which is used when validating input.
+.TP 5
+\fIcopy_arg\fP
+This function may be used by applications to copy argument-blocks.
+.TP 5
+\fIfree_arg\fP
+Frees an argument-block structure.
.PP
-You also supply \fBnew_fieldtype\fR with \fIchar_check\fR,
-a function to validate input characters as they are entered; it will be passed
-the character to be checked and a pointer to an argument-block structure.
-.PP
-The function \fBfree_fieldtype\fR frees the space allocated for a given
-validation type.
-.PP
-The function \fBset_fieldtype_arg\fR associates three storage-management functions
-with a field type.
-The \fImake_arg\fR function is automatically applied to the
-list of arguments you give \fBset_field_type\fR when attaching validation
-to a field; its job is to bundle these into an allocated argument-block
-object which can later be passed to validation predicated.
-The other two hook arguments should copy and free argument-block structures.
-They will be used by the forms-driver code.
-You must supply the \fImake_arg\fR function,
-the other two are optional, you may supply NULL for them.
-In this case it is assumed
-that \fImake_arg\fR does not allocate memory but simply loads the
+You must supply the \fImake_arg\fP function.
+The other two are optional: you may supply NULL for them.
+In this case, the form library assumes
+that \fImake_arg\fP does not allocate memory but simply loads the
argument into a single scalar value.
-.PP
-The function \fBlink_fieldtype\fR creates
-a new field type from the two given types.
-They are connected by an logical 'OR'.
-.PP
-The form driver requests \fBREQ_NEXT_CHOICE\fR and \fBREQ_PREV_CHOICE\fR assume
+.SS set_fieldtype_choice
+The form driver requests \fBREQ_NEXT_CHOICE\fP and \fBREQ_PREV_CHOICE\fP assume
that the possible values of a field form an ordered set, and provide the forms
user with a way to move through the set.
-The \fBset_fieldtype_choice\fR
+.PP
+The \fBset_fieldtype_choice\fP
function allows forms programmers to define successor and predecessor functions
for the field type.
These functions take the field pointer and an
argument-block structure as arguments.
+.SS link_fieldtype
+The function \fBlink_fieldtype\fP creates
+a new field type from the two given types.
+They are connected by an logical 'OR'.
.SH RETURN VALUE
The pointer-valued routines return NULL on error.
-They set errno according to their success:
+They set \fBerrno\fP according to their success:
.TP 5
.B E_OK
The routine succeeded.
@@ -124,19 +149,15 @@
The field is the current field.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBform\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
-.PP
-All of the \fB(char *)\fR arguments of these functions should actually be
-\fB(void *)\fR. The type has been left uncorrected for strict compatibility
-with System V.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X),
+\fB\%form_field_validation\fP(3X)
diff --git a/man/form_hook.3x b/man/form_hook.3x
index 2943b88..d93d8d8 100644
--- a/man/form_hook.3x
+++ b/man/form_hook.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2007,2010 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 *
@@ -27,68 +27,71 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_hook.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
-.TH form_hook 3X ""
+.\" $Id: form_hook.3x,v 1.37 2024/03/16 15:35:01 tom Exp $
+.TH form_hook 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBform_hook\fR \- set hooks for automatic invocation by applications
+\fBform_hook\fP \-
+set hooks for automatic invocation by applications
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-int set_field_init(FORM *form, Form_Hook func);
-.br
-Form_Hook field_init(const FORM *form);
-.br
-int set_field_term(FORM *form, Form_Hook func);
-.br
-Form_Hook field_term(const FORM *form);
-.br
-int set_form_init(FORM *form, Form_Hook func);
-.br
-Form_Hook form_init(const FORM *form);
-.br
-int set_form_term(FORM *form, Form_Hook func);
-.br
-Form_Hook form_term(const FORM *form);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBint set_field_init(FORM *\fIform\fP, Form_Hook \fIfunc\fP);
+\fBForm_Hook field_init(const FORM *\fIform\fP);
+.PP
+\fBint set_field_term(FORM *\fIform\fP, Form_Hook \fIfunc\fP);
+\fBForm_Hook field_term(const FORM *\fIform\fP);
+.PP
+\fBint set_form_init(FORM *\fIform\fP, Form_Hook \fIfunc\fP);
+\fBForm_Hook form_init(const FORM *\fIform\fP);
+.PP
+\fBint set_form_term(FORM *\fIform\fP, Form_Hook \fIfunc\fP);
+\fBForm_Hook form_term(const FORM *\fIform\fP);
+.fi
.SH DESCRIPTION
These functions make it possible to set hook functions to be called at various
-points in the automatic processing of input event codes by \fBform_driver\fR.
-.PP
-The function \fBset_field_init\fR sets a hook to be called at form-post time
-and each time the selected field changes (after the change). \fBfield_init\fR
-returns the current field init hook, if any (\fBNULL\fR if there is no such
+points in the automatic processing of input event codes by \fBform_driver\fP.
+.SS set_field_init
+sets a hook to be called at form-post time
+and each time the selected field changes (after the change).
+.SS field_init
+returns the current field init hook, if any (\fBNULL\fP if there is no such
hook).
-.PP
-The function \fBset_field_term\fR sets a hook to be called at form-unpost time
-and each time the selected field changes (before the change). \fBfield_term\fR
-returns the current field term hook, if any (\fBNULL\fR if there is no such
+.SS set_field_term
+sets a hook to be called at form-unpost time
+and each time the selected field changes (before the change).
+.SS field_term
+returns the current field term hook, if any (\fBNULL\fP if there is no such
hook).
-.PP
-The function \fBset_form_init\fR sets a hook to be called at form-post time and
-just after a page change once it is posted. \fBform_init\fR returns the
-current form init hook, if any (\fBNULL\fR if there is no such hook).
-.PP
-The function \fBset_form_term\fR sets a hook to be called at form-unpost time
-and just before a page change once it is posted. \fBform_init\fR
-returns the current form term hook, if any (\fBNULL\fR if there is no such
+.SS set_form_init
+sets a hook to be called at form-post time and
+just after a page change once it is posted.
+.SS form_init
+returns the current form init hook,
+if any (\fBNULL\fP if there is no such hook).
+.SS set_form_term
+sets a hook to be called at form-unpost time
+and just before a page change once it is posted.
+.SS form_term
+returns the current form term hook, if any (\fBNULL\fP if there is no such
hook).
.SH RETURN VALUE
-Routines that return pointers return \fBNULL\fR on error. Other routines
+Routines that return pointers return \fBNULL\fP on error.
+Other routines
return one of the following:
.TP 5
.B E_OK
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBform\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X)
diff --git a/man/form_new.3x b/man/form_new.3x
index b69f642..dc45e18 100644
--- a/man/form_new.3x
+++ b/man/form_new.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,26 +27,28 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_new.3x,v 1.9 2010/12/04 18:40:45 tom Exp $
-.TH form_new 3X ""
+.\" $Id: form_new.3x,v 1.32 2024/03/16 15:35:01 tom Exp $
+.TH form_new 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBform_new\fR \- create and destroy forms
+\fBnew_form\fP,
+\fBfree_form\fP \-
+create and destroy forms
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-FORM *new_form(FIELD **fields);
-.br
-int free_form(FORM *form);
-.br
-.SH DESCRIPTION
-The function \fBnew_form\fR creates a new form connected to a specified field
-pointer array (which must be \fBNULL\fR-terminated).
+.nf
+\fB#include <form.h>
.PP
-The function \fBfree_form\fR disconnects \fIform\fR from its field array
+\fBFORM *new_form(FIELD **\fIfields\fP);
+\fBint free_form(FORM *\fIform\fP);
+.fi
+.SH DESCRIPTION
+The function \fBnew_form\fP creates a new form connected to a specified field
+pointer array (which must be \fBNULL\fP-terminated).
+.PP
+The function \fBfree_form\fP disconnects \fIform\fP from its field array
and frees the storage allocated for the form.
.SH RETURN VALUE
-The function \fBnew_form\fR returns \fBNULL\fR on error.
-It sets errno according to the function's success:
+The function \fBnew_form\fP returns \fBNULL\fP on error.
+It sets \fBerrno\fP according to the function's success:
.TP 5
.B E_OK
The routine succeeded.
@@ -60,7 +62,7 @@
.B E_SYSTEM_ERROR
System error occurred, e.g., malloc failure.
.PP
-The function \fBfree_form\fR returns one of the following:
+The function \fBfree_form\fP returns one of the following:
.TP 5
.B E_OK
The routine succeeded.
@@ -70,14 +72,13 @@
.TP 5
.B E_POSTED
The form has already been posted.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBform\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X)
diff --git a/man/form_new_page.3x b/man/form_new_page.3x
index 635822d..c47a959 100644
--- a/man/form_new_page.3x
+++ b/man/form_new_page.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,45 +27,52 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_new_page.3x,v 1.10 2010/12/04 18:40:45 tom Exp $
-.TH form_new_page 3X ""
+.\" $Id: form_new_page.3x,v 1.34 2024/03/16 15:35:01 tom Exp $
+.TH form_new_page 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-\fBform_new_page\fR \- form pagination functions
+\fBset_new_page\fP,
+\fBnew_page\fP \-
+form pagination functions
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-int set_new_page(FIELD *field, bool new_page_flag);
-.br
-bool new_page(const FIELD *field);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBint set_new_page(FIELD *\fIfield\fP, bool \fInew_page_flag\fP);
+\fBbool new_page(const FIELD *\fIfield\fP);
+.fi
.SH DESCRIPTION
-The function \fBset_new_page\fR sets or resets a flag marking the given field
+The function \fBset_new_page\fP sets or resets a flag marking the given field
as the beginning of a new page on its form.
.PP
-The function \fBnew_page\fR is a predicate which tests if a given field marks
+The function \fBnew_page\fP is a predicate which tests if a given field marks
a page beginning on its form.
.SH RETURN VALUE
-The function \fBnew_page\fR returns \fBTRUE\fR or \fBFALSE\fR.
+The function \fBnew_page\fP returns \fBTRUE\fP or \fBFALSE\fP.
.PP
-The function \fBset_new_page\fR return one of the following:
+The function \fBset_new_page\fP returns one of the following:
.TP 5
.B E_OK
The routine succeeded.
.TP 5
-.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.TP 5
.B E_CONNECTED
The given field is already connected to a form.
-.SH SEE ALSO
-\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed
-descriptions of the entry points.
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X) and related pages whose names begin \*(``form_\*(''
+for detailed descriptions of the entry points.
diff --git a/man/form_opts.3x b/man/form_opts.3x
index f02cec6..74a36d2 100644
--- a/man/form_opts.3x
+++ b/man/form_opts.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,58 +27,60 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_opts.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
-.TH form_opts 3X ""
+.\" $Id: form_opts.3x,v 1.34 2024/03/16 15:35:01 tom Exp $
+.TH form_opts 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBform_opts\fR \- set and get form options
+\fBset_form_opts\fP,
+\fBform_opts_on\fP,
+\fBform_opts_off\fP,
+\fBform_opts\fP \-
+set and get form options
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-int set_form_opts(FORM *form, Field_Options opts);
-.br
-int form_opts_on(FORM *form, Field_Options opts);
-.br
-int form_opts_off(FORM *form, Field_Options opts);
-.br
-Field_Options form_opts(const FORM *form);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBint set_form_opts(FORM *\fIform\fP, Field_Options \fIopts\fP);
+\fBField_Options form_opts(const FORM *\fIform\fP);
+.PP
+\fBint form_opts_on(FORM *\fIform\fP, Field_Options \fIopts\fP);
+\fBint form_opts_off(FORM *\fIform\fP, Field_Options \fIopts\fP);
+.fi
.SH DESCRIPTION
-The function \fBset_form_opts\fR sets all the given form's option bits (form
+The function \fBset_form_opts\fP sets all the given form's option bits (form
option bits may be logically-OR'ed together).
.PP
-The function \fBform_opts_on\fR turns on the given option bits, and leaves
+The function \fBform_opts_on\fP turns on the given option bits, and leaves
others alone.
.PP
-The function \fBform_opts_off\fR turns off the given option bits, and leaves
+The function \fBform_opts_off\fP turns off the given option bits, and leaves
others alone.
.PP
-The function \fBform_opts\fR returns the form's current option bits.
+The function \fBform_opts\fP returns the form's current option bits.
.PP
The following options are defined (all are on by default):
.TP 5
O_NL_OVERLOAD
-Overload the \fBREQ_NEW_LINE\fR forms driver request so that calling it at the
+Overload the \fBREQ_NEW_LINE\fP forms driver request so that calling it at the
end of a field goes to the next field.
.TP 5
O_BS_OVERLOAD
-Overload the \fBREQ_DEL_PREV\fR forms driver request so that calling it at the
+Overload the \fBREQ_DEL_PREV\fP forms driver request so that calling it at the
beginning of a field goes to the previous field.
.SH RETURN VALUE
-Except for \fBform_opts\fR, each routine returns one of the following:
+Except for \fBform_opts\fP, each routine returns one of the following:
.TP 5
.B E_OK
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBform\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X)
diff --git a/man/form_page.3x b/man/form_page.3x
index 2211216..fa538c6 100644
--- a/man/form_page.3x
+++ b/man/form_page.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2016 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 *
@@ -27,37 +27,44 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_page.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
-.TH form_page 3X ""
+.\" $Id: form_page.3x,v 1.37 2024/03/16 15:35:01 tom Exp $
+.TH form_page 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBform_page\fR \- set and get form page number
+\fBform_page\fP \-
+set and get form page number
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-int set_current_field(FORM *form, FIELD *field);
-.br
-FIELD *current_field(const FORM *);
-.br
-int set_form_page(FORM *form, int n);
-.br
-int form_page(const FORM *form);
-.br
-int field_index(const FIELD *field);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBint set_current_field(FORM *\fIform\fP, FIELD *\fIfield\fP);
+\fBFIELD *current_field(const FORM *\fIform\fP);
+.PP
+\fBint unfocus_current_field(FORM *\fIform\fP);
+.PP
+\fBint set_form_page(FORM *\fIform\fP, int \fIn\fP);
+\fBint form_page(const FORM *\fIform\fP);
+.PP
+\fBint field_index(const FIELD *\fIfield\fP);
+.fi
.SH DESCRIPTION
-The function \fBset_current field\fR sets the current field of the given
-form; \fBcurrent_field\fR returns the current field of the given form.
+The function \fBset_current_field\fP sets the current field of the given
+form; \fBcurrent_field\fP returns the current field of the given form.
.PP
-The function \fBset_form_page\fR sets the form's page number (goes to page
-\fIn\fR of the form).
+The function \fBunfocus_current_field\fP removes the focus from the current
+field of the form.
+In such state, inquiries via \fBcurrent_field\fP shall return a NULL pointer.
.PP
-The function \fBform_page\fR returns the form's current page number.
+The function \fBset_form_page\fP sets the form's page number (goes to page
+\fIn\fP of the form).
.PP
-The function \fBfield_index\fR returns the index of the field in the
-field array of the form it is connected to. It returns \fBERR\fR if
+The function \fBform_page\fP returns the form's current page number.
+.PP
+The function \fBfield_index\fP returns the index of the field in the
+field array of the form it is connected to.
+It returns \fBERR\fP if
the argument is the null pointer or the field is not connected.
.SH RETURN VALUE
-Except for \fBform_page\fR, each routine returns one of the following:
+Except for \fBform_page\fP, each routine returns one of the following:
.TP 5
.B E_OK
The routine succeeded.
@@ -75,16 +82,17 @@
The form driver could not process the request.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBform\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
+.PP
+The \fBunfocus_current_field\fP function is an \fI\%ncurses\fP
+extension.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X)
diff --git a/man/form_post.3x b/man/form_post.3x
index 4799d9d..77e086e 100644
--- a/man/form_post.3x
+++ b/man/form_post.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" 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 *
.\" copy of this software and associated documentation files (the *
@@ -27,24 +27,27 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_post.3x,v 1.9 2010/12/04 18:40:45 tom Exp $
-.TH form_post 3X ""
+.\" $Id: form_post.3x,v 1.33 2024/03/16 15:35:01 tom Exp $
+.TH form_post 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBform_post\fR \- write or erase forms from associated subwindows
+\fBpost_form\fP,
+\fBunpost_form\fP \-
+write or erase forms from associated subwindows
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-int post_form(FORM *form);
-.br
-int unpost_form(FORM *form);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBint post_form(FORM *\fIform\fP);
+\fBint unpost_form(FORM *\fIform\fP);
+.fi
.SH DESCRIPTION
-The function \fBpost_form\fR displays a form to its associated subwindow. To
-trigger physical display of the subwindow, use \fBrefresh\fR or some equivalent
-\fBcurses\fR routine (the implicit \fBdoupdate\fR triggered by an \fBcurses\fR
+The function \fBpost_form\fP displays a form to its associated subwindow.
+To trigger physical display of the subwindow,
+use \fBrefresh\fP(3X) or some equivalent
+\fBcurses\fP routine (the implicit \fBdoupdate\fP triggered by an \fBcurses\fP
input request will do).
.PP
-The function \fBunpost_form\fR erases form from its associated subwindow.
+The function \fBunpost_form\fP erases form from its associated subwindow.
.SH RETURN VALUE
These routines return one of the following:
.TP 5
@@ -70,16 +73,14 @@
The form has already been posted.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBform\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X)
diff --git a/man/form_requestname.3x b/man/form_requestname.3x
index 4a4e7eb..4075ea7 100644
--- a/man/form_requestname.3x
+++ b/man/form_requestname.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,38 +27,40 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_requestname.3x,v 1.9 2010/12/04 18:40:45 tom Exp $
-.TH form_requestname 3X ""
+.\" $Id: form_requestname.3x,v 1.35 2024/03/16 15:35:01 tom Exp $
+.TH form_requestname 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBform_requestname\fR \- handle printable form request names
+\fBform_request_by_name\fP,
+\fBform_request_name\fP \-
+handle printable form request names
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-const char *form_request_name(int request);
-.br
-int form_request_by_name(const char *name);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBconst char *form_request_name(int \fIrequest\fP);
+\fBint form_request_by_name(const char *\fIname\fP);
+.fi
.SH DESCRIPTION
-The function \fBform_request_name\fR returns the printable name of a form
+The function \fBform_request_name\fP returns the printable name of a form
request code.
-.br
-The function \fBform_request_by_name\fR searches in the name-table for a request
-with the given name and returns its request code. Otherwise E_NO_MATCH is returned.
+The function \fBform_request_by_name\fP searches in the name-table for a request
+with the given name and returns its request code.
+Otherwise E_NO_MATCH is returned.
.SH RETURN VALUE
-\fBform_request_name\fR returns \fBNULL\fR on error and sets errno
-to \fBE_BAD_ARGUMENT\fR.
-.br
-\fBform_request_by_name\fR returns \fBE_NO_MATCH\fR on error.
-It does not set errno.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBform\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+\fBform_request_name\fP returns \fBNULL\fP on error and sets \fBerrno\fP
+to \fBE_BAD_ARGUMENT\fP.
+.PP
+\fBform_request_by_name\fP returns \fBE_NO_MATCH\fP on error.
+It does not set \fBerrno\fP.
.SH PORTABILITY
-These routines are specific to ncurses. They were not supported on
-Version 7, BSD or System V implementations. It is recommended that
+These 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 them be conditioned using NCURSES_VERSION.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X)
diff --git a/man/form_userptr.3x b/man/form_userptr.3x
index bd29b54..11c990c 100644
--- a/man/form_userptr.3x
+++ b/man/form_userptr.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,37 +27,38 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_userptr.3x,v 1.13 2010/12/04 18:40:45 tom Exp $
-.TH form_userptr 3X ""
+.\" $Id: form_userptr.3x,v 1.36 2024/03/16 15:35:01 tom Exp $
+.TH form_userptr 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBform_userptr\fR \- associate application data with a form item
+\fBset_form_userptr\fP,
+\fBform_userptr\fP \-
+associate application data with a form item
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-int set_form_userptr(FORM *form, void *userptr);
-.br
-void* form_userptr(const FORM *form);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBint set_form_userptr(FORM *\fIform\fP, void *\fIuserptr\fP);
+\fBvoid* form_userptr(const FORM *\fIform\fP);
+.fi
.SH DESCRIPTION
Every form and every form item has a field that can be used to hold
application-specific data (that is, the form-driver code leaves it alone).
These functions get and set the form user pointer field.
.SH RETURN VALUE
-The function \fBform_userptr\fR returns a pointer (which may be \fBNULL\fR).
-It does not set errno.
+The function \fBform_userptr\fP returns a pointer (which may be \fBNULL\fP).
+It does not set \fBerrno\fP.
.PP
-The function \fBset_form_userptr\fR returns \fBE_OK\fP (success).
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBform\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+The function \fBset_form_userptr\fP returns \fBE_OK\fP (success).
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.PP
The user pointer is a void pointer.
We chose not to leave it as a char pointer for SVr4 compatibility.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X)
diff --git a/man/form_variables.3x b/man/form_variables.3x
index f4af349..7b11a1a 100644
--- a/man/form_variables.3x
+++ b/man/form_variables.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2010,2013 Free Software Foundation, Inc. *
+.\" Copyright 2020-2023,2024 Thomas E. Dickey *
+.\" Copyright 2010-2013,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 *
@@ -26,37 +27,33 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_variables.3x,v 1.4 2013/06/22 17:58:32 tom Exp $
-.TH form_variables 3X ""
-.ds n 5
-.na
-.hy 0
+.\" $Id: form_variables.3x,v 1.18 2024/03/16 15:35:01 tom Exp $
+.TH form_variables 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBTYPE_ALNUM\fR,
-\fBTYPE_ALPHA\fR,
-\fBTYPE_ENUM\fR,
-\fBTYPE_INTEGER\fR,
-\fBTYPE_IPV4\fR,
-\fBTYPE_NUMERIC\fR,
-\fBTYPE_REGEXP\fR
-\- form system global variables
-.ad
-.hy
+\fB\%TYPE_ALNUM\fP,
+\fB\%TYPE_ALPHA\fP,
+\fB\%TYPE_ENUM\fP,
+\fB\%TYPE_INTEGER\fP,
+\fB\%TYPE_IPV4\fP,
+\fB\%TYPE_NUMERIC\fP,
+\fB\%TYPE_REGEXP\fP \-
+form system global variables
.SH SYNOPSIS
.nf
-\fB#include <form.h>\fR
+\fB#include <form.h>
.PP
-\fBFIELDTYPE * TYPE_ALNUM;\fR
-\fBFIELDTYPE * TYPE_ALPHA;\fR
-\fBFIELDTYPE * TYPE_ENUM;\fR
-\fBFIELDTYPE * TYPE_INTEGER;\fR
-\fBFIELDTYPE * TYPE_IPV4;\fR
-\fBFIELDTYPE * TYPE_NUMERIC;\fR
-\fBFIELDTYPE * TYPE_REGEXP;\fR
+\fBFIELDTYPE * TYPE_ALNUM;
+\fBFIELDTYPE * TYPE_ALPHA;
+\fBFIELDTYPE * TYPE_ENUM;
+\fBFIELDTYPE * TYPE_INTEGER;
+\fBFIELDTYPE * TYPE_IPV4;
+\fBFIELDTYPE * TYPE_NUMERIC;
+\fBFIELDTYPE * TYPE_REGEXP;
.fi
.SH DESCRIPTION
These are building blocks for the form library,
-defining fields that can be created using \fBset_fieldtype\fP(3X).
+defining fields that can be created using
+the \fBform_fieldtype\fP(3X) functions.
Each provides functions for field- and character-validation,
according to the given datatype.
.SS TYPE_ALNUM
@@ -77,4 +74,4 @@
The \fBTYPE_IPV4\fP variable is an extension not provided by older
implementations of the form library.
.SH SEE ALSO
-\fBform\fR(3X).
+\fB\%form\fP(3X)
diff --git a/man/form_win.3x b/man/form_win.3x
index 32af49b..4a75b29 100644
--- a/man/form_win.3x
+++ b/man/form_win.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2006,2010 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 *
@@ -27,46 +27,49 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_win.3x,v 1.13 2010/12/04 18:38:55 tom Exp $
-.TH form_win 3X ""
+.\" $Id: form_win.3x,v 1.35 2024/03/16 15:35:01 tom Exp $
+.TH form_win 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBform_win\fR \- make and break form window and subwindow associations
+\fBform_win\fP \-
+make and break form window and subwindow associations
.SH SYNOPSIS
-\fB#include <form.h>\fR
-.br
-int set_form_win(FORM *form, WINDOW *win);
-.br
-WINDOW *form_win(const FORM *form);
-.br
-int set_form_sub(FORM *form, WINDOW *sub);
-.br
-WINDOW *form_sub(const FORM *form);
-.br
-int scale_form(const FORM *form, int *rows, int *columns);
-.br
+.nf
+\fB#include <form.h>
+.PP
+\fBint set_form_win(FORM *\fIform\fP, WINDOW *\fIwin\fP);
+\fBWINDOW *form_win(const FORM *\fIform\fP);
+.PP
+\fBint set_form_sub(FORM *\fIform\fP, WINDOW *\fIsub\fP);
+\fBWINDOW *form_sub(const FORM *\fIform\fP);
+.PP
+\fBint scale_form(const FORM *\fIform\fP, int *\fIrows\fP, int *\fIcolumns\fP);
+.fi
.SH DESCRIPTION
-Every form has an associated pair of \fBcurses\fR windows. The form window
+Every form has an associated pair of \fBcurses\fP windows.
+The form window
displays any title and border associated with the window; the form subwindow
displays the items of the form that are currently available for selection.
.PP
-The first four functions get and set those windows. It is not necessary to set
-either window; by default, the driver code uses \fBstdscr\fR for both.
+The first four functions get and set those windows.
+It is not necessary to set
+either window; by default, the driver code uses \fBstdscr\fP for both.
.PP
-In the \fBset_\fR functions, window argument of \fBNULL\fR is treated as though
-it were \fBstsdcr\fR. A form argument of \fBNULL\fR is treated as a request
+In the \fBset_\fP functions, window argument of \fBNULL\fP is treated as though
+it were \fBstsdcr\fP. A form argument of \fBNULL\fP is treated as a request
to change the system default form window or subwindow.
.PP
-The function \fBscale_form\fR returns the minimum size required for the
-subwindow of \fIform\fR.
+The function \fBscale_form\fP returns the minimum size required for the
+subwindow of \fIform\fP.
.SH RETURN VALUE
-Routines that return pointers return \fBNULL\fR on error. Routines that return
+Routines that return pointers return \fBNULL\fP on error.
+Routines that return
an integer return one of the following error codes:
.TP 5
.B E_OK
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fP(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
@@ -76,16 +79,14 @@
.TP 5
.B E_NOT_CONNECTED
No items are connected to the form.
-.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_variables\fR(3X),
-\fBform\fR(3X).
-.SH NOTES
-The header file \fB<form.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V forms library. They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%curs_variables\fP(3X),
+\fB\%form\fP(3X)
diff --git a/man/infocmp.1m b/man/infocmp.1m
index 8a3fef2..5f92c96 100644
--- a/man/infocmp.1m
+++ b/man/infocmp.1m
@@ -1,6 +1,7 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2014,2015 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 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 *
@@ -27,109 +28,144 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: infocmp.1m,v 1.56 2015/05/23 20:50:00 tom Exp $
-.TH @INFOCMP@ 1M ""
-.ds n 5
+.\" $Id: infocmp.1m,v 1.109 2024/03/16 15:35:01 tom Exp $
+.TH @INFOCMP@ 1M 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.ds ' \(aq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.ie t .ds ' \(aq
+.el .ds ' '
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
+.
.ds d @TERMINFO@
.SH NAME
-\fB@INFOCMP@\fR \- compare or print out \fIterminfo\fR descriptions
+\fB@INFOCMP@\fP \-
+compare or print out \fIterminfo\fP descriptions
.SH SYNOPSIS
-\fB@INFOCMP@\fR [\fB\-\
+\fB@INFOCMP@\fP [\fB\-\
1\
+c\
C\
+d\
D\
+e\
E\
F\
+g\
G\
+i\
I\
K\
-L\
-T\
-U\
-V\
-c\
-d\
-e\
-g\
-i\
l\
+L\
n\
p\
q\
r\
t\
+T\
u\
+U\
+V\
+W\
x\
-\fR]
-.br
- [\fB\-v\fR \fIn\fR] [\fB\-s d\fR| \fBi\fR| \fBl\fR| \fBc\fR] [\fB\-R \fR\fBsubset\fR]
-.br
- [\fB\-w\fR\ \fIwidth\fR] [\fB\-A\fR\ \fIdirectory\fR] [\fB\-B\fR\ \fIdirectory\fR]
-.br
- [\fItermname\fR...]
+\fP]
+ [\fB\-v\fR \fIn\fR] [\fB\-s d\fR| \fBi\fR| \fBl\fR| \fBc\fR] [\fB\-Q\fR \fIn\fR] [\fB\-R \fBsubset\fR]
+ [\fB\-w\fP\ \fIwidth\fP] [\fB\-A\fP\ \fIdirectory\fP] [\fB\-B\fP\ \fIdirectory\fP]
+ [\fIterminal-type\fP ...]
.SH DESCRIPTION
-\fB@INFOCMP@\fR can be used to compare a binary \fBterminfo\fR entry with other
-terminfo entries, rewrite a \fBterminfo\fR description to take advantage of the
-\fBuse=\fR terminfo field, or print out a \fBterminfo\fR description from the
-binary file (\fBterm\fR) in a variety of formats.
-In all cases, the boolean
+\fB@INFOCMP@\fP can be used to compare a binary \fBterminfo\fP entry with other
+terminfo entries, rewrite a \fBterminfo\fP description to take advantage of the
+\fBuse=\fP terminfo field, or print out a \fBterminfo\fP description from the
+binary file (\fBterm\fP) in a variety of formats.
+In all cases, the Boolean
fields will be printed first, followed by the numeric fields, followed by the
string fields.
-.SS Default Options
-If no options are specified and zero or one \fItermnames\fR are specified, the
-\fB\-I\fR option will be assumed.
-If more than one \fItermname\fR is specified,
-the \fB\-d\fR option will be assumed.
-.SS Comparison Options [\-d] [\-c] [\-n]
-\fB@INFOCMP@\fR compares the \fBterminfo\fR description of the first terminal
-\fItermname\fR with each of the descriptions given by the entries for the other
-terminal's \fItermnames\fR.
+.SS "Default Options"
+If no options are specified and zero or one \fIterminal-types\fP are
+specified,
+the
+\fB\-I\fP option will be assumed.
+If more than one \fIterminal-type\fP is specified,
+the \fB\-d\fP option will be assumed.
+.SS "Comparison Options [\-d] [\-c] [\-n]"
+\fB@INFOCMP@\fP compares the \fBterminfo\fP description of the first terminal
+\fIterminal-type\fP with each of the descriptions given by the entries
+for the other terminal's \fIterminal-types\fP.
If a capability is defined for only one of the
-terminals, the value returned will depend on the type of the capability:
-\fBF\fR for boolean variables, \fB\-1\fR for integer variables, and \fBNULL\fR
-for string variables.
+terminals, the value returned depends on the type of the capability:
+.bP
+\fBF\fP for missing Boolean variables
+.bP
+\fBNULL\fP for missing integer or string variables
.PP
-The \fB\-d\fR option produces a list of each capability that is different
+Use the \fB\-q\fP option to show the distinction between
+\fIabsent\fP and \fIcancelled\fP capabilities.
+.PP
+These options produce a list which you can use to compare two
+or more terminal descriptions:
+.TP 5
+\fB\-d\fP
+produces a list of each capability that is \fIdifferent\fP
between two entries.
-This option is useful to show the difference between two
-entries, created by different people, for the same or similar terminals.
-.PP
-The \fB\-c\fR option produces a list of each capability that is common between
+Each item in the list shows \*(``:\*('' after the capability name,
+followed by the capability values, separated by a comma.
+.TP
+\fB\-c\fP
+produces a list of each capability that is \fIcommon\fP between
two or more entries.
-Capabilities that are not set are ignored.
-This option can be
-used as a quick check to see if the \fB\-u\fR option is worth using.
+Missing capabilities are ignored.
+Each item in the list shows \*(``=\*('' after the capability name,
+followed by the capability value.
+.IP
+The \fB\-u\fP option provides a related output,
+showing the first terminal description rewritten to use the second
+as a building block via the \*(``use=\*('' clause.
+.TP
+\fB\-n\fP
+produces a list of each capability that is in \fInone\fP of the given entries.
+Each item in the list shows \*(``!\*('' before the capability name.
+.IP
+Normally only the conventional capabilities are shown.
+Use the \fB\-x\fP option to add the BSD-compatibility
+capabilities (names prefixed with \*(``OT\*('').
+.IP
+If no \fIterminal-types\fP are given,
+\fB@INFOCMP@\fP uses the environment variable \fITERM\fP
+for each of the \fIterminal-types\fP.
+.SS "Source Listing Options [\-I] [\-L] [\-C] [\-r]"
+The \fB\-I\fP, \fB\-L\fP, and \fB\-C\fP options will produce
+a source listing for each terminal named.
.PP
-The \fB\-n\fR option produces a list of each capability that is in none of
-the given entries.
-If no \fItermnames\fR are given, the environment variable \fBTERM\fR
-will be used for both of the \fItermnames\fR.
-This can be used as a quick
-check to see if anything was left out of a description.
-.SS Source Listing Options [\-I] [\-L] [\-C] [\-r]
-The \fB\-I\fR, \fB\-L\fR, and \fB\-C\fR options will produce a source listing for
-each terminal named.
-.
.TS
-center tab(/) ;
-l l .
-\fB\-I\fR/use the \fBterminfo\fR names
-\fB\-L\fR/use the long C variable name listed in <\fBterm.h\fR>
-\fB\-C\fR/use the \fBtermcap\fR names
-\fB\-r\fR/when using \fB\-C\fR, put out all capabilities in \fBtermcap\fR form
-\fB\-K\fR/modifies the \fB\-C\fP option, improving BSD-compatibility.
+center;
+Lb L.
+\-I use \fIterminfo\fP capability codes
+\-L use \*(``long\*('' capability names
+\-C use \fItermcap\fP capability codes
+\-r with \fB\-C\fP, include nonstandard capabilities
+\-K with \fB\-C\fP, improve BSD compatibility
.TE
.PP
-If no \fItermnames\fR are given, the environment variable \fBTERM\fR will be
-used for the terminal name.
+If no \fIterminal-types\fP are given,
+the environment variable \fITERM\fP will be used for the terminal name.
.PP
-The source produced by the \fB\-C\fR option may be used directly as a
-\fBtermcap\fR entry, but not all parameterized strings can be changed to
-the \fBtermcap\fR format.
-\fB@INFOCMP@\fR will attempt to convert most of the
+The source produced by the \fB\-C\fP option may be used directly as a
+\fBtermcap\fP entry, but not all parameterized strings can be changed to
+the \fBtermcap\fP format.
+\fB@INFOCMP@\fP will attempt to convert most of the
parameterized information, and anything not converted will be plainly marked in
the output and commented out.
These should be edited by hand.
@@ -137,7 +173,7 @@
For best results when converting to \fBtermcap\fP format,
you should use both \fB\-C\fP and \fB\-r\fP.
Normally a termcap description is limited to 1023 bytes.
-@INFOCMP@ trims away less essential parts to make it fit.
+\fB@INFOCMP@\fP trims away less essential parts to make it fit.
If you are converting to one of the (rare) termcap implementations
which accept an unlimited size of termcap,
you may want to add the \fB\-T\fP option.
@@ -145,107 +181,119 @@
and trim excess whitespace (use the \fB\-0\fP option for that).
.PP
All padding information for strings will be collected together and placed
-at the beginning of the string where \fBtermcap\fR expects it.
+at the beginning of the string where \fBtermcap\fP expects it.
Mandatory
-padding (padding information with a trailing '/') will become optional.
+padding (padding information with a trailing \*(``/\*('') will become optional.
.PP
-All \fBtermcap\fR variables no longer supported by \fBterminfo\fR, but which
-are derivable from other \fBterminfo\fR variables, will be output.
+All \fBtermcap\fP variables no longer supported by \fBterminfo\fP, but which
+are derivable from other \fBterminfo\fP variables, will be output.
Not all
-\fBterminfo\fR capabilities will be translated; only those variables which were
-part of \fBtermcap\fR will normally be output.
-Specifying the \fB\-r\fR option
+\fBterminfo\fP capabilities will be translated; only those variables which were
+part of \fBtermcap\fP will normally be output.
+Specifying the \fB\-r\fP option
will take off this restriction, allowing all capabilities to be output in
-\fItermcap\fR form.
+\fItermcap\fP form.
Normally you would use both the \fB\-C\fP and \fB\-r\fP options.
The actual format used incorporates some improvements for escaped characters
from terminfo format.
-For a stricter BSD-compatible translation, use the \fB\-K\fR option
+For a stricter BSD-compatible translation, use the \fB\-K\fP option
rather than \fB\-C\fP.
.PP
Note that because padding is collected to the beginning of the capability, not
all capabilities are output.
Mandatory padding is not supported.
Because
-\fBtermcap\fR strings are not as flexible, it is not always possible to convert
-a \fBterminfo\fR string capability into an equivalent \fBtermcap\fR format.
-A subsequent conversion of the \fBtermcap\fR file back into \fBterminfo\fR format
-will not necessarily reproduce the original \fBterminfo\fR
-source.
+\fBtermcap\fP strings are not as flexible, it is not always possible to convert
+a \fBterminfo\fP string capability into an equivalent \fBtermcap\fP format.
+A subsequent conversion of the \fBtermcap\fP file
+back into \fBterminfo\fP format
+will not necessarily reproduce the original \fBterminfo\fP source.
.PP
-Some common \fBterminfo\fR parameter sequences, their \fBtermcap\fR
+Some common \fBterminfo\fP parameter sequences, their \fBtermcap\fP
equivalents, and some terminal types which commonly have such sequences, are:
-.
+.PP
.TS
-center tab(/) ;
-l c l
-l l l.
-\fBterminfo/termcap\fR/Representative Terminals
-=
-\fB%p1%c/%.\fR/adm
-\fB%p1%d/%d\fR/hp, ANSI standard, vt100
-\fB%p1%'x'%+%c/%+x\fR/concept
-\fB%i/%i\fRq/ANSI standard, vt100
-\fB%p1%?%'x'%>%t%p1%'y'%+%;/%>xy\fR/concept
-\fB%p2\fR is printed before \fB%p1/%r\fR/hp
+center;
+Lf(BI) Lf(BI) L
+Lb Lb L.
+terminfo termcap Terminal Types
+_
+.\" ansi-m cup (adm3a has other stuff in between, more like concept)
+%p1%c %. ansi\-m
+.\" ansi cub, vt100 cub
+%p1%d %d ansi, vt100
+.\" vt52 cup (via vt52-basic)
+%p1%\*' \*'%+%c %+x vt52
+.\" ansi cup, vt100 cup
+%i %iq ansi, vt100
+.\" annarbor4080 cup
+%p1%?%\*'x\*'%>%t%p1%\*'y\*'%+%; %>xy annarbor4080
+.\" hpgeneric cup
+%p2\fR\|.\|.\|.\|\fP%p1 %r hpgeneric
.TE
-.SS Use= Option [\-u]
-The \fB\-u\fR option produces a \fBterminfo\fR source description of the first
-terminal \fItermname\fR which is relative to the sum of the descriptions given
-by the entries for the other terminals \fItermnames\fR.
+.SS "Use= Option [\-u]"
+The \fB\-u\fP option produces a \fBterminfo\fP source description of the first
+terminal \fIterminal-type\fP which is relative to the sum of the
+descriptions given by the entries for the other \fIterminal-types\fP.
It does this by
-analyzing the differences between the first \fItermname\fR and the other
-\fItermnames\fR and producing a description with \fBuse=\fR fields for the
-other terminals.
+analyzing the differences between the first \fIterminal-types\fP and the
+other \fIterminal-types\fP and producing a description with \fBuse=\fP
+fields for the other terminals.
In this manner, it is possible to retrofit generic terminfo
entries into a terminal's description.
Or, if two similar terminals exist, but
were coded at different times or by different people so that each description
-is a full description, using \fB@INFOCMP@\fR will show what can be done to change
+is a full description, using \fB@INFOCMP@\fP
+will show what can be done to change
one description to be relative to the other.
.PP
-A capability will get printed with an at-sign (@) if it no longer exists in the
-first \fItermname\fR, but one of the other \fItermname\fR entries contains a
-value for it.
-A capability's value gets printed if the value in the first
-\fItermname\fR is not found in any of the other \fItermname\fR entries, or if
-the first of the other \fItermname\fR entries that has this capability gives a
-different value for the capability than that in the first \fItermname\fR.
+A capability will be printed with an at-sign (@) if it no longer exists in the
+first \fIterminal-type\fP,
+but one of the other \fIterminal-type\fP entries contains a value for
+it.
+A capability's value will be printed if the value in the first
+\fIterminal-type\fP is not found in any of the other \fIterminal-type\fP
+entries,
+or if the first of the other \fIterminal-type\fP entries that has this
+capability gives a different value for the capability than that in the
+first \fIterminal-type\fP.
.PP
-The order of the other \fItermname\fR entries is significant.
+The order of the other \fIterminal-type\fP entries is significant.
Since the
-terminfo compiler \fB@TIC@\fR does a left-to-right scan of the capabilities,
-specifying two \fBuse=\fR entries that contain differing entries for the same
+terminfo compiler \fB@TIC@\fP does a left-to-right scan of the capabilities,
+specifying two \fBuse=\fP entries that contain differing entries for the same
capabilities will produce different results depending on the order that the
entries are given in.
-\fB@INFOCMP@\fR will flag any such inconsistencies between
-the other \fItermname\fR entries as they are found.
+\fB@INFOCMP@\fP will flag any such inconsistencies between
+the other \fIterminal-type\fP entries as they are found.
.PP
-Alternatively, specifying a capability \fIafter\fR a \fBuse=\fR entry that
+Alternatively, specifying a capability \fIafter\fP a \fBuse=\fP entry that
contains that capability will cause the second specification to be ignored.
-Using \fB@INFOCMP@\fR to recreate a description can be a useful check to make
+Using \fB@INFOCMP@\fP to recreate a description can be a useful check to make
sure that everything was specified correctly in the original source
description.
.PP
Another error that does not cause incorrect compiled files, but will slow down
-the compilation time, is specifying extra \fBuse=\fR fields that are
+the compilation time, is specifying extra \fBuse=\fP fields that are
superfluous.
-\fB@INFOCMP@\fR will flag any other \fItermname use=\fR fields that
+\fB@INFOCMP@\fP will flag any other \fIterminal-type use=\fP fields that
were not needed.
-.SS Changing Databases [\-A \fIdirectory\fR] [\-B \fIdirectory\fR]
-Like other \fBncurses\fP utilities,
-@INFOCMP@ looks for the terminal descriptions in several places.
-You can use the \fBTERMINFO\fP and \fBTERMINFO_DIRS\fP environment variables
-to override the compiled-in default list of places to search
-(see \fBcurses\fP(3X) for details).
+.SS "Changing Databases [\-A \fIdirectory\fR] [\-B \fIdirectory\fR]"
+Like other \fI\%ncurses\fP utilities,
+\fB@INFOCMP@\fP looks for the terminal descriptions in several places.
+You can use the \fI\%TERMINFO\fP and \fI\%TERMINFO_DIRS\fP environment
+variables to override the compiled-in default list of places to search.
+See \fBcurses\fP(3X), as well as
+the \fIFetching Compiled Descriptions\fP section in \fBterminfo\fR(5).
.PP
-You can also use the options \fB\-A\fR
-and \fB\-B\fR to override the list of places to search
+You can also use the options \fB\-A\fP
+and \fB\-B\fP to override the list of places to search
when comparing terminal descriptions:
.bP
-The \fB\-A\fR option sets the location for the first \fItermname\fR
+The \fB\-A\fP option sets the location for the first \fIterminal-type\fP
.bP
-The \fB\-B\fR option sets the location for the other \fItermnames\fR.
+The \fB\-B\fP option sets the location for the other
+\fIterminal-types\fP.
.PP
Using these options, it is possible to
compare descriptions for a terminal with the same name located in two different
@@ -253,45 +301,47 @@
For instance,
you can use this feature for comparing descriptions for the same terminal
created by different people.
-.SS Other Options
+.SS "Other Options"
.TP 5
-\fB\-0\fR
+\fB\-0\fP
causes the fields to be printed on one line, without wrapping.
.TP 5
-\fB\-1\fR
+\fB\-1\fP
causes the fields to be printed out one to a line.
Otherwise,
the fields will be printed several to a line to a maximum width
of 60 characters.
.TP
-\fB\-a\fR
-tells \fB@INFOCMP@\fP to retain commented-out capabilities rather than discarding
-them.
+\fB\-a\fP
+tells \fB@INFOCMP@\fP to retain commented-out capabilities
+rather than discarding them.
Capabilities are commented by prefixing them with a period.
.TP
-\fB\-D\fR
-tells \fB@INFOCMP@\fP to print the database locations that it knows about, and exit.
+\fB\-D\fP
+tells \fB@INFOCMP@\fP to print the database locations that it knows about,
+and exit.
.TP 5
-\fB\-E\fR
+\fB\-E\fP
Dump the capabilities of the given terminal as tables, needed in
the C initializer for a
-TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fR).
+TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fP).
This option is useful for preparing versions of the curses library hardwired
for a given terminal type.
The tables are all declared static, and are named according to the type
and the name of the corresponding terminal entry.
.sp
-Before ncurses 5.0, the split between the \fB\-e\fP and \fB\-E\fP
-options was not needed; but support for extended names required making
-the arrays of terminal capabilities separate from the TERMTYPE structure.
+Before \fI\%ncurses\fP 5.0,
+the split between the \fB\-e\fP and \fB\-E\fP options was not needed;
+but support for extended names required making the arrays of terminal
+capabilities separate from the TERMTYPE structure.
.TP 5
-\fB\-e\fR
+\fB\-e\fP
Dump the capabilities of the given terminal as a C initializer for a
-TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fR).
+TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fP).
This option is useful for preparing versions of the curses library hardwired
for a given terminal type.
.TP 5
-\fB\-F\fR
+\fB\-F\fP
compare terminfo files.
This assumes that two following arguments are filenames.
The files are searched for pairwise matches between
@@ -303,23 +353,23 @@
Normally,
to reduce the volume of the report, use references are
not resolved before looking for differences, but resolution can be forced
-by also specifying \fB\-r\fR.
+by also specifying \fB\-r\fP.
.TP 5
-\fB\-f\fR
+\fB\-f\fP
Display complex terminfo strings which contain if/then/else/endif expressions
indented for readability.
.TP 5
-\fB\-G\fR
+\fB\-G\fP
Display constant literals in decimal form
rather than their character equivalents.
.TP 5
-\fB\-g\fR
+\fB\-g\fP
Display constant character literals in quoted form
rather than their decimal equivalents.
.TP 5
-\fB\-i\fR
-Analyze the initialization (\fBis1\fR, \fBis2\fR, \fBis3\fR), and reset
-(\fBrs1\fR, \fBrs2\fR, \fBrs3\fR), strings in the entry,
+\fB\-i\fP
+Analyze the initialization (\fBis1\fP, \fBis2\fP, \fBis3\fP), and reset
+(\fBrs1\fP, \fBrs2\fP, \fBrs3\fP), strings in the entry,
as well as those used for starting/stopping cursor-positioning mode
(\fBsmcup\fP, \fBrmcup\fP) as well as starting/stopping keymap mode
(\fBsmkx\fP, \fBrmkx\fP).
@@ -336,177 +386,282 @@
.IP
Here is a list of the DEC/ANSI
special sequences recognized:
+.PP
.TS
-center tab(/) ;
-l l
-l l.
-Action/Meaning
-=
-RIS/full reset
-SC/save cursor
-RC/restore cursor
-LL/home-down
-RSR/reset scroll region
-=
-DECSTR/soft reset (VT320)
-S7C1T/7-bit controls (VT220)
-=
-ISO DEC G0/enable DEC graphics for G0
-ISO UK G0/enable UK chars for G0
-ISO US G0/enable US chars for G0
-ISO DEC G1/enable DEC graphics for G1
-ISO UK G1/enable UK chars for G1
-ISO US G1/enable US chars for G1
-=
-DECPAM/application keypad mode
-DECPNM/normal keypad mode
-DECANSI/enter ANSI mode
-=
-ECMA[+\-]AM/keyboard action mode
-ECMA[+\-]IRM/insert replace mode
-ECMA[+\-]SRM/send receive mode
-ECMA[+\-]LNM/linefeed mode
-=
-DEC[+\-]CKM/application cursor keys
-DEC[+\-]ANM/set VT52 mode
-DEC[+\-]COLM/132-column mode
-DEC[+\-]SCLM/smooth scroll
-DEC[+\-]SCNM/reverse video mode
-DEC[+\-]OM/origin mode
-DEC[+\-]AWM/wraparound mode
-DEC[+\-]ARM/auto-repeat mode
+center;
+L L.
+Action Meaning
+_
+RIS full reset
+SC save cursor
+RC restore cursor
+LL home-down
+RSR reset scroll region
+_
+DECSTR soft reset (VT320)
+S7C1T 7-bit controls (VT220)
+_
+ISO DEC G0 enable DEC graphics for G0
+ISO UK G0 enable UK chars for G0
+ISO US G0 enable US chars for G0
+ISO DEC G1 enable DEC graphics for G1
+ISO UK G1 enable UK chars for G1
+ISO US G1 enable US chars for G1
+_
+DECPAM application keypad mode
+DECPNM normal keypad mode
+DECANSI enter ANSI mode
+_
+ECMA[+\-]AM keyboard action mode
+ECMA[+\-]IRM insert replace mode
+ECMA[+\-]SRM send receive mode
+ECMA[+\-]LNM linefeed mode
+_
+DEC[+\-]CKM application cursor keys
+DEC[+\-]ANM set VT52 mode
+DEC[+\-]COLM 132-column mode
+DEC[+\-]SCLM smooth scroll
+DEC[+\-]SCNM reverse video mode
+DEC[+\-]OM origin mode
+DEC[+\-]AWM wraparound mode
+DEC[+\-]ARM auto-repeat mode
.TE
.sp
It also recognizes a SGR action corresponding to ANSI/ISO 6429/ECMA Set
Graphics Rendition, with the values NORMAL, BOLD, UNDERLINE, BLINK, and
REVERSE.
-All but NORMAL may be prefixed with `+' (turn on) or `\-' (turn off).
+All but NORMAL may be prefixed with
+.RS
+.bP
+\*(``+\*('' (turn on) or
+.bP
+\*(``\-\*('' (turn off).
+.RE
.IP
An SGR0 designates an empty highlight sequence (equivalent to {SGR:NORMAL}).
.TP 5
-\fB\-l\fR
+\fB\-l\fP
Set output format to terminfo.
.TP 5
-\fB\-p\fR
+\fB\-p\fP
Ignore padding specifications when comparing strings.
.TP 5
-\fB\-q\fR
-Make the comparison listing shorter by omitting subheadings, and using
-"\-" for absent capabilities, "@" for canceled rather than "NULL".
+\fB\-Q\fP \fIn\fP
+Rather than show source in terminfo (text) format,
+print the compiled (binary) format in hexadecimal or base64 form,
+depending on the option's value:
+.RS 8
+.TP 3
+1
+hexadecimal
+.TP 3
+2
+base64
+.TP 3
+3
+hexadecimal and base64
+.RE
+.IP
+For example, this prints the compiled terminfo value as a string
+which could be assigned to the \fI\%TERMINFO\fP environment variable:
+.PP
+.RS 9
+.EX
+@INFOCMP@ \-0 \-q \-Q2
+.EE
+.RE
.TP 5
-\fB\-R\fR\fIsubset\fR
+\fB\-q\fP
+This makes the output a little shorter:
+.RS
+.bP
+Make the comparison listing shorter by omitting subheadings, and using
+\*(``\-\*('' for absent capabilities, \*(``@\*(''
+for canceled rather than \*(``NULL\*(''.
+.bP
+However, show differences between absent and cancelled capabilities.
+.bP
+Omit the \*(``Reconstructed from\*('' comment for source listings.
+.RE
+.TP 5
+\fB\-R\fIsubset\fR
Restrict output to a given subset.
This option is for use with archaic
-versions of terminfo like those on SVr1, Ultrix, or HP/UX that do not support
+versions of terminfo like those on SVr1, Ultrix, or HP-UX that do not support
the full set of SVR4/XSI Curses terminfo; and variants such as AIX
that have their own extensions incompatible with SVr4/XSI.
-.IP
+.RS
+.bP
Available terminfo
-subsets are "SVr1", "Ultrix", "HP", and "AIX"; see \fBterminfo\fR(\*n) for
-details.
-You can also choose the subset "BSD" which selects only capabilities
+subsets are \*(``SVr1\*('', \*(``Ultrix\*('', \*(``HP\*('', and \*(``AIX\*('';
+see \fBterminfo\fP(5) for details.
+.bP
+You can also choose the subset \*(``BSD\*('' which selects only capabilities
with termcap equivalents recognized by 4.4BSD.
+.bP
+If you select any other value for \fB\-R\fP,
+it is the same as no subset, i.e., all capabilities are used.
+.RE
+.IP
+A few options override the subset selected with \fB\-R\fP,
+if they are processed later in the command parameters:
+.RS
+.TP 5
+\fB\-C\fP
+sets the \*(``BSD\*('' subset as a side-effect.
+.TP 5
+\fB\-I\fP
+sets the subset to all capabilities.
+.TP 5
+\fB\-r\fP
+sets the subset to all capabilities.
+.RE
.TP
-\fB\-s \fR\fI[d|i|l|c]\fR
-The \fB\-s\fR option sorts the fields within each type according to the argument
+\fB\-s \fI[d|i|l|c]\fR
+The \fB\-s\fP option sorts the fields within each type according to the argument
below:
.br
.RS 5
.TP 5
-\fBd\fR
-leave fields in the order that they are stored in the \fIterminfo\fR database.
+\fBd\fP
+leave fields in the order that they are stored in the \fIterminfo\fP database.
.TP 5
-\fBi\fR
-sort by \fIterminfo\fR name.
+\fBi\fP
+sort by \fIterminfo\fP name.
.TP 5
-\fBl\fR
+\fBl\fP
sort by the long C variable name.
.TP 5
-\fBc\fR
-sort by the \fItermcap\fR name.
+\fBc\fP
+sort by the \fItermcap\fP name.
.RE
.IP
-If the \fB\-s\fR option is not given, the fields printed out will be
-sorted alphabetically by the \fBterminfo\fR name within each type,
-except in the case of the \fB\-C\fR or the \fB\-L\fR options, which cause the
-sorting to be done by the \fBtermcap\fR name or the long C variable
+If the \fB\-s\fP option is not given, the fields printed out will be
+sorted alphabetically by the \fBterminfo\fP name within each type,
+except in the case of the \fB\-C\fP or the \fB\-L\fP options, which cause the
+sorting to be done by the \fBtermcap\fP name or the long C variable
name, respectively.
.TP 5
-\fB\-T\fR
+\fB\-T\fP
eliminates size-restrictions on the generated text.
This is mainly useful for testing and analysis, since the compiled
descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
.TP
-\fB\-t\fR
+\fB\-t\fP
tells \fB@TIC@\fP to discard commented-out capabilities.
Normally when translating from terminfo to termcap,
untranslatable capabilities are commented-out.
.TP 5
-\fB\-U\fR
-tells \fB@INFOCMP@\fP to not post-process the data after parsing the source file.
+\fB\-U\fP
+tells \fB@INFOCMP@\fP to not post-process the data
+after parsing the source file.
This feature helps when comparing the actual contents of two source files,
since it excludes the inferences that \fB@INFOCMP@\fP makes to fill in missing
data.
.TP 5
-\fB\-V\fR
-reports the version of ncurses which was used in this program, and exits.
+\fB\-V\fP
+reports the version of \fI\%ncurses\fP which was used in this program,
+and exits.
.TP 5
-\fB\-v\fR \fIn\fR
+\fB\-v\fP \fIn\fP
prints out tracing information on standard error as the program runs.
-Higher values of n induce greater verbosity.
-.TP 5
-\fB\-w\fR \fIwidth\fR
-changes the output to \fIwidth\fR characters.
+.IP
+The optional parameter \fIn\fP is a number from 1 to 10, inclusive,
+indicating the desired level of detail of information.
+If \fI\%ncurses\fP is built without tracing support,
+the optional parameter is ignored.
.TP
-\fB\-x\fR
-print information for user-defined capabilities.
+\fB\-W\fP
+By itself, the \fB\-w\fP option will not force long strings to be wrapped.
+Use the \fB\-W\fP option to do this.
+.TP 5
+\fB\-w\fP \fIwidth\fP
+changes the output to \fIwidth\fP characters.
+.TP
+\fB\-x\fP
+print information for user-defined capabilities (see \fBuser_caps\fP(5).
These are extensions to the terminfo repertoire which can be loaded
-using the \fB\-x\fR option of \fB@TIC@\fP.
+using the \fB\-x\fP option of \fB@TIC@\fP.
.SH FILES
-.TP 20
-\*d
-Compiled terminal description database.
+.TP
+.I \*d
+compiled terminal description database
.SH EXTENSIONS
The
-\fB\-0\fR,
-\fB\-1\fR,
-\fB\-E\fR,
-\fB\-F\fR,
-\fB\-G\fR,
-\fB\-R\fR,
-\fB\-T\fR,
-\fB\-V\fR,
-\fB\-a\fR,
-\fB\-e\fR,
-\fB\-f\fR,
-\fB\-g\fR,
-\fB\-i\fR,
-\fB\-l\fR,
-\fB\-p\fR,
-\fB\-q\fR and
-\fB\-t\fR
+\fB\-0\fP,
+\fB\-1\fP,
+\fB\-E\fP,
+\fB\-F\fP,
+\fB\-G\fP,
+\fB\-Q\fP,
+\fB\-R\fP,
+\fB\-T\fP,
+\fB\-V\fP,
+\fB\-a\fP,
+\fB\-e\fP,
+\fB\-f\fP,
+\fB\-g\fP,
+\fB\-i\fP,
+\fB\-l\fP,
+\fB\-p\fP,
+\fB\-q\fP and
+\fB\-t\fP
options are not supported in SVr4 curses.
.PP
-The \fB\-r\fR option's notion of `termcap' capabilities is System V Release 4's.
+SVr4 infocmp does not distinguish between absent and cancelled capabilities.
+Also, it shows missing integer capabilities as \fB\-1\fP
+(the internal value used to represent missing integers).
+This implementation shows those as \*(``NULL\*('',
+for consistency with missing strings.
+.PP
+The \fB\-r\fP option's notion of \*(``termcap\*('' capabilities
+is System V Release 4's.
Actual BSD curses versions will have a more restricted set.
To see only the
-4.4BSD set, use \fB\-r\fR \fB\-RBSD\fR.
-.SH BUGS
-The \fB\-F\fR option of \fB@INFOCMP@\fR(1M) should be a \fB@TOE@\fR(1M) mode.
-.SH SEE ALSO
-\fB@CAPTOINFO@\fR(1M),
-\fB@INFOTOCAP@\fR(1M),
-\fB@TIC@\fR(1M),
-\fB@TOE@\fR(1M),
-\fBcurses\fR(3X),
-\fBterminfo\fR(\*n).
-.sp
-http://invisible-island.net/ncurses/tctest.html
+4.4BSD set, use \fB\-r\fP \fB\-RBSD\fP.
+.SH PORTABILITY
+X/Open Curses, Issue 7 (2009) provides a description of \fBinfocmp\fP.
+It does not mention the options used for converting to termcap format.
+.SH HISTORY
+Although System V Release 2 provided a terminfo library,
+it had no documented tool for decompiling the terminal descriptions.
+Tony Hansen (AT&T) wrote the first \fBinfocmp\fP in early 1984,
+for System V Release 3.
.PP
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
-.SH AUTHOR
+Eric Raymond used the AT&T documentation in 1995 to provide an equivalent
+\fB@INFOCMP@\fP for \fI\%ncurses\fP.
+In addition, he added a few new features such as:
+.bP
+the \fB\-e\fP option, to support \fIfallback\fP
+(compiled-in) terminal descriptions
+.bP
+the \fB\-i\fP option, to help with analysis
+.PP
+Later, Thomas Dickey added the \fB\-x\fP (user-defined capabilities)
+option, and the \fB\-E\fP option to support fallback entries with
+user-defined capabilities.
+.PP
+For a complete list, see the \fIEXTENSIONS\fP section.
+.PP
+In 2010, Roy Marples provided an \fBinfocmp\fP program for NetBSD.
+It is less capable than the SVr4 or \fI\%ncurses\fP versions
+(e.g., it lacks the sorting options documented in X/Open),
+but does include the \fB\-x\fP option adapted from \fI\%ncurses\fP.
+.SH BUGS
+The \fB\-F\fP option of \fB\%@INFOCMP@\fP(1M) should be a
+\fB\%@TOE@\fP(1M) mode.
+.SH AUTHORS
Eric S. Raymond <esr@snark.thyrsus.com>
and
.br
-Thomas E. Dickey <dickey@invisible-island.net>
+Thomas E. Dickey <dickey@invisible\-island.net>
+.SH SEE ALSO
+\fB\%@CAPTOINFO@\fP(1M),
+\fB\%@INFOTOCAP@\fP(1M),
+\fB\%@TIC@\fP(1M),
+\fB\%@TOE@\fP(1M),
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(5),
+\fB\%user_caps\fP(5)
+.PP
+https://invisible\-island.net/ncurses/tctest.html
diff --git a/man/infotocap.1m b/man/infotocap.1m
index d9b44f0..0f0335d 100644
--- a/man/infotocap.1m
+++ b/man/infotocap.1m
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1999-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1999-2010,2016 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 *
@@ -27,52 +27,71 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: infotocap.1m,v 1.11 2010/12/04 18:38:55 tom Exp $
-.TH @INFOTOCAP@ 1M ""
-.ds n 5
+.\" $Id: infotocap.1m,v 1.41 2024/03/16 15:35:01 tom Exp $
+.TH @INFOTOCAP@ 1M 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.ds d @TERMINFO@
.SH NAME
-\fB@INFOTOCAP@\fR \- convert a \fIterminfo\fR description into a \fItermcap\fR description
+\fB\%@INFOTOCAP@\fP \-
+convert a \fI\%terminfo\fR description into a \fI\%termcap\fR description
.SH SYNOPSIS
-\fB@INFOTOCAP@\fR [\fB\-v\fR\fIn\fR \fIwidth\fR] [\fB\-V\fR] [\fB\-1\fR] [\fB\-w\fR \fIwidth\fR] \fIfile\fR . . .
+.B @INFOTOCAP@
+.RI [ tic-option ]
+.I file
+\&.\|.\|.
+.P
+.B "@INFOTOCAP@ \-V"
.SH DESCRIPTION
-\fB@INFOTOCAP@\fR looks in each given text
-\fIfile\fR for \fBterminfo\fR descriptions.
-For each terminfo description found,
-an equivalent \fBtermcap\fR description is written to standard output.
-Terminfo \fBuse\fR capabilities are translated directly to termcap
-\fBtc\fR capabilities.
-.TP 5
-\fB\-v\fR
-print out tracing information on standard error as the program runs.
-.TP 5
-\fB\-V\fR
-print out the version of the program in use on standard error and exit.
-.TP 5
-\fB\-1\fR
-cause the fields to print out one to a line.
-Otherwise, the fields
-will be printed several to a line to a maximum width of 60 characters.
-.TP 5
-\fB\-w\fR
-change the output to \fIwidth\fR characters.
-.SH FILES
-.TP 20
-\*d
-Compiled terminal description database.
-.SH NOTES
-This utility is actually a link to \fI@TIC@\fR, running in \fI\-C\fR mode.
-You can use other \fI@TIC@\fR options such as \fB\-f\fR and \fB\-x\fR.
-.SH SEE ALSO
-\fBcurses\fR(3X),
-\fB@TIC@\fR(1M),
-\fB@INFOCMP@\fR(1M),
-\fBterminfo\fR(\*n)
+\fB\%@INFOTOCAP@\fP translates terminal descriptions.
+It looks in each given text \fIfile\fP for \fI\%terminfo\fP entries and,
+For each one found,
+it writes an analogous \fI\%termcap\fP description to the standard
+output stream.
+\fI\%terminfo\fP \*(``\fBuse\fP\*('' capabilities translate to
+\fI\%termcap\fP \fBtc\fP capabilities.
+Because \fI\%termcap\fP is a less expressive format than
+\fI\%terminfo\fP,
+some capabilities cannot be translated.
.PP
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
-.SH AUTHOR
+This utility is implemented as a link to \fB\%@TIC@\fP(1M),
+with the latter's
+.B \-C
+option implied.
+You can use other \fB\%@TIC@\fP options such as
+.BR \-1 ,
+.BR \-f ,
+.BR \-v ,
+.BR \-w ,
+and
+.BR \-x .
+The \fB\-V\fP option reports the version of \fI\%ncurses\fP associated
+with this program and exits with a successful status.
+.SH FILES
+.TP
+.I \*d
+compiled terminal description database
+.SH PORTABILITY
+None of X/Open Curses,
+Issue 7 (2009),
+SVr4,
+or NetBSD document this application.
+.SH AUTHORS
Eric S. Raymond <esr@snark.thyrsus.com>
and
.br
-Thomas E. Dickey <dickey@invisible-island.net>
+Thomas E. Dickey <dickey@invisible\-island.net>
+.SH SEE ALSO
+\fB\%@INFOCMP@\fP(1M),
+\fB\%@TIC@\fP(1M),
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(5)
diff --git a/man/key_defined.3x b/man/key_defined.3x
index db6c531..f0184aa 100644
--- a/man/key_defined.3x
+++ b/man/key_defined.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2003-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 2003-2006,2010 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 *
@@ -28,27 +29,33 @@
.\"
.\" Author: Thomas E. Dickey 2003
.\"
-.\" $Id: key_defined.3x,v 1.6 2010/12/04 18:40:45 tom Exp $
-.TH key_defined 3X ""
+.\" $Id: key_defined.3x,v 1.34 2024/03/16 15:35:01 tom Exp $
+.TH key_defined 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBkey_defined\fP \- check if a keycode is defined
+\fB\%key_defined\fP \-
+test whether a \fIcurses\fR keycode is defined
.SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-\fBint key_defined(const char *definition);\fP
+.nf
+\fB#include <curses.h>
+.PP
+\fBint key_defined(const char *\fIdefinition\fP);
+.fi
.SH DESCRIPTION
-This is an extension to the curses library.
+This is an extension to the \fIcurses\fP library.
It permits an application to determine if a string is currently bound
to any keycode.
.SH RETURN VALUE
If the string is bound to a keycode, its value (greater than zero) is returned.
If no keycode is bound, zero is returned.
-If the string conflicts with longer strings which are bound to keys, \-1 is returned.
+If the string conflicts with longer strings
+which are bound to keys, \-1 is returned.
.SH PORTABILITY
-These routines are specific to ncurses. They were not supported on
-Version 7, BSD or System V implementations. It is recommended that
-any code depending on them be conditioned using NCURSES_VERSION.
+This routine is specific to \fI\%ncurses\fP.
+It was not supported on
+Version 7, BSD or System V implementations.
+It is recommended that
+any code depending on them be conditioned using \fB\%NCURSES_VERSION\fP.
+.SH AUTHORS
+Thomas Dickey
.SH SEE ALSO
-\fBdefine_key\fR(3X).
-.SH AUTHOR
-Thomas Dickey.
+\fB\%define_key\fP(3X)
diff --git a/man/keybound.3x b/man/keybound.3x
index 5dd083a..bd8bb80 100644
--- a/man/keybound.3x
+++ b/man/keybound.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1999-2008,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1999-2008,2010 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 *
@@ -28,31 +29,37 @@
.\"
.\" Author: Thomas E. Dickey 1999
.\"
-.\" $Id: keybound.3x,v 1.8 2010/12/04 18:49:20 tom Exp $
-.TH keybound 3X ""
+.\" $Id: keybound.3x,v 1.36 2024/03/16 15:35:01 tom Exp $
+.TH keybound 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBkeybound\fP \- return definition of keycode
+\fB\%keybound\fP \-
+get definition of \fIcurses\fR keycode
.SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-\fBchar * keybound(int keycode, int count);\fP
+.nf
+\fB#include <curses.h>
+.PP
+\fBchar * keybound(int \fIkeycode\fP, int \fIcount\fP);
+.fi
.SH DESCRIPTION
-This is an extension to the curses library.
+This is an extension to the \fIcurses\fP library.
It permits an application to determine the string which is defined
in the terminfo for specific keycodes.
.SH RETURN VALUE
-The \fIkeycode\fP parameter must be greater than zero, else NULL is returned.
-If it does not correspond to a defined key, then NULL is returned.
+The \fIkeycode\fP parameter must be greater than zero,
+else \fBNULL\fP is returned.
+If it does not correspond to a defined key, then \fBNULL\fP is returned.
The \fIcount\fP parameter is used to allow the application to iterate
through multiple definitions, counting from zero.
When successful,
the function returns a string which must be freed by the caller.
.SH PORTABILITY
-These routines are specific to ncurses. They were not supported on
-Version 7, BSD or System V implementations. It is recommended that
-any code depending on them be conditioned using NCURSES_VERSION.
+This routine is specific to \fI\%ncurses\fP.
+It was not supported on
+Version 7, BSD or System V implementations.
+It is recommended that
+any code depending on them be conditioned using \fB\%NCURSES_VERSION\fP.
+.SH AUTHORS
+Thomas Dickey
.SH SEE ALSO
-\fBdefine_key\fR(3X),
-\fBkeyok\fR(3X).
-.SH AUTHOR
-Thomas Dickey.
+\fB\%define_key\fP(3X),
+\fB\%keyok\fP(3X)
diff --git a/man/keyok.3x b/man/keyok.3x
index 8eaf9a3..b4c7de2 100644
--- a/man/keyok.3x
+++ b/man/keyok.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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 *
@@ -28,30 +29,35 @@
.\"
.\" Author: Thomas E. Dickey 1997
.\"
-.\" $Id: keyok.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
-.TH keyok 3X ""
+.\" $Id: keyok.3x,v 1.40 2024/03/16 15:35:01 tom Exp $
+.TH keyok 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBkeyok\fP \- enable or disable a keycode
+\fB\%keyok\fP \-
+enable or disable a \fIcurses\fR keycode
.SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-\fBint keyok(int keycode, bool enable);\fP
+.nf
+\fB#include <curses.h>
+.PP
+\fBint keyok(int \fIkeycode\fP, bool \fIenable\fP);
+.fi
.SH DESCRIPTION
-This is an extension to the curses library.
+This is an extension to the \fIcurses\fP library.
It permits an application to disable specific keycodes, rather than
-use the \fIkeypad\fP function to disable all keycodes.
+use the \fB\%keypad\fP function to disable all keycodes.
Keys that have been disabled can be re-enabled.
.SH RETURN VALUE
-The keycode must be greater than zero, else ERR is returned.
-If it does not correspond to a defined key, then ERR is returned.
+The keycode must be greater than zero, else \fBERR\fP is returned.
+If it does not correspond to a defined key, then \fBERR\fP is returned.
If the \fIenable\fP parameter is true, then the key must have been disabled,
and vice versa.
-Otherwise, the function returns OK.
+Otherwise, the function returns \fBOK\fP.
.SH PORTABILITY
-These routines are specific to ncurses. They were not supported on
-Version 7, BSD or System V implementations. It is recommended that
-any code depending on them be conditioned using NCURSES_VERSION.
+This routine is specific to \fI\%ncurses\fP.
+It was not supported on
+Version 7, BSD or System V implementations.
+It is recommended that
+any code depending on them be conditioned using \fB\%NCURSES_VERSION\fP.
+.SH AUTHORS
+Thomas Dickey
.SH SEE ALSO
-\fBdefine_key\fR(3X).
-.SH AUTHOR
-Thomas Dickey.
+\fB\%define_key\fP(3X)
diff --git a/man/legacy_coding.3x b/man/legacy_coding.3x
index fabb607..ccfdd55 100644
--- a/man/legacy_coding.3x
+++ b/man/legacy_coding.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2005-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2020-2023,2024 Thomas E. Dickey *
+.\" Copyright 2005-2016,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 *
@@ -28,49 +29,75 @@
.\"
.\" Author: Thomas E. Dickey
.\"
-.\" $Id: legacy_coding.3x,v 1.4 2010/12/04 18:49:20 tom Exp $
-.TH legacy_coding 3X ""
+.\" $Id: legacy_coding.3x,v 1.28 2024/04/20 19:13:50 tom Exp $
+.TH legacy_coding 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBuse_legacy_coding\fR \- use terminal's default colors
+\fB\%use_legacy_coding\fP \-
+override \fIcurses\fR locale encoding checks
.SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-\fBint use_legacy_coding(int level);\fP
-.SH DESCRIPTION
-The
-.I use_legacy_coding()
-function is an extension to the curses library.
-It allows the caller to change the result of \fBunctrl\fP,
-and suppress related checks within the library that would normally
-cause nonprinting characters to be rendered in visible form.
-This affects only 8-bit characters.
+.nf
+\fB#include <curses.h>
.PP
-The \fIlevel\fP parameter controls the result:
+\fBint use_legacy_coding(int \fIlevel\fP);
+.fi
+.SH DESCRIPTION
+.B \%use_legacy_coding
+is an extension to the
+.I curses
+library.
+It allows the caller to change the result of \fB\%unctrl\fP(3X),
+suppressing \fI\%isprint\fP(3)-based checks within the library that
+would normally cause nonprinting characters to be rendered in visible
+form.
+The alteration affects only eight-bit characters.
+.PP
+The
+.I level
+parameter controls the result.
.RS
.TP 5
-0
-the library functions normally,
-rendering nonprinting characters as described in \fBunctrl\fP.
+.B 0
+The library functions normally,
+rendering nonprinting characters as described in \fB\%unctrl\fP(3X),
.TP
-1
-the library ignores \fBisprintf\fP for codes in the range 160-255.
+.B 1
+the library ignores
+.I \%isprint
+for codes in the range 160-255.
.TP
-2
-the library ignores \fBisprintf\fP for codes in the range 128-255.
-It also modifies the output of \fBunctrl\fP, showing codes in the
-range 128-159 as is.
+.B 2
+the library ignores
+.I \%isprint
+for codes in the range 128-255.
+It also modifies the output of \fB\%unctrl\fP(3X),
+showing codes in the range 128-159 as is.
.RE
.SH RETURN VALUE
If the screen has not been initialized,
-or the \fIlevel\fP parameter is out of range,
-the function returns \fBERR\fP.
-Otherwise, it returns the previous level: \fB0\fP, \fB1\fP or \fB2\fP.
+or the
+.I level
+parameter is out of range,
+.B \%use_legacy_coding
+returns
+.BR ERR .
+Otherwise,
+it returns the previous level:
+.BR 0 ,
+.BR 1 ,
+or
+.BR 2 .
.SH PORTABILITY
-This routine is specific to ncurses.
+.B \%use_legacy_coding
+is specific to
+.IR \%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.
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
+.SH AUTHORS
+Thomas Dickey
+(to support \fI\%lynx\fP(1)'s font-switching feature).
.SH SEE ALSO
-\fBunctrl\fR.
-.SH AUTHOR
-Thomas Dickey (to support lynx's font-switching feature).
+\fB\%unctrl\fP(3X)
diff --git a/man/make_sed.sh b/man/make_sed.sh
index f2afac9..ee7df41 100755
--- a/man/make_sed.sh
+++ b/man/make_sed.sh
@@ -1,7 +1,8 @@
#!/bin/sh
-# $Id: make_sed.sh,v 1.9 2005/07/16 18:15:31 tom Exp $
+# $Id: make_sed.sh,v 1.19 2023/12/07 01:16:43 tom Exp $
##############################################################################
-# Copyright (c) 1998-2003,2005 Free Software Foundation, Inc. #
+# Copyright 2020-2022,2023 Thomas E. Dickey #
+# Copyright 1998-2005,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 "Software"), #
@@ -28,7 +29,7 @@
# authorization. #
##############################################################################
#
-# Author: Thomas E. Dickey 1997-2005
+# Author: Thomas E. Dickey 1997
#
# Construct a sed-script to perform renaming within man-pages. Originally
# written in much simpler form, this one accounts for the common cases of
@@ -45,8 +46,9 @@
SCRIPT=script$$
RESULT=result$$
rm -f $UPPER $SCRIPT $RESULT
-trap "rm -f $COL.* $INPUT $UPPER $SCRIPT $RESULT" 0 1 2 5 15
-fgrep -v \# $1 | \
+trap "rm -f $COL.* $INPUT $UPPER $SCRIPT $RESULT; exit 1" 1 2 3 15
+trap "rm -f $COL.* $INPUT $UPPER $SCRIPT $RESULT" 0
+${FGREP-grep -F} -v \# "$1" | \
sed -e 's/[ ][ ]*/ /g' >$INPUT
for F in 1 2 3 4
@@ -57,33 +59,37 @@
for F in 2 4
do
tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ <$COL.$F >$UPPER
- mv $UPPER $COL.$F
+ mv $UPPER $COL.$F
done
paste $COL.* | \
sed -e 's/^/s\/\\</' \
-e 's/$/\//' >$UPPER
-echo "# Do the TH lines" >>$RESULT
+{
+echo "# This script was generated from '$1' by man/make_sed.sh."
+echo "# Do the TH lines"
sed -e 's/\//\/TH /' \
-e 's/ / /' \
- -e 's/ / ""\/TH /' \
+ -e 's/ / \/TH /' \
-e 's/ / /' \
- -e 's/\/$/ ""\//' \
- $UPPER >>$RESULT
+ -e 's/\/$/ \//' \
+ $UPPER
-echo "# Do the embedded references" >>$RESULT
-sed -e 's/</<fB/' \
- -e 's/ /\\\\fR(/' \
- -e 's/ /)\/fB/' \
- -e 's/ /\\\\fR(/' \
+echo "# Do the embedded references"
+sed -e 's/</<fB\\(\\\\%\\)\\?/' \
+ -e 's/\\%</\\%/' \
+ -e 's/ /\\\\fP(/' \
+ -e 's/ /)\/fB\\\\%/' \
+ -e 's/ /\\\\fP(/' \
-e 's/\/$/)\//' \
- $UPPER >>$RESULT
+ $UPPER
-echo "# Do the \fBxxx\fR references in the .NAME section" >>$RESULT
+echo '# Do the \\fBxxx\\fP references in the .NAME section'
sed -e 's/\\</^\\\\fB/' \
-e 's/ [^ ]* /\\\\f[RP] -\/\\\\fB/' \
- -e 's/ .*$/\\\\fR -\//' \
- $UPPER >>$RESULT
+ -e 's/ .*$/\\\\fP -\//' \
+ $UPPER
+} >>$RESULT
# Finally, send the result to standard output
cat $RESULT
diff --git a/man/man_db.renames b/man/man_db.renames.in
similarity index 60%
rename from man/man_db.renames
rename to man/man_db.renames.in
index 276d7ba..2b18a01 100644
--- a/man/man_db.renames
+++ b/man/man_db.renames.in
@@ -1,5 +1,6 @@
##############################################################################
-# Copyright (c) 1998-2010,2015 Free Software Foundation, Inc. #
+# Copyright 2019-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 #
# copy of this software and associated documentation files (the "Software"), #
@@ -25,7 +26,7 @@
# use or other dealings in this Software without prior written #
# authorization. #
##############################################################################
-# $Id: man_db.renames,v 1.48 2015/04/18 16:47:55 tom Exp $
+# $Id: man_db.renames.in,v 1.73 2024/04/13 23:39:11 tom Exp $
# Manual-page renamings for the man_db program
#
# Files:
@@ -149,49 +150,154 @@
mitem_value.3x menu_value.3menu
mitem_visible.3x menu_visible.3menu
ncurses.3x ncurses.3ncurses
-panel.3x panel.3curses
+new_pair.3x new_pair.3ncurses
+panel.3x panel.3ncurses
printf.3s printf.3
putc.3s putc.3
resizeterm.3x resizeterm.3ncurses
scanf.3s scanf.3
+scr_dump.5 scr_dump.5
system.3s system.3
tabs.1 tabs.1
term.5 term.5
term.7 term.7
term_variables.3x terminfo_variables.3ncurses
terminfo.5 terminfo.5
-terminfo.\\\*n terminfo.5
tic.1m tic.1
toe.1m toe.1
tput.1 tput.1
tset.1 tset.1
-vprintf.3s vprintf.3
+user_caps.5 user_caps.5
wresize.3x wresize.3ncurses
#
-# Other:
-tack.1m tack.1
+# Supplementary topics in the foregoing pages:
+add_wch.3x add_wch.3ncurses
+addch.3x addch.3ncurses
+assume_default_colors.3x assume_default_colors.3ncurses
+attr_get.3x attr_get.3ncurses
+attr_on.3x attr_on.3ncurses
+attron.3x attron.3ncurses
+baudrate.3x baudrate.3ncurses
+bkgd.3x bkgd.3ncurses
+bkgrnd.3x bkgrnd.3ncurses
+cbreak.3x cbreak.3ncurses
+clearok.3x clearok.3ncurses
+clrtoeol.3x clrtoeol.3ncurses
+curs_set.3x curs_set.3ncurses
+curscr.3x curscr.3ncurses
+curses_trace.3x curses_trace.3ncurses
+def_prog_mode.3x def_prog_mode.3ncurses
+def_shell_mode.3x def_shell_mode.3ncurses
+del_curterm.3x del_curterm.3ncurses
+delay_output.3x delay_output.3ncurses
+delscreen.3x delscreen.3ncurses
+derwin.3x derwin.3ncurses
+doupdate.3x doupdate.3ncurses
+echo.3x echo.3ncurses
+endwin.3x endwin.3ncurses
+extended_slk_color.3x extended_slk_color.3ncurses
+filter.3x filter.3ncurses
+flushinp.3x flushinp.3ncurses
+get_wch.3x get_wch.3ncurses
+getattr.3x getattr.3ncurses
+getcchar.3x getcchar.3ncurses
+getch.3x getch.3ncurses
+getwin.3x getwin.3ncurses
+halfdelay.3x halfdelay.3ncurses
+has_key.3x has_key.3ncurses
+idcok.3x idcok.3ncurses
+idlok.3x idlok.3ncurses
+immedok.3x immedok.3ncurses
+in_wch.3x in_wch.3ncurses
+inch.3x inch.3ncurses
+initscr.3x initscr.3ncurses
+is_scrollok.3x is_scrollok.3ncurses
+keyname.3x keyname.3ncurses
+keypad.3x keypad.3ncurses
+leaveok.3x leaveok.3ncurses
+longname.3x longname.3ncurses
+meta.3x meta.3ncurses
+move.3x move.3ncurses
+mvcur.3x mvcur.3ncurses
+mvwin.3x mvwin.3ncurses
+newpad.3x newpad.3ncurses
+newterm.3x newterm.3ncurses
+newwin.3x newwin.3ncurses
+nl.3x nl.3ncurses
+nocbreak.3x nocbreak.3ncurses
+nodelay.3x nodelay.3ncurses
+nonl.3x nonl.3ncurses
+notimeout.3x notimeout.3ncurses
+pnoutrefresh.3x pnoutrefresh.3ncurses
+prefresh.3x prefresh.3ncurses
+printw.3x printw.3ncurses
+putp.3x putp.3ncurses
+putwin.3x putwin.3ncurses
+raw.3x raw.3ncurses
+refresh.3x refresh.3ncurses
+reset_shell_mode.3x reset_shell_mode.3ncurses
+restartterm.3x restartterm.3ncurses
+ripoffline.3x ripoffline.3ncurses
+scrollok.3x scrollok.3ncurses
+set_curterm.3x set_curterm.3ncurses
+set_term.3x set_term.3nses
+setcchar.3x setcchar.3ncurses
+setupterm.3x setupterm.3ncurses
+slk_attr.3x slk_attr.3ncurses
+slk_color.3x slk_color.3ncurses
+slk_init.3x slk_init.3ncurses
+slk_touch.3x slk_touch.3ncurses
+start_color.3x start_color.3ncurses
+subwin.3x subwin.3ncurses
+syncok.3x syncok.3ncurses
+terminfo.3x terminfo.3ncurses
+tigetstr.3x tigetstr.3ncurses
+touchline.3x touchline.3ncurses
+touchwin.3x touchwin.3ncurses
+tparm.3x tparm.3ncurses
+tputs.3x tputs.3ncurses
+trace.3x trace.3ncurses
+unctrl.3x unctrl.3ncurses
+use_default_colors.3x use_default_colors.3ncurses
+use_env.3x use_env.3ncurses
+use_extended_names.3x use_extended_names.3ncurses
+use_legacy_coding.3x use_legacy_coding.3ncurses
+use_tioctl.3x use_tioctl.3ncurses
+vidputs.3x vidputs.3ncurses
+wadd_wch.3x wadd_wch.3ncurses
+waddch.3x waddch.3ncurses
+waddstr.3x waddstr.3ncurses
+waddwstr.3x waddwstr.3ncurses
+wattr_set.3x wattr_set.3ncurses
+wattrset.3x wattrset.3ncurses
+wbkgdset.3x wbkgdset.3ncurses
+wbkgrndset.3x wbkgrndset.3ncurses
+wdelch.3x wdelch.3ncurses
+wecho_wchar.3x wecho_wchar.3ncurses
+wechochar.3x wechochar.3ncurses
+wget_wch.3x wget_wch.3ncurses
+wgetch.3x wgetch.3ncurses
+wgetstr.3x wgetstr.3ncurses
+winch.3x winch.3ncurses
+wins_wch.3x wins_wch.3ncurses
+winsch.3x winsch.3ncurses
+wmove.3x wmove.3ncurses
+wnoutrefresh.3x wnoutrefresh.3ncurses
+wrefresh.3x wrefresh.3ncurses
+wsetscrreg.3x wsetscrreg.3ncurses
+wtimeout.3x wtimeout.3ncurses
#
-getty.1 getty.8
+# Other:
+getty.8 getty.8
scanf.3 scanf.3
ttys.5 ttys.4
-termio.7 termios.3
system.3 system.3
regcomp.3x regcomp.3
regexec.3x regexec.3
+vprintf.3 vprintf.3
#
# The following are pages which may be generated depending on configuration:
-adacurses-config.1 adacurses-config.1
-adacurses5-config.1 adacurses5-config.1
-adacurses6-config.1 adacurses6-config.1
-#
-ncurses5-config.1 ncurses5-config.1
-ncursesw5-config.1 ncursesw5-config.1
-ncursest5-config.1 ncursest5-config.1
-ncursestw5-config.1 ncursestw5-config.1
-#
-ncurses6-config.1 ncurses6-config.1
-ncursesw6-config.1 ncursesw6-config.1
-ncursest6-config.1 ncursest6-config.1
-ncursestw6-config.1 ncursestw6-config.1
+adacurses@USE_CFG_SUFFIX@-config.1 adacurses@USE_CFG_SUFFIX@-config.1
+ncurses@USE_CFG_SUFFIX@-config.1 ncurses@USE_CFG_SUFFIX@-config.1
#
# vile:cfgmode
diff --git a/man/manhtml.aliases b/man/manhtml.aliases
index a4ae047..7599c74 100644
--- a/man/manhtml.aliases
+++ b/man/manhtml.aliases
@@ -1,16 +1,133 @@
-# $Id: manhtml.aliases,v 1.1 2013/12/21 21:44:52 tom Exp $
+# $Id: manhtml.aliases,v 1.35 2024/04/14 00:36:21 tom Exp $
+#***************************************************************************
+# Copyright 2019-2023,2024 Thomas E. Dickey *
+# Copyright 2013,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 *
+# "Software"), to deal in the Software without restriction, including *
+# without limitation the rights to use, copy, modify, merge, publish, *
+# distribute, distribute with modifications, sublicense, and/or sell *
+# copies of the Software, and to permit persons to whom the Software is *
+# furnished to do so, subject to the following conditions: *
+# *
+# The above copyright notice and this permission notice shall be included *
+# in all copies or substantial portions of the Software. *
+# *
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
+# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
+# IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
+# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
+# OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
+# THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
+# *
+# Except as contained in this notice, the name(s) of the above copyright *
+# holders shall not be used in advertising or otherwise to promote the *
+# sale, use or other dealings in this Software without prior written *
+# authorization. *
+#***************************************************************************
# Items in this list will be linked to the corresponding manpages by man2html
+add_wch(3X) curs_add_wch(3X)
addch(3X) curs_addch(3X)
+assume_default_colors(3X) default_colors(3X)
+attr_get(3X) curs_attr(3X)
+attr_on(3X) curs_attr(3X)
+attron(3X) curs_attr(3X)
+baudrate(3X) curs_termattrs(3X)
+bkgd(3X) curs_bkgd(3X)
+bkgrnd(3X) curs_bkgrnd(3X)
+cbreak(3X) curs_inopts(3X)
+clearok(3X) curs_outopts(3X)
+clrtoeol(3X) curs_clear(3X)
+curs_set(3X) curs_kernel(3X)
+curscr(3X) curs_variables(3X)
+curses_trace(3X) curs_trace(3X)
+def_prog_mode(3X) curs_kernel(3X)
+def_shell_mode(3X) curs_kernel(3X)
+del_curterm(3X) curs_terminfo(3X)
+delay_output(3X) curs_util(3X)
delscreen(3X) curs_initscr(3X)
+doupdate(3X) curs_refresh(3X)
+echo(3X) curs_inopts(3X)
+endwin(3X) curs_initscr(3X)
+extended_slk_color(3X) curs_slk(3X)
filter(3X) curs_util(3X)
-form_fieldtype(3X) form_fieldtype(3X)
+flushinp(3X) curs_util(3X)
+get_wch(3X) curs_get_wch(3X)
+getcchar(3X) curs_getcchar(3X)
getch(3X) curs_getch(3X)
+getwin(3X) curs_util(3X)
+halfdelay(3X) curs_inopts(3X)
+has_key(3X) curs_getch(3X)
+immedok(3X) curs_outopts(3X)
+in_wch(3X) curs_in_wch(3X)
+inch(3X) curs_inch(3X)
infocmp(1) infocmp(1M)
initscr(3X) curs_initscr(3X)
+is_scrollok(3X) curs_opaque(3X)
+keyname(3X) curs_util(3X)
+keypad(3X) curs_inopts(3X)
+longname(3X) curs_termattrs(3X)
+meta(3X) curs_inopts(3X)
+move(3X) curs_move(3X)
+mvcur(3X) curs_terminfo(3X)
+mvwin(3X) curs_window(3X)
newterm(3X) curs_initscr(3X)
-set_fieldtype(3X) form_fieldtype(3X)
+newwin(3X) curs_window(3X)
+nl(3X) curs_inopts(3X)
+nocbreak(3X) curs_inopts(3X)
+nonl(3X) curs_inopts(3X)
+pnoutrefresh(3X) curs_pad(3X)
+prefresh(3X) curs_pad(3X)
+printw(3X) curs_printw(3X)
+putp(3X) curs_terminfo(3X)
+putwin(3X) curs_util(3X)
+raw(3X) curs_inopts(3X)
+refresh(3X) curs_refresh(3X)
+reset_shell_mode(3X) curs_kernel(3X)
+restartterm(3X) curs_terminfo(3X)
+ripoffline(3X) curs_kernel(3X)
+set_curterm(3X) curs_terminfo(3X)
set_term(3X) curs_initscr(3X)
+setcchar(3X) curs_getcchar(3X)
setupterm(3X) curs_terminfo(3X)
+slk_attr(3X) curs_slk(3X)
+slk_color(3X) curs_slk(3X)
+slk_init(3X) curs_slk(3X)
+slk_touch(3X) curs_slk(3X)
+start_color(3X) curs_color(3X)
+terminfo(3X) curs_terminfo(3X)
tic(1) tic(1M)
+tigetstr(3X) curs_terminfo(3X)
+touchline(3X) curs_touch(3X)
+touchwin(3X) curs_touch(3X)
+tparm(3X) curs_terminfo(3X)
+tputs(3X) curs_terminfo(3X)
+use_default_colors(3X) default_colors(3X)
use_env(3X) curs_util(3X)
+use_extended_names(3X) curs_extend(3X)
+use_legacy_coding(3X) legacy_coding(3X)
+use_tioctl(3X) curs_util(3X)
vidputs(3X) curs_terminfo(3X)
+wadd_wch(3X) curs_add_wch(3X)
+waddch(3X) curs_addch(3X)
+waddstr(3X) curs_addstr(3X)
+waddwstr(3X) curs_addwstr(3X)
+wattr_set(3X) curs_attr(3X)
+wattrset(3X) curs_attr(3X)
+wbkgdset(3X) curs_bkgd(3X)
+wbkgrndset(3X) curs_bkgrnd(3X)
+wdelch(3X) curs_delch(3X)
+wecho_wchar(3X) curs_add_wch(3X)
+wechochar(3X) curs_addch(3X)
+wget_wch(3X) curs_get_wch(3X)
+wgetch(3X) curs_getch(3X)
+wgetstr(3X) curs_getstr(3X)
+winch(3X) curs_inch(3X)
+wins_wch(3X) curs_ins_wch(3X)
+winsch(3X) curs_insch(3X)
+wmove(3X) curs_move(3X)
+wnoutrefresh(3X) curs_refresh(3X)
+wrefresh(3X) curs_refresh(3X)
+wsetscrreg(3X) curs_outopts(3X)
diff --git a/man/manhtml.externs b/man/manhtml.externs
index d26b612..41aa635 100644
--- a/man/manhtml.externs
+++ b/man/manhtml.externs
@@ -1,24 +1,83 @@
-# $Id: manhtml.externs,v 1.3 2013/12/21 22:11:29 tom Exp $
+# $Id: manhtml.externs,v 1.25 2024/04/20 19:26:05 tom Exp $
# Items in this list will not be linked by man2html
+#***************************************************************************
+# Copyright 2019-2023,2024 Thomas E. Dickey *
+# Copyright 2013,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 *
+# "Software"), to deal in the Software without restriction, including *
+# without limitation the rights to use, copy, modify, merge, publish, *
+# distribute, distribute with modifications, sublicense, and/or sell *
+# copies of the Software, and to permit persons to whom the Software is *
+# furnished to do so, subject to the following conditions: *
+# *
+# The above copyright notice and this permission notice shall be included *
+# in all copies or substantial portions of the Software. *
+# *
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
+# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
+# IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
+# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
+# OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
+# THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
+# *
+# Except as contained in this notice, the name(s) of the above copyright *
+# holders shall not be used in advertising or otherwise to promote the *
+# sale, use or other dealings in this Software without prior written *
+# authorization. *
+#***************************************************************************
+COLOR_PAIR(1)
+COLOR_PAIR(2)
+ascii(7)
+atoi(3)
+bash(1)
conflict(1)
+cron(1)
csh(1)
ded(1)
+emacs(1)
environ(7)
-getty(1)
+errno(3)
+file(1)
+getty(8)
+jove(1)
+lynx(1)
+mutt(1)
nvi(1)
+od(1)
+ioctl(2)
+isprint(3)
printf(3)
profile(5)
putc(3)
+putchar(3)
putwc(3)
read(2)
-rogue(1)
+readline(3)
+resize(1)
scanf(3)
+scanf(3S)
+screen(1)
+setbuf(3)
+setgid(2)
+setlocale(3)
+setuid(2)
sh(1)
sscanf(3)
stdio(3)
stty(1)
+swprintf(3)
system(3)
-termio(7)
+termios(3)
+tmux(1)
tty(4)
ttys(5)
+vi(1)
+vprintf(3)
+vscanf(3)
+vsscanf(3)
wcwidth(3)
+write(2)
+xterm(1)
diff --git a/man/manlinks.sed b/man/manlinks.sed
index 78055b4..6e2d2b8 100644
--- a/man/manlinks.sed
+++ b/man/manlinks.sed
@@ -1,6 +1,7 @@
-# $Id: manlinks.sed,v 1.13 2008/01/19 23:31:17 tom Exp $
+# $Id: manlinks.sed,v 1.21 2024/04/20 22:25:36 tom Exp $
##############################################################################
-# Copyright (c) 2000-2003,2008 Free Software Foundation, Inc. #
+# Copyright 2020-2023,2024 Thomas E. Dickey #
+# Copyright 2000-2003,2008 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 "Software"), #
@@ -30,6 +31,9 @@
# listed in the "NAME" section, i.e., the names that we would like to use
# as aliases for the manpage -T.Dickey
#
+# workaround for manpages without a SYNOPSIS
+s/^\.\\"SH/.SH/
+#
# eliminate formatting controls that get in the way
/^'\\"/d
/\.\\"/d
@@ -38,27 +42,32 @@
/typedef/d
s/^\.IX//
s/\\f.//g
+s/\\%//g
s/[:,]/ /g
#
-# eliminate unnecessary whitespace, convert multiple blanks to single space
+# ignore C-style comments
+s%/\*.*\*/%%
+#
+# Eliminate unnecessary whitespace, convert multiple blanks to single space.
s/^[ ][ ]*//
s/[ ][ ]*$//
s/[ ][ ]*/ /g
+/^$/d
#
# convert ".SH" into a more manageable form
s/\.SH[ ][ ]*/.SH_(/
#
# in ".SH NAME"
-# change "\-" to "-", eliminate text after "-", and split the remaining lines
-# at each space, making a list of names:
-/^\.SH_(NAME/,/^\.SH_(SYNOPSIS/{
-s/\\-.*/ -/
-/ -/{
-s/ -.*//
-s/ /\
-/g
-}
-/^-/{
+# Convert a list of names separated from their description by " \-" to a list
+# of names on separate lines. Normally the list is also comma-separated, but
+# we ignore that detail here. The description is on a separate line to make
+# the nroff source more pleasing to some eyes.
+/^\.SH_(NAME/,/ \\-$/{
+s/\\-/-/g
+s/ / /g
+/ -$/{
+s/ -$//
+n
d
}
s/ /\
@@ -66,10 +75,16 @@
}
#
# in ".SH SYNOPSIS"
-# remove any line that does not contain a '(', since we only want functions.
+# For readability, the NAME section may not contain all function names, but we
+# still want to make aliases for those. Do this by extracting names from the
+# list of function prototypes in the synopsis.
+#
+# Remove any line that does not contain a '(', since we only want functions.
# then strip off return-type of each function.
-# finally, remove the parameter list, which begins with a '('.
+#
+# Finally, remove the parameter list, which begins with a '('.
/^\.SH_(SYNOPSIS/,/^\.SH_(DESCRIPTION/{
+/^\.ti/d
/^[^(]*$/d
# reduce
# .B "int add_wch( const cchar_t *\fIwch\fB );"
diff --git a/man/menu.3x b/man/menu.3x
index c0be469..a833c3b 100644
--- a/man/menu.3x
+++ b/man/menu.3x
@@ -1,6 +1,7 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2014 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2014,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 *
@@ -27,108 +28,130 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu.3x,v 1.22 2014/08/16 20:32:08 tom Exp $
-.TH menu 3X ""
+.\" $Id: menu.3x,v 1.45 2024/03/16 15:35:01 tom Exp $
+.TH menu 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBmenu\fR \- curses extension for programming menus
+\fBmenu\fP \-
+curses extension for programming menus
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
+.nf
+\fB#include <menu.h>
+.fi
.SH DESCRIPTION
-The \fBmenu\fR library provides terminal-independent facilities for composing
-menu systems on character-cell terminals. The library includes: item routines,
+The \fBmenu\fP library provides terminal-independent facilities for composing
+menu systems on character-cell terminals.
+The library includes: item routines,
which create and modify menu items; and menu routines, which group items into
menus, display menus on the screen, and handle interaction with the user.
.PP
-The \fBmenu\fR library uses the \fBcurses\fR libraries, and a curses
-initialization routine such as \fBinitscr\fR must be called before using any of
-these functions. To use the \fBmenu\fR library, link with the options
-\fB\-lmenu \-lcurses\fR.
+The \fBmenu\fP library uses the \fBcurses\fP libraries, and a curses
+initialization routine such as \fBinitscr\fP must be called before using any of
+these functions.
+To use the \fBmenu\fP library, link with the options
+\fB\-lmenu \-lcurses\fP.
.
-.SS Current Default Values for Item Attributes
+.SS "Current Default Values for Item Attributes"
.
-The \fBmenu\fR library maintains a default value for item attributes. You can
-get or set this default by calling the appropriate \fBget_\fR or \fBset_\fR
-routine with a \fBNULL\fR item pointer. Changing this default with a
-\fBset_\fR function affects future item creations, but does not change the
+The \fBmenu\fP library maintains a default value for item attributes.
+You can
+get or set this default by calling the appropriate \fBget_\fP or \fBset_\fP
+routine with a \fBNULL\fP item pointer.
+Changing this default with a
+\fBset_\fP function affects future item creations, but does not change the
rendering of items already created.
.
-.SS Routine Name Index
+.SS "Routine Name Index"
.
-The following table lists each \fBmenu\fR routine and the name of
+The following table lists each \fBmenu\fP routine and the name of
the manual page on which it is described.
-.
+.PP
.TS
l l .
-\fBcurses\fR Routine Name Manual Page Name
+\fBcurses\fP Routine Name Manual Page Name
=
-current_item \fBmitem_current\fR(3X)
-free_item \fBmitem_new\fR(3X)
-free_menu \fBmenu_new\fR(3X)
-item_count \fBmenu_items\fR(3X)
-item_description \fBmitem_name\fR(3X)
-item_index \fBmitem_current\fR(3X)
-item_init \fBmenu_hook\fR(3X)
-item_name \fBmitem_name\fR(3X)
-item_opts \fBmitem_opts\fR(3X)
-item_opts_off \fBmitem_opts\fR(3X)
-item_opts_on \fBmitem_opts\fR(3X)
-item_term \fBmenu_hook\fR(3X)
-item_userptr \fBmitem_userptr\fR(3X)
-item_value \fBmitem_value\fR(3X)
-item_visible \fBmitem_visible\fR(3X)
-menu_back \fBmenu_attributes\fR(3X)
-menu_driver \fBmenu_driver\fR(3X)
-menu_fore \fBmenu_attributes\fR(3X)
-menu_format \fBmenu_format\fR(3X)
-menu_grey \fBmenu_attributes\fR(3X)
-menu_init \fBmenu_hook\fR(3X)
-menu_items \fBmenu_items\fR(3X)
-menu_mark \fBmenu_mark\fR(3X)
-menu_opts \fBmenu_opts\fR(3X)
-menu_opts_off \fBmenu_opts\fR(3X)
-menu_opts_on \fBmenu_opts\fR(3X)
-menu_pad \fBmenu_attributes\fR(3X)
-menu_pattern \fBmenu_pattern\fR(3X)
-menu_request_by_name \fBmenu_requestname\fR(3X)
-menu_request_name \fBmenu_requestname\fR(3X)
-menu_spacing \fBmenu_spacing\fR(3X)
-menu_sub \fBmenu_win\fR(3X)
-menu_term \fBmenu_hook\fR(3X)
-menu_userptr \fBmenu_userptr\fR(3X)
-menu_win \fBmenu_win\fR(3X)
-new_item \fBmitem_new\fR(3X)
-new_menu \fBmenu_new\fR(3X)
-pos_menu_cursor \fBmenu_cursor\fR(3X)
-post_menu \fBmenu_post\fR(3X)
-scale_menu \fBmenu_win\fR(3X)
-set_current_item \fBmitem_current\fR(3X)
-set_item_init \fBmenu_hook\fR(3X)
-set_item_opts \fBmitem_opts\fR(3X)
-set_item_term \fBmenu_hook\fR(3X)
-set_item_userptr \fBmitem_userptr\fR(3X)
-set_item_value \fBmitem_value\fR(3X)
-set_menu_back \fBmenu_attributes\fR(3X)
-set_menu_fore \fBmenu_attributes\fR(3X)
-set_menu_format \fBmenu_format\fR(3X)
-set_menu_grey \fBmenu_attributes\fR(3X)
-set_menu_init \fBmenu_hook\fR(3X)
-set_menu_items \fBmenu_items\fR(3X)
-set_menu_mark \fBmenu_mark\fR(3X)
-set_menu_opts \fBmitem_opts\fR(3X)
-set_menu_pad \fBmenu_attributes\fR(3X)
-set_menu_pattern \fBmenu_pattern\fR(3X)
-set_menu_spacing \fBmenu_spacing\fR(3X)
-set_menu_sub \fBmenu_win\fR(3X)
-set_menu_term \fBmenu_hook\fR(3X)
-set_menu_userptr \fBmenu_userptr\fR(3X)
-set_menu_win \fBmenu_win\fR(3X)
-set_top_row \fBmitem_current\fR(3X)
-top_row \fBmitem_current\fR(3X)
-unpost_menu \fBmenu_post\fR(3X)
+current_item \fBmitem_current\fP(3X)
+free_item \fBmitem_new\fP(3X)
+free_menu \fBmenu_new\fP(3X)
+item_count \fBmenu_items\fP(3X)
+item_description \fBmitem_name\fP(3X)
+item_index \fBmitem_current\fP(3X)
+item_init \fBmenu_hook\fP(3X)
+item_name \fBmitem_name\fP(3X)
+item_opts \fBmitem_opts\fP(3X)
+item_opts_off \fBmitem_opts\fP(3X)
+item_opts_on \fBmitem_opts\fP(3X)
+item_term \fBmenu_hook\fP(3X)
+item_userptr \fBmitem_userptr\fP(3X)
+item_value \fBmitem_value\fP(3X)
+item_visible \fBmitem_visible\fP(3X)
+menu_back \fBmenu_attributes\fP(3X)
+menu_driver \fBmenu_driver\fP(3X)
+menu_fore \fBmenu_attributes\fP(3X)
+menu_format \fBmenu_format\fP(3X)
+menu_grey \fBmenu_attributes\fP(3X)
+menu_init \fBmenu_hook\fP(3X)
+menu_items \fBmenu_items\fP(3X)
+menu_mark \fBmenu_mark\fP(3X)
+menu_opts \fBmenu_opts\fP(3X)
+menu_opts_off \fBmenu_opts\fP(3X)
+menu_opts_on \fBmenu_opts\fP(3X)
+menu_pad \fBmenu_attributes\fP(3X)
+menu_pattern \fBmenu_pattern\fP(3X)
+menu_request_by_name \fBmenu_requestname\fP(3X)
+menu_request_name \fBmenu_requestname\fP(3X)
+menu_spacing \fBmenu_spacing\fP(3X)
+menu_sub \fBmenu_win\fP(3X)
+menu_term \fBmenu_hook\fP(3X)
+menu_userptr \fBmenu_userptr\fP(3X)
+menu_win \fBmenu_win\fP(3X)
+new_item \fBmitem_new\fP(3X)
+new_menu \fBmenu_new\fP(3X)
+pos_menu_cursor \fBmenu_cursor\fP(3X)
+post_menu \fBmenu_post\fP(3X)
+scale_menu \fBmenu_win\fP(3X)
+set_current_item \fBmitem_current\fP(3X)
+set_item_init \fBmenu_hook\fP(3X)
+set_item_opts \fBmitem_opts\fP(3X)
+set_item_term \fBmenu_hook\fP(3X)
+set_item_userptr \fBmitem_userptr\fP(3X)
+set_item_value \fBmitem_value\fP(3X)
+set_menu_back \fBmenu_attributes\fP(3X)
+set_menu_fore \fBmenu_attributes\fP(3X)
+set_menu_format \fBmenu_format\fP(3X)
+set_menu_grey \fBmenu_attributes\fP(3X)
+set_menu_init \fBmenu_hook\fP(3X)
+set_menu_items \fBmenu_items\fP(3X)
+set_menu_mark \fBmenu_mark\fP(3X)
+set_menu_opts \fBmitem_opts\fP(3X)
+set_menu_pad \fBmenu_attributes\fP(3X)
+set_menu_pattern \fBmenu_pattern\fP(3X)
+set_menu_spacing \fBmenu_spacing\fP(3X)
+set_menu_sub \fBmenu_win\fP(3X)
+set_menu_term \fBmenu_hook\fP(3X)
+set_menu_userptr \fBmenu_userptr\fP(3X)
+set_menu_win \fBmenu_win\fP(3X)
+set_top_row \fBmitem_current\fP(3X)
+top_row \fBmitem_current\fP(3X)
+unpost_menu \fBmenu_post\fP(3X)
.TE
.SH RETURN VALUE
-Routines that return pointers return \fBNULL\fR on error. Routines that return
+Routines that return pointers return \fBNULL\fP on error.
+Routines that return
an integer return one of the following error codes:
.TP 5
.B E_OK
@@ -162,26 +185,31 @@
The menu driver could not process the request.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fP(3)).
.TP 5
.B E_UNKNOWN_COMMAND
The menu driver code saw an unknown request code.
.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header files
-\fB<curses.h>\fR and \fB<eti.h>\fR.
-.PP
-In your library list, libmenu.a should be before libncurses.a; that is,
-you want to say `\-lmenu \-lncurses', not the other way around (which would
-usually give a link-error).
+The header file \fI\%menu.h\fP itself includes the header file
+\fI\%curses.h\fP.
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
-.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for ncurses by Eric
-S. Raymond.
-.SH SEE ALSO
-\fBcurses\fR(3X) and related pages whose names begin "menu_" for detailed
-descriptions of the entry points.
.PP
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
+A menu facility was documented in SVr4.2's
+\fICharacter User Interface Programming\fP document.
+.PP
+It is not part of X/Open Curses.
+.PP
+Aside from \fI\%ncurses\fP, there are few implementations:
+.bP
+systems based on SVr4 source code, e.g., Solaris.
+.bP
+NetBSD curses.
+.SH AUTHORS
+Juergen Pfeifer.
+Manual pages and adaptation for \fI\%ncurses\fP by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X) and related pages whose names begin \*(``menu_\*(''
+for detailed descriptions of the entry points.
diff --git a/man/menu_attributes.3x b/man/menu_attributes.3x
index c33059b..7bce42d 100644
--- a/man/menu_attributes.3x
+++ b/man/menu_attributes.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2008,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,48 +27,69 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_attributes.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
-.TH menu_attributes 3X ""
+.\" $Id: menu_attributes.3x,v 1.36 2024/03/16 15:35:01 tom Exp $
+.TH menu_attributes 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
.SH NAME
-\fBmenu_attributes\fR \- color and attribute control for menus
+\fBmenu_back\fP,
+\fBmenu_fore\fP,
+\fBmenu_grey\fP,
+\fBmenu_pad\fP,
+\fBset_menu_back\fP,
+\fBset_menu_fore\fP,
+\fBset_menu_grey\fP,
+\fBset_menu_pad\fP \-
+color and attribute control for menus
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int set_menu_fore(MENU *menu, chtype attr);
-.br
-chtype menu_fore(const MENU *menu);
-.br
-int set_menu_back(MENU *menu, chtype attr);
-.br
-chtype menu_back(const MENU *menu);
-.br
-int set_menu_grey(MENU *menu, chtype attr);
-.br
-chtype menu_grey(const MENU *menu);
-.br
-int set_menu_pad(MENU *menu, int pad);
-.br
-int menu_pad(const MENU *menu);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBint set_menu_fore(MENU *\fImenu\fP, chtype \fIattr\fP);
+\fBchtype menu_fore(const MENU *\fImenu\fP);
+.PP
+\fBint set_menu_back(MENU *\fImenu\fP, chtype \fIattr\fP);
+\fBchtype menu_back(const MENU *\fImenu\fP);
+.PP
+\fBint set_menu_grey(MENU *\fImenu\fP, chtype \fIattr\fP);
+\fBchtype menu_grey(const MENU *\fImenu\fP);
+.PP
+\fBint set_menu_pad(MENU *\fImenu\fP, int \fIpad\fP);
+\fBint menu_pad(const MENU *\fImenu\fP);
+.fi
.SH DESCRIPTION
-The function \fBset_menu_fore\fR sets the foreground attribute of
-\fImenu\fR. This is the highlight used for selected menu items.
-\fBmenu_fore\fR returns the foreground attribute. The default
-is \fBA_REVERSE\fR.
+The function \fBset_menu_fore\fP sets the foreground attribute of
+\fImenu\fP. This is the highlight used for selected menu items.
+\fBmenu_fore\fP returns the foreground attribute.
+The default
+is \fBA_REVERSE\fP.
.PP
-The function \fBset_menu_back\fR sets the background attribute of
-\fImenu\fR. This is the highlight used for selectable (but not currently
-selected) menu items. The function \fBmenu_back\fR returns the background
-attribute. The default is \fBA_NORMAL\fR.
+The function \fBset_menu_back\fP sets the background attribute of
+\fImenu\fP. This is the highlight used for selectable (but not currently
+selected) menu items.
+The function \fBmenu_back\fP returns the background
+attribute.
+The default is \fBA_NORMAL\fP.
.PP
-The function \fBset_menu_grey\fR sets the grey attribute of \fImenu\fR. This is
+The function \fBset_menu_grey\fP sets the grey attribute of \fImenu\fP. This is
the highlight used for un-selectable menu items in menus that permit more than
-one selection. The function \fBmenu_grey\fR returns the grey attribute.
-The default is \fBA_UNDERLINE\fR.
+one selection.
+The function \fBmenu_grey\fP returns the grey attribute.
+The default is \fBA_UNDERLINE\fP.
.PP
-The function \fBset_menu_pad\fR sets the character used to fill the space
-between the name and description parts of a menu item. \fBmenu_pad\fR returns
-the given menu's pad character. The default is a blank.
+The function \fBset_menu_pad\fP sets the character used to fill the space
+between the name and description parts of a menu item.
+\fBmenu_pad\fP returns
+the given menu's pad character.
+The default is a blank.
.SH RETURN VALUE
These routines return one of the following:
.TP 5
@@ -76,19 +97,17 @@
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fP(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
-.SH SEE ALSO
-\fBcurses\fR(3X) and related pages whose names begin "menu_" for detailed
-descriptions of the entry points.
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X) and related pages whose names begin \*(``menu_\*(''
+for detailed descriptions of the entry points.
diff --git a/man/menu_cursor.3x b/man/menu_cursor.3x
index 66a835b..d92d8c3 100644
--- a/man/menu_cursor.3x
+++ b/man/menu_cursor.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,18 +27,21 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_cursor.3x,v 1.8 2010/12/04 18:40:45 tom Exp $
-.TH menu_cursor 3X ""
+.\" $Id: menu_cursor.3x,v 1.30 2024/03/16 15:35:01 tom Exp $
+.TH menu_cursor 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmenu_cursor\fR \- position a menu's cursor
+\fBpos_menu_cursor\fP \-
+position a menu's cursor
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int pos_menu_cursor(const MENU *menu);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBint pos_menu_cursor(const MENU *\fImenu\fP);
+.fi
.SH DESCRIPTION
-The function \fBpos_menu_cursor\fR restores the cursor to the current position
-associated with the menu's selected item. This is useful after \fBcurses\fR
+The function \fBpos_menu_cursor\fP restores the cursor to the current position
+associated with the menu's selected item.
+This is useful after \fBcurses\fP
routines have been called to do screen-painting in response to a menu select.
.SH RETURN VALUE
This routine returns one of the following:
@@ -47,21 +50,20 @@
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fP(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
.B E_NOT_POSTED
The menu has not been posted.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/menu_driver.3x b/man/menu_driver.3x
index 1fe5001..6a11728 100644
--- a/man/menu_driver.3x
+++ b/man/menu_driver.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2008,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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 *
@@ -26,25 +27,29 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_driver.3x,v 1.20 2010/12/04 18:38:55 tom Exp $
-.TH menu_driver 3X ""
+.\" $Id: menu_driver.3x,v 1.47 2024/03/16 15:35:01 tom Exp $
+.TH menu_driver 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.SH NAME
-\fBmenu_driver\fR \- command-processing loop of the menu system
+\fBmenu_driver\fP \-
+command-processing loop of the menu system
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int menu_driver(MENU *menu, int c);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBint menu_driver(MENU *\fImenu\fP, int \fIc\fP);
+.fi
.SH DESCRIPTION
Once a menu has been posted (displayed), you should funnel input events to it
-through \fBmenu_driver\fR. This routine has three major input cases:
+through \fBmenu_driver\fP. This routine has three major input cases:
.bP
The input is a form navigation request.
Navigation request codes are constants defined in \fB<form.h>\fP,
-which are distinct from the key- and character codes returned by \fBwgetch\fP.
+which are distinct from the key- and character codes
+returned by \fBwgetch\fP(3X).
.bP
The input is a printable character.
Printable characters (which must be positive, less than 256) are
@@ -107,13 +112,13 @@
.PP
If the second argument is a printable character, the code appends
it to the pattern buffer and attempts to move to the next item matching
-the new pattern. If there is no such match, \fBmenu_driver\fR returns
-\fBE_NO_MATCH\fR and deletes the appended character from the buffer.
+the new pattern.
+If there is no such match, \fBmenu_driver\fP returns
+\fBE_NO_MATCH\fP and deletes the appended character from the buffer.
.PP
If the second argument is one of the above pre-defined requests, the
corresponding action is performed.
-.SS MOUSE HANDLING
-.PP
+.SS "Mouse Handling"
If the second argument is the KEY_MOUSE special key, the associated
mouse event is translated into one of the above pre-defined requests.
Currently only clicks in the user window (e.g., inside the menu display
@@ -140,7 +145,7 @@
the menu cursor is positioned to that item.
.bP
If you double-click an item a REQ_TOGGLE_ITEM
-is generated and \fBE_UNKNOWN_COMMAND\fR is returned.
+is generated and \fBE_UNKNOWN_COMMAND\fP is returned.
This return value makes sense,
because a double click usually means that an item-specific action should
be returned.
@@ -148,25 +153,26 @@
application specific command should be executed.
.bP
If a translation
-into a request was done, \fBmenu_driver\fR returns the result of this request.
+into a request was done, \fBmenu_driver\fP returns the result of this request.
.PP
-If you clicked outside the user window or the mouse event could not be translated
-into a menu request an \fBE_REQUEST_DENIED\fR is returned.
-.SS APPLICATION-DEFINED COMMANDS
-.PP
+If you clicked outside the user window
+or the mouse event could not be translated
+into a menu request an \fBE_REQUEST_DENIED\fP is returned.
+.SS "Application-defined Commands"
If the second argument is neither printable nor one of the above
-pre-defined menu requests or KEY_MOUSE, the drive assumes it is an application-specific
-command and returns \fBE_UNKNOWN_COMMAND\fR. Application-defined commands
-should be defined relative to \fBMAX_COMMAND\fR, the maximum value of these
+pre-defined menu requests or KEY_MOUSE,
+the drive assumes it is an application-specific
+command and returns \fBE_UNKNOWN_COMMAND\fP. Application-defined commands
+should be defined relative to \fBMAX_COMMAND\fP, the maximum value of these
pre-defined requests.
.SH RETURN VALUE
-\fBmenu_driver\fR return one of the following error codes:
+\fBmenu_driver\fP return one of the following error codes:
.TP 5
.B E_OK
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fP(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
@@ -185,16 +191,15 @@
.TP 5
.B E_REQUEST_DENIED
The menu driver could not process the request.
-.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBmenu\fR(3X),
-\fBgetch\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header files
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
-Version 7 or BSD versions. The support for mouse events is ncurses specific.
+These routines emulate the System V menu library.
+They were not supported on
+Version 7 or BSD versions.
+The support for mouse events is \fI\%ncurses\fP specific.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%getch\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/menu_format.3x b/man/menu_format.3x
index b9a572b..9781878 100644
--- a/man/menu_format.3x
+++ b/man/menu_format.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2015,2016 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 *
@@ -27,30 +27,36 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_format.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
-.TH menu_format 3X ""
+.\" $Id: menu_format.3x,v 1.35 2024/03/16 15:35:01 tom Exp $
+.TH menu_format 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmenu_format\fR \- set and get menu sizes
+\fBset_menu_format\fP,
+\fBmenu_format\fP \-
+set and get menu sizes
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int set_menu_format(MENU *menu, int rows, int cols);
-.br
-void menu_format(const MENU *menu, int *rows, int *cols);
-.br
-.SH DESCRIPTION
-The function \fBset_menu_format\fR sets the maximum display size of the given
-menu. If this size is too small to display all menu items, the menu will be
-made scrollable. If this size is larger than the menus subwindow and the
-subwindow is too small to display all menu items, \fBpost_menu()\fR will fail.
+.nf
+\fB#include <menu.h>
.PP
-The default format is 16 rows, 1 column. Calling \fBset_menu_format\fR with a
-null menu pointer will change this default. A zero row or column argument to
-\fBset_menu_format\fR is interpreted as a request not to change the current
+\fBint set_menu_format(MENU *\fImenu\fP, int \fIrows\fP, int \fIcols\fP);
+\fBvoid menu_format(const MENU *\fImenu\fP, int *\fIrows\fP, int *\fIcols\fP);
+.fi
+.SH DESCRIPTION
+The function \fBset_menu_format\fP sets the maximum display size of the given
+menu.
+If this size is too small to display all menu items, the menu will be
+made scrollable.
+If this size is larger than the menus subwindow and the
+subwindow is too small to display all menu items, \fBpost_menu\fP will fail.
+.PP
+The default format is 16 rows, 1 column.
+Calling \fBset_menu_format\fP with a
+null menu pointer will change this default.
+A zero row or column argument to
+\fBset_menu_format\fP is interpreted as a request not to change the current
value.
.PP
-The function \fBmenu_format\fR returns the maximum-size constraints for the
-given menu into the storage addressed by \fBrows\fR and \fBcols\fR.
+The function \fBmenu_format\fP returns the maximum-size constraints for the
+given menu into the storage addressed by \fBrows\fP and \fBcols\fP.
.SH RETURN VALUE
These routines returns one of the following:
.TP 5
@@ -58,7 +64,7 @@
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fP(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
@@ -68,14 +74,13 @@
.TP 5
.B E_NOT_CONNECTED
No items are connected to the menu.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/menu_hook.3x b/man/menu_hook.3x
index 1fd74de..839e199 100644
--- a/man/menu_hook.3x
+++ b/man/menu_hook.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2007,2010 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 *
@@ -27,69 +27,71 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_hook.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
-.TH menu_hook 3X ""
+.\" $Id: menu_hook.3x,v 1.32 2024/03/16 15:35:01 tom Exp $
+.TH menu_hook 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmenu_hook\fR \- set hooks for automatic invocation by applications
+\fBmenu_hook\fP \-
+set hooks for automatic invocation by applications
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int set_item_init(MENU *menu, Menu_Hook func);
-.br
-Menu_Hook item_init(const MENU *menu);
-.br
-int set_item_term(MENU *menu, Menu_Hook func);
-.br
-Menu_Hook item_term(const MENU *menu);
-.br
-int set_menu_init(MENU *menu, Menu_Hook func);
-.br
-Menu_Hook menu_init(const MENU *menu);
-.br
-int set_menu_term(MENU *menu, Menu_Hook func);
-.br
-Menu_Hook menu_term(const MENU *menu);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBint set_item_init(MENU *\fImenu\fP, Menu_Hook \fIfunc\fP);
+\fBMenu_Hook item_init(const MENU *\fImenu\fP);
+.PP
+\fBint set_item_term(MENU *\fImenu\fP, Menu_Hook \fIfunc\fP);
+\fBMenu_Hook item_term(const MENU *\fImenu\fP);
+.PP
+\fBint set_menu_init(MENU *\fImenu\fP, Menu_Hook \fIfunc\fP);
+\fBMenu_Hook menu_init(const MENU *\fImenu\fP);
+.PP
+\fBint set_menu_term(MENU *\fImenu\fP, Menu_Hook \fIfunc\fP);
+\fBMenu_Hook menu_term(const MENU *\fImenu\fP);
+.fi
.SH DESCRIPTION
These functions make it possible to set hook functions to be called at various
-points in the automatic processing of input event codes by \fBmenu_driver\fR.
+points in the automatic processing of input event codes by \fBmenu_driver\fP.
.PP
-The function \fBset_item_init\fR sets a hook to be called at menu-post time and
-each time the selected item changes (after the change). \fBitem_init\fR
-returns the current item init hook, if any (\fBNULL\fR if there is no such
+The function \fBset_item_init\fP sets a hook to be called at menu-post time and
+each time the selected item changes (after the change).
+\fBitem_init\fP
+returns the current item init hook, if any (\fBNULL\fP if there is no such
hook).
.PP
-The function \fBset_item_term\fR sets a hook to be called at menu-unpost time
-and each time the selected item changes (before the change). \fBitem_term\fR
-returns the current item term hook, if any (\fBNULL\fR if there is no such
+The function \fBset_item_term\fP sets a hook to be called at menu-unpost time
+and each time the selected item changes (before the change).
+\fBitem_term\fP
+returns the current item term hook, if any (\fBNULL\fP if there is no such
hook).
.PP
-The function \fBset_menu_init\fR sets a hook to be called at menu-post time and
-just after the top row on the menu changes once it is posted. \fBmenu_init\fR
-returns the current menu init hook, if any (\fBNULL\fR if there is no such
+The function \fBset_menu_init\fP sets a hook to be called at menu-post time and
+just after the top row on the menu changes once it is posted.
+\fBmenu_init\fP
+returns the current menu init hook, if any (\fBNULL\fP if there is no such
hook).
.PP
-The function \fBset_menu_term\fR sets a hook to be called at menu-unpost time
+The function \fBset_menu_term\fP sets a hook to be called at menu-unpost time
and just before the top row on the menu changes once it is posted.
-\fBmenu_term\fR returns the current menu term hook, if any (\fBNULL\fR if there
+\fBmenu_term\fP returns the current menu term hook, if any (\fBNULL\fP if there
is no such hook).
.SH RETURN VALUE
-Routines that return pointers return \fBNULL\fR on error. Other routines
+Routines that return pointers return \fBNULL\fP on error.
+Other routines
return one of the following:
.TP 5
.B E_OK
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric
S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/menu_items.3x b/man/menu_items.3x
index 04b00ad..43409fe 100644
--- a/man/menu_items.3x
+++ b/man/menu_items.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2012,2015 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 *
@@ -27,34 +27,36 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_items.3x,v 1.10 2012/11/03 23:03:59 tom Exp $
-.TH menu_items 3X ""
+.\" $Id: menu_items.3x,v 1.34 2024/03/16 15:35:01 tom Exp $
+.TH menu_items 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmenu_items\fR \- make and break connections between items and menus
+\fBset_menu_items\fP,
+\fBmenu_items\fP,
+\fBitem_count\fP \-
+make and break connections between items and menus
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int set_menu_items(MENU *menu, ITEM **items);
-.br
-ITEM **menu_items(const MENU *menu);
-.br
-int item_count(const MENU *menu);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBint set_menu_items(MENU *\fImenu\fP, ITEM **\fIitems\fP);
+\fBITEM **menu_items(const MENU *\fImenu\fP);
+\fBint item_count(const MENU *\fImenu\fP);
+.fi
.SH DESCRIPTION
-The function \fBset_menu_items\fR changes the item pointer array of the given
-\fImenu\fR. The array must be terminated by a \fBNULL\fR.
+The function \fBset_menu_items\fP changes the item pointer array of the given
+\fImenu\fP. The array must be terminated by a \fBNULL\fP.
.PP
-The function \fBmenu_items\fR returns the item array of the given menu.
+The function \fBmenu_items\fP returns the item array of the given menu.
.PP
-The function \fBitem_count\fR returns the count of items in \fImenu\fR.
+The function \fBitem_count\fP returns the count of items in \fImenu\fP.
.SH RETURN VALUE
-The function \fBmenu_items\fR returns a pointer (which may be \fBNULL\fR).
-It does not set errno.
+The function \fBmenu_items\fP returns a pointer (which may be \fBNULL\fP).
+It does not set \fBerrno\fP.
.PP
-The function \fBitem_count\fR returns \fBERR\fR (the general \fBcurses\fR error
+The function \fBitem_count\fP returns \fBERR\fP (the general \fBcurses\fP error
return value) if its \fImenu\fP parameter is \fBNULL\fP.
.PP
-The function \fBset_menu_items\fR returns one of the following codes on error:
+The function \fBset_menu_items\fP returns one of the following codes on error:
.TP 5
.B E_OK
The routine succeeded.
@@ -69,19 +71,17 @@
The menu is already posted.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.PP
-The SVr4 menu library documentation specifies the \fBitem_count\fR error value
-as \-1 (which is the value of \fBERR\fR).
+The SVr4 menu library documentation specifies the \fBitem_count\fP error value
+as \-1 (which is the value of \fBERR\fP).
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/menu_mark.3x b/man/menu_mark.3x
index 1425154..e3f3a92 100644
--- a/man/menu_mark.3x
+++ b/man/menu_mark.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,37 +27,40 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_mark.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
-.TH menu_mark 3X ""
+.\" $Id: menu_mark.3x,v 1.35 2024/03/16 15:35:01 tom Exp $
+.TH menu_mark 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmenu_mark\fR \- get and set the menu mark string
+\fBset_menu_mark\fP,
+\fBmenu_mark\fP \-
+get and set the menu mark string
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int set_menu_mark(MENU *menu, const char *mark);
-.br
-const char *menu_mark(const MENU *menu);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBint set_menu_mark(MENU *\fImenu\fP, const char *\fImark\fP);
+\fBconst char *menu_mark(const MENU *\fImenu\fP);
+.fi
.SH DESCRIPTION
In order to make menu selections visible on older terminals without
highlighting or color capability, the menu library marks selected items
in a menu with a prefix string.
.PP
-The function \fBset_menu_mark\fR sets the mark string for the given menu.
-Calling \fBset_menu_mark\fR with a null menu item will abolish the mark string.
+The function \fBset_menu_mark\fP sets the mark string for the given menu.
+Calling \fBset_menu_mark\fP with a null menu item will abolish the mark string.
Note that changing the length of the mark string for a menu while the
menu is posted is likely to produce unhelpful behavior.
.PP
-The default string is "\-" (a dash). Calling \fBset_menu_mark\fR with
-a non-\fBNULL\fR menu argument will change this default.
+The default string is "\-" (a dash).
+Calling \fBset_menu_mark\fP with
+a non-\fBNULL\fP menu argument will change this default.
.PP
-The function \fBmenu_mark\fR returns the menu's mark string (or \fBNULL\fR if
+The function \fBmenu_mark\fP returns the menu's mark string (or \fBNULL\fP if
there is none).
.SH RETURN VALUE
-The function \fBmenu_mark\fR returns a pointer (which may be \fBNULL\fR).
-It does not set errno.
+The function \fBmenu_mark\fP returns a pointer (which may be \fBNULL\fP).
+It does not set \fBerrno\fP.
.PP
-The function \fBset_menu_mark\fR may return the following error codes:
+The function \fBset_menu_mark\fP may return the following error codes:
.TP 5
.B E_OK
The routine succeeded.
@@ -66,15 +69,14 @@
Routine detected an incorrect or out-of-range argument.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/menu_new.3x b/man/menu_new.3x
index 1197654..1a13374 100644
--- a/man/menu_new.3x
+++ b/man/menu_new.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,26 +27,28 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_new.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
-.TH menu_new 3X ""
+.\" $Id: menu_new.3x,v 1.35 2024/03/16 15:35:01 tom Exp $
+.TH menu_new 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmenu_new\fR \- create and destroy menus
+\fBnew_menu\fP,
+\fBfree_menu\fP \-
+create and destroy menus
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-MENU *new_menu(ITEM **items);
-.br
-int free_menu(MENU *menu);
-.br
-.SH DESCRIPTION
-The function \fBnew_menu\fR creates a new menu connected to a specified item
-pointer array (which must be \fBNULL\fR-terminated).
+.nf
+\fB#include <menu.h>
.PP
-The function \fBfree_menu\fR disconnects \fImenu\fR from its item array
+\fBMENU *new_menu(ITEM **\fIitems\fP);
+\fBint free_menu(MENU *\fImenu\fP);
+.fi
+.SH DESCRIPTION
+The function \fBnew_menu\fP creates a new menu connected to a specified item
+pointer array (which must be \fBNULL\fP-terminated).
+.PP
+The function \fBfree_menu\fP disconnects \fImenu\fP from its item array
and frees the storage allocated for the menu.
.SH RETURN VALUE
-The function \fBnew_menu\fR returns \fBNULL\fR on error.
-It sets errno according to the function's failure:
+The function \fBnew_menu\fP returns \fBNULL\fP on error.
+It sets \fBerrno\fP according to the function's failure:
.TP 5
.B E_NOT_CONNECTED
No items are connected to the menu.
@@ -54,27 +56,26 @@
.B E_SYSTEM_ERROR
System error occurred, e.g., malloc failure.
.PP
-The function \fBfree_menu\fR returns one of the following:
+The function \fBfree_menu\fP returns one of the following:
.TP 5
.B E_OK
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fP(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
.B E_POSTED
The menu has already been posted.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/menu_opts.3x b/man/menu_opts.3x
index 5f4cb08..ad7fe97 100644
--- a/man/menu_opts.3x
+++ b/man/menu_opts.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2015,2016 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 *
@@ -27,32 +27,35 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_opts.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
-.TH menu_opts 3X ""
+.\" $Id: menu_opts.3x,v 1.35 2024/03/16 15:35:01 tom Exp $
+.TH menu_opts 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmenu_opts\fR \- set and get menu options
+\fBset_menu_opts\fP,
+\fBmenu_opts_on\fP,
+\fBmenu_opts_off\fP,
+\fBmenu_opts\fP \-
+set and get menu options
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int set_menu_opts(MENU *menu, Menu_Options opts);
-.br
-int menu_opts_on(MENU *menu, Menu_Options opts);
-.br
-int menu_opts_off(MENU *menu, Menu_Options opts);
-.br
-Menu_Options menu_opts(const MENU *menu);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBint set_menu_opts(MENU *\fImenu\fP, Menu_Options \fIopts\fP);
+\fBMenu_Options menu_opts(const MENU *\fImenu\fP);
+.PP
+\fBint menu_opts_on(MENU *\fImenu\fP, Menu_Options \fIopts\fP);
+\fBint menu_opts_off(MENU *\fImenu\fP, Menu_Options \fIopts\fP);
+.fi
.SH DESCRIPTION
-The function \fBset_menu_opts\fR sets all the given menu's option bits (menu
+The function \fBset_menu_opts\fP sets all the given menu's option bits (menu
option bits may be logically-OR'ed together).
.PP
-The function \fBmenu_opts_on\fR turns on the given option bits, and leaves
+The function \fBmenu_opts_on\fP turns on the given option bits, and leaves
others alone.
.PP
-The function \fBmenu_opts_off\fR turns off the given option bits, and leaves
+The function \fBmenu_opts_off\fP turns off the given option bits, and leaves
others alone.
.PP
-The function \fBmenu_opts\fR returns the menu's current option bits.
+The function \fBmenu_opts\fP returns the menu's current option bits.
.PP
The following options are defined (all are on by default):
.TP 5
@@ -74,25 +77,30 @@
O_NONCYCLIC
Don't wrap around next-item and previous-item,
requests to the other end of the menu.
+.TP 5
+O_MOUSE_MENU
+If user clicks with the mouse
+and it does not fall on the currently active menu,
+push \fBKEY_MOUSE\fP and the \fBMEVENT\fP data
+back on the queue to allow processing in another part of the calling program.
.SH RETURN VALUE
-Except for \fBmenu_opts\fR, each routine returns one of the following:
+Except for \fBmenu_opts\fP, each routine returns one of the following:
.TP 5
.B E_OK
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fP(3)).
.TP 5
.B E_POSTED
The menu is already posted.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/menu_pattern.3x b/man/menu_pattern.3x
index e63a9f7..a66a368 100644
--- a/man/menu_pattern.3x
+++ b/man/menu_pattern.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2008,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -26,34 +27,40 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_pattern.3x,v 1.13 2010/12/04 18:40:45 tom Exp $
-.TH menu_pattern 3X ""
+.\" $Id: menu_pattern.3x,v 1.38 2024/03/16 15:35:01 tom Exp $
+.TH menu_pattern 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmenu_pattern\fR \- get and set a menu's pattern buffer
+\fBset_menu_pattern\fP,
+\fBmenu_pattern\fP \-
+set and get a menu's pattern buffer
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int set_menu_pattern(MENU *menu, const char *pattern);
-.br
-char *menu_pattern(const MENU *menu);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBint set_menu_pattern(MENU *\fImenu\fP, const char *\fIpattern\fP);
+\fBchar *menu_pattern(const MENU *\fImenu\fP);
+.fi
.SH DESCRIPTION
-Every menu has an associated pattern match buffer. As input events that are
+Every menu has an associated pattern match buffer.
+As input events that are
printable characters come in, they are appended to this match buffer
-and tested for a match, as described in \fBmenu_driver\fR(3X).
+and tested for a match, as described in \fBmenu_driver\fP(3X).
.PP
-The function \fBset_menu_pattern\fR sets the pattern buffer for the given menu
-and tries to find the first matching item. If it succeeds, that item becomes
-current; if not, the current item does not change.
+The function \fBset_menu_pattern\fP sets the pattern buffer for the given menu
+and tries to find the first matching item.
+If it succeeds, that item becomes
+current; if not, the current item does not change.
.PP
-The function \fBmenu_pattern\fR returns the pattern buffer of the given
-\fImenu\fR.
+The function \fBmenu_pattern\fP returns the pattern buffer of the given
+\fImenu\fP.
.SH RETURN VALUE
-The function \fBmenu_pattern\fR returns a pointer, which is \fBNULL\fR if the \fImenu\fP parameter is \fBNULL\fP.
-Otherwise, it is a pointer to a string which is empty if no pattern has been set.
-It does not set errno.
+The function \fBmenu_pattern\fP returns a pointer,
+which is \fBNULL\fP if the \fImenu\fP parameter is \fBNULL\fP.
+Otherwise, it is a pointer to a string which is empty
+if no pattern has been set.
+It does not set \fBerrno\fP.
.PP
-The function \fBset_menu_pattern\fR may return the following error codes:
+The function \fBset_menu_pattern\fP may return the following error codes:
.TP 5
.B E_OK
The routine succeeded.
@@ -71,15 +78,14 @@
Character failed to match.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/menu_post.3x b/man/menu_post.3x
index d09d0ca..4a0827a 100644
--- a/man/menu_post.3x
+++ b/man/menu_post.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -27,24 +27,29 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_post.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
-.TH menu_post 3X ""
+.\" $Id: menu_post.3x,v 1.36 2024/03/16 15:35:01 tom Exp $
+.TH menu_post 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmenu_post\fR \- write or erase menus from associated subwindows
+\fBpost_menu\fP,
+\fBunpost_menu\fP \-
+write or erase menus from associated subwindows
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int post_menu(MENU *menu);
-.br
-int unpost_menu(MENU *menu);
-.br
-.SH DESCRIPTION
-The function \fBpost_menu\fR displays a menu to its associated subwindow. To
-trigger physical display of the subwindow, use \fBrefresh\fR or some equivalent
-\fBcurses\fR routine (the implicit \fBdoupdate\fR triggered by an \fBcurses\fR
-input request will do). \fBpost_menu\fR resets the selection status of all items.
+.nf
+\fB#include <menu.h>
.PP
-The function \fBunpost_menu\fR erases menu from its associated subwindow.
+\fBint post_menu(MENU *\fImenu\fP);
+\fBint unpost_menu(MENU *\fImenu\fP);
+.fi
+.SH DESCRIPTION
+The function \fBpost_menu\fP displays a menu to its associated subwindow.
+To
+trigger physical display of the subwindow,
+use \fBrefresh\fP(3X) or some equivalent
+\fBcurses\fP routine (the implicit \fBdoupdate\fP triggered by an \fBcurses\fP
+input request will do).
+\fBpost_menu\fP resets the selection status of all items.
+.PP
+The function \fBunpost_menu\fP erases menu from its associated subwindow.
.SH RETURN VALUE
These routines return one of the following:
.TP 5
@@ -52,7 +57,7 @@
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fP(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
@@ -64,22 +69,21 @@
Routine was called from an initialization or termination function.
.TP 5
.B E_NO_ROOM
-Menu is too large for its window. You should consider to use
-\fBset_menu_format()\fR to solve the problem.
+Menu is too large for its window.
+You should consider using \fBset_menu_format\fP to solve the problem.
.TP 5
.B E_NOT_POSTED
The menu has not been posted.
.TP 5
.B E_NOT_CONNECTED
No items are connected to the menu.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/menu_requestname.3x b/man/menu_requestname.3x
index d1957a2..a0363fb 100644
--- a/man/menu_requestname.3x
+++ b/man/menu_requestname.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,39 +27,41 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_requestname.3x,v 1.9 2010/12/04 18:40:45 tom Exp $
-.TH menu_requestname 3X ""
+.\" $Id: menu_requestname.3x,v 1.33 2024/03/16 15:35:01 tom Exp $
+.TH menu_requestname 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmenu_requestname\fR \- handle printable menu request names
+\fBmenu_request_by_name\fP,
+\fBmenu_request_name\fP \-
+handle printable menu request names
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-const char *menu_request_name(int request);
-.br
-int menu_request_by_name(const char *name);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBconst char *menu_request_name(int \fIrequest\fP);
+\fBint menu_request_by_name(const char *\fIname\fP);
+.fi
.SH DESCRIPTION
-The function \fBmenu_request_name\fR returns the printable name of a menu
+The function \fBmenu_request_name\fP returns the printable name of a menu
request code.
.br
-The function \fBmenu_request_by_name\fR searches in the name-table for a request
+The function \fBmenu_request_by_name\fP searches in the name-table for a request
with the given name and returns its request code.
Otherwise E_NO_MATCH is returned.
.SH RETURN VALUE
-\fBmenu_request_name\fR returns \fBNULL\fR on error
-and sets errno to \fBE_BAD_ARGUMENT\fR.
+\fBmenu_request_name\fP returns \fBNULL\fP on error
+and sets \fBerrno\fP to \fBE_BAD_ARGUMENT\fP.
.br
-\fBmenu_request_by_name\fR returns \fBE_NO_MATCH\fR on error.
-It does not set errno.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+\fBmenu_request_by_name\fP returns \fBE_NO_MATCH\fP on error.
+It does not set \fBerrno\fP.
.SH PORTABILITY
-These routines are specific to ncurses. They were not supported on
-Version 7, BSD or System V implementations. It is recommended that
+These 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 them be conditioned using NCURSES_VERSION.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/menu_spacing.3x b/man/menu_spacing.3x
index 9e7c3ea..d15e77d 100644
--- a/man/menu_spacing.3x
+++ b/man/menu_spacing.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2004,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,58 +27,60 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_spacing.3x,v 1.12 2010/12/04 18:38:55 tom Exp $
-.TH menu_spacing 3X ""
+.\" $Id: menu_spacing.3x,v 1.37 2024/03/16 15:35:01 tom Exp $
+.TH menu_spacing 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmenu_spacing\fR \- Control spacing between menu items.
+\fBset_menu_spacing\fP,
+\fBmenu_spacing\fP \-
+set and get spacing between menu items.
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int set_menu_spacing(MENU *menu,
- int spc_description,
- int spc_rows,
- int spc_columns);
-.br
-int menu_spacing(const MENU *menu,
- int* spc_description,
- int* spc_rows,
- int* spc_columns);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBint set_menu_spacing(MENU *\fImenu\fP,
+ \fBint \fIspc_description\fB,\fR
+ \fBint \fIspc_rows\fB,\fR
+ \fBint \fIspc_columns\fB);\fR
+\fBint menu_spacing(const MENU *\fImenu\fB,\fR
+ \fBint* \fIspc_description\fB,\fR
+ \fBint* \fIspc_rows\fB,\fR
+ \fBint* \fIspc_columns\fB);\fR
+.fi
.SH DESCRIPTION
-The function \fBset_menu_spacing\fR sets the spacing information for the menu.
-Its parameter \fBspc_description\fR controls the number of spaces between an item name and an item
-description.
-It must not be larger than \fBTABSIZE\fR.
+The function \fBset_menu_spacing\fP sets the spacing information for the menu.
+Its parameters provide the description and the size (in rows and columns).
+.TP
+\fIspc_description\fP
+controls the number of spaces
+between an item name and an item description.
+It must not be larger than \fBTABSIZE\fP.
The menu system puts in the
middle of this spacing area the pad character.
The remaining parts are filled with
spaces.
-The \fBspc_rows\fR parameter controls the number of rows that are used for an item.
+.TP
+\fIspc_rows\fP
+controls the number of rows
+that are used for an item.
It must not be larger than 3.
The menu system inserts the blank lines between item rows, these lines
will contain the pad character in the appropriate positions.
-The \fBspc_columns\fR parameter controls the number of blanks between columns of items.
-It must not be larger than TABSIZE.
-A value of 0 for all the spacing values resets them to the default, which is 1 for all
-of them.
-.br
-The function \fBmenu_spacing\fR passes back the spacing info for the menu.
-If a
-pointer is NULL, this specific info is simply not returned.
+.TP
+\fIspc_columns\fP
+controls the number of blanks between columns of items.
+It must not be larger than \fBTABSIZE\fP.
+A value of 0 for all the spacing values resets them to the default,
+which is 1 for all of them.
+.PP
+The function \fBmenu_spacing\fP returns the spacing information for the menu.
+If a pointer is NULL, the corresponding information is simply not returned.
.SH RETURN VALUE
-Both routines return \fBE_OK\fR on success.
-\fBset_menu_spacing\fR may return
-\fBE_POSTED\fR if the menu is posted, or \fBE_BAD_ARGUMENT\fR if one of the
+Both routines return \fBE_OK\fP on success.
+\fBset_menu_spacing\fP may return
+\fBE_POSTED\fP if the menu is posted, or \fBE_BAD_ARGUMENT\fP if one of the
spacing values is out of range.
-.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_variables\fR(3X),
-\fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines are specific to ncurses.
+These routines are specific to \fI\%ncurses\fP.
They were not supported on
Version 7, BSD or System V implementations.
It is recommended that
@@ -86,3 +88,7 @@
.SH AUTHORS
Juergen Pfeifer.
Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%curs_variables\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/menu_userptr.3x b/man/menu_userptr.3x
index 0455fe3..292bbd6 100644
--- a/man/menu_userptr.3x
+++ b/man/menu_userptr.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,37 +27,38 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_userptr.3x,v 1.10 2010/12/04 18:40:45 tom Exp $
-.TH menu_userptr 3X ""
+.\" $Id: menu_userptr.3x,v 1.33 2024/03/16 15:35:01 tom Exp $
+.TH menu_userptr 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmenu_userptr\fR \- associate application data with a menu item
+\fBset_menu_userptr\fP,
+\fBmenu_userptr\fP \-
+associate application data with a menu item
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int set_menu_userptr(MENU *menu, void *userptr);
-.br
-void *menu_userptr(const MENU *menu);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBint set_menu_userptr(MENU *\fImenu\fP, void *\fIuserptr\fP);
+\fBvoid *menu_userptr(const MENU *\fImenu\fP);
+.fi
.SH DESCRIPTION
Every menu and every menu item has a field that can be used to hold
application-specific data (that is, the menu-driver code leaves it alone).
These functions get and set the menu user pointer field.
.SH RETURN VALUE
-\fBmenu_userptr\fR returns a pointer (which may be \fBNULL\fR).
-It does not set errno.
+\fBmenu_userptr\fP returns a pointer (which may be \fBNULL\fP).
+It does not set \fBerrno\fP.
.PP
\fBset_menu_userptr\fP returns \fBE_OK\fP (success).
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.PP
The user pointer is a void pointer.
We chose not to leave it as a char pointer for SVr4 compatibility.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/menu_win.3x b/man/menu_win.3x
index 774eafa..36f6129 100644
--- a/man/menu_win.3x
+++ b/man/menu_win.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2006,2010 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 *
@@ -27,46 +27,49 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_win.3x,v 1.11 2010/12/04 18:38:55 tom Exp $
-.TH menu_win 3X ""
+.\" $Id: menu_win.3x,v 1.32 2024/03/16 15:35:01 tom Exp $
+.TH menu_win 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmenu_win\fR \- make and break menu window and subwindow associations
+\fBmenu_win\fP \-
+make and break menu window and subwindow associations
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int set_menu_win(MENU *menu, WINDOW *win);
-.br
-WINDOW *menu_win(const MENU *menu);
-.br
-int set_menu_sub(MENU *menu, WINDOW *sub);
-.br
-WINDOW *menu_sub(const MENU *menu);
-.br
-int scale_menu(const MENU *menu, int *rows, int *columns);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBint set_menu_win(MENU *\fImenu\fP, WINDOW *\fIwin\fP);
+\fBWINDOW *menu_win(const MENU *\fImenu\fP);
+.PP
+\fBint set_menu_sub(MENU *\fImenu\fP, WINDOW *\fIsub\fP);
+\fBWINDOW *menu_sub(const MENU *\fImenu\fP);
+.PP
+\fBint scale_menu(const MENU *\fImenu\fP, int *\fIrows\fP, int *\fIcolumns\fP);
+.fi
.SH DESCRIPTION
-Every menu has an associated pair of \fBcurses\fR windows. The menu window
+Every menu has an associated pair of \fBcurses\fP windows.
+The menu window
displays any title and border associated with the window; the menu subwindow
displays the items of the menu that are currently available for selection.
.PP
-The first four functions get and set those windows. It is not necessary to set
-either window; by default, the driver code uses \fBstdscr\fR for both.
+The first four functions get and set those windows.
+It is not necessary to set
+either window; by default, the driver code uses \fBstdscr\fP for both.
.PP
-In the \fBset_\fR functions, window argument of \fBNULL\fR is treated as though
-it were \fBstsdcr\fR. A menu argument of \fBNULL\fR is treated as a request
+In the \fBset_\fP functions, window argument of \fBNULL\fP is treated as though
+it were \fBstsdcr\fP. A menu argument of \fBNULL\fP is treated as a request
to change the system default menu window or subwindow.
.PP
-The function \fBscale_menu\fR returns the minimum size required for the
-subwindow of \fImenu\fR.
+The function \fBscale_menu\fP returns the minimum size required for the
+subwindow of \fImenu\fP.
.SH RETURN VALUE
-Routines that return pointers return \fBNULL\fR on error. Routines that return
+Routines that return pointers return \fBNULL\fP on error.
+Routines that return
an integer return one of the following error codes:
.TP 5
.B E_OK
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fP(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
@@ -76,16 +79,14 @@
.TP 5
.B E_NOT_CONNECTED
No items are connected to the menu.
-.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_variables\fR(3X),
-\fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%curs_variables\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/mitem_current.3x b/man/mitem_current.3x
index 86c9b47..42d36c3 100644
--- a/man/mitem_current.3x
+++ b/man/mitem_current.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2006,2010 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 *
@@ -27,44 +27,47 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: mitem_current.3x,v 1.13 2010/12/04 18:40:45 tom Exp $
-.TH mitem_current 3X ""
+.\" $Id: mitem_current.3x,v 1.37 2024/03/16 15:35:01 tom Exp $
+.TH mitem_current 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmitem_current\fR \- set and get current_menu_item
+\fBmitem_current\fP \-
+set and get current_menu_item
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int set_current_item(MENU *menu, const ITEM *item);
-.br
-ITEM *current_item(const MENU *menu);
-.br
-int set_top_row(MENU *menu, int row);
-.br
-int top_row(const MENU *menu);
-.br
-int item_index(const ITEM *item);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBint set_current_item(MENU *\fImenu\fP, ITEM *\fIitem\fP);
+\fBITEM *current_item(const MENU *\fImenu\fP);
+.PP
+\fBint set_top_row(MENU *\fImenu\fP, int \fIrow\fP);
+\fBint top_row(const MENU *\fImenu\fP);
+.PP
+\fBint item_index(const ITEM *\fIitem\fP);
+.fi
.SH DESCRIPTION
-The function \fBset_current_item\fR sets the current item (the item on which
-the menu cursor is positioned). \fBcurrent_item\fR returns a pointer to the
+The function \fBset_current_item\fP sets the current item (the item on which
+the menu cursor is positioned).
+\fBcurrent_item\fP returns a pointer to the
current item in the given menu.
.PP
-The function \fBset_top_row\fR sets the top row of the menu to show the given
+The function \fBset_top_row\fP sets the top row of the menu to show the given
row (the top row is initially 0, and is reset to this value whenever the
-\fBO_ROWMAJOR\fR option is toggled). The item leftmost on the given row
-becomes current. The function \fBtop_row\fR returns the number of the top menu
+\fBO_ROWMAJOR\fP option is toggled).
+The item leftmost on the given row
+becomes current.
+The function \fBtop_row\fP returns the number of the top menu
row being displayed.
.PP
-The function \fBitem_index\fR returns the (zero-origin) index of \fIitem\fR in
+The function \fBitem_index\fP returns the (zero-origin) index of \fIitem\fP in
the menu's item pointer list.
.SH RETURN VALUE
-\fBcurrent_item\fR returns a pointer (which may be \fBNULL\fR).
-It does not set errno.
+\fBcurrent_item\fP returns a pointer (which may be \fBNULL\fP).
+It does not set \fBerrno\fP.
.PP
-\fBtop_row\fR and \fBitem_index\fR return \fBERR\fR (the general \fBcurses\fR
+\fBtop_row\fP and \fBitem_index\fP return \fBERR\fP (the general \fBcurses\fP
error value) if their \fImenu\fP parameter is \fBNULL\fP.
.PP
-\fBset_current_item\fR and \fBset_top_row\fR return one of the following:
+\fBset_current_item\fP and \fBset_top_row\fP return one of the following:
.TP 5
.B E_OK
The routine succeeded.
@@ -79,18 +82,17 @@
No items are connected to the menu.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.PP
-The SVr4 menu library documentation specifies the \fBtop_row\fR and
-\fBindex_item\fR error value as \-1 (which is the value of \fBERR\fR).
+The SVr4 menu library documentation specifies the \fBtop_row\fP and
+\fBindex_item\fP error value as \-1 (which is the value of \fBERR\fP).
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/mitem_name.3x b/man/mitem_name.3x
index ff879e6..3606bb5 100644
--- a/man/mitem_name.3x
+++ b/man/mitem_name.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,33 +27,33 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: mitem_name.3x,v 1.8 2010/12/04 18:40:45 tom Exp $
-.TH mitem_name 3X ""
+.\" $Id: mitem_name.3x,v 1.31 2024/03/16 15:35:01 tom Exp $
+.TH mitem_name 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmitem_name\fR \- get menu item name and description fields
+\fBitem_name\fP,
+\fBitem_description\fP \-
+get menu item name and description fields
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-const char *item_name(const ITEM *item);
-.br
-const char *item_description(const ITEM *item);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBconst char *item_name(const ITEM *\fIitem\fP);
+\fBconst char *item_description(const ITEM *\fIitem\fP);
+.fi
.SH DESCRIPTION
-The function \fBitem_name\fR returns the name part of the given item.
+The function \fBitem_name\fP returns the name part of the given item.
.br
-The function \fBitem_description\fR returns the description part of the given
+The function \fBitem_description\fP returns the description part of the given
item.
.SH RETURN VALUE
-These routines return a pointer (which may be \fBNULL\fR).
-They do not set errno.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+These routines return a pointer (which may be \fBNULL\fP).
+They do not set \fBerrno\fP.
.SH PORTABILITY
These routines emulate the System V menu library.
They were not supported on Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/mitem_new.3x b/man/mitem_new.3x
index 8e2449e..66bd29b 100644
--- a/man/mitem_new.3x
+++ b/man/mitem_new.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,30 +27,36 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: mitem_new.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
-.TH mitem_new 3X ""
+.\" $Id: mitem_new.3x,v 1.36 2024/03/16 15:35:01 tom Exp $
+.TH mitem_new 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmitem_new\fR \- create and destroy menu items
+\fBnew_item\fP,
+\fBfree_item\fP \-
+create and destroy menu items
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-ITEM *new_item(const char *name, const char *description);
-.br
-int free_item(ITEM *item);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBITEM *new_item(const char *\fIname\fP, const char *\fIdescription\fP);
+\fBint free_item(ITEM *\fIitem\fP);
+.fi
.SH DESCRIPTION
-The function \fBnew_item\fR allocates a new item and initializes it from the
-\fBname\fR and \fBdescription\fR pointers. Please notice that the item stores
-only the pointers to the name and description. Those pointers must be valid
-during the lifetime of the item. So you should be very careful with names
+The function \fBnew_item\fP allocates a new item and initializes it from the
+\fBname\fP and \fBdescription\fP pointers.
+Please notice that the item stores
+only the pointers to the name and description.
+Those pointers must be valid
+during the lifetime of the item.
+So you should be very careful with names
or descriptions allocated on the stack of some routines.
.br
-The function \fBfree_item\fR de-allocates an item. Please notice that it
+The function \fBfree_item\fP de-allocates an item.
+Please notice that it
is the responsibility of the application to release the memory for the
name or the description of the item.
.SH RETURN VALUE
-The function \fBnew_item\fR returns \fBNULL\fR on error.
-It sets errno according to the function's failure:
+The function \fBnew_item\fP returns \fBNULL\fP on error.
+It sets \fBerrno\fP according to the function's failure:
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
@@ -58,7 +64,7 @@
.B E_SYSTEM_ERROR
System error occurred, e.g., malloc failure.
.PP
-The function \fBfree_item\fR returns one of the following:
+The function \fBfree_item\fP returns one of the following:
.TP 5
.B E_OK
The routine succeeded.
@@ -70,15 +76,14 @@
Item is connected to a menu.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/mitem_opts.3x b/man/mitem_opts.3x
index 37ea552..5a86516 100644
--- a/man/mitem_opts.3x
+++ b/man/mitem_opts.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,52 +27,55 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: mitem_opts.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
-.TH mitem_opts 3X ""
+.\" $Id: mitem_opts.3x,v 1.33 2024/03/16 15:35:01 tom Exp $
+.TH mitem_opts 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmitem_opts\fR \- set and get menu item options
+\fBset_item_opts\fP,
+\fBitem_opts_on\fP,
+\fBitem_opts_off\fP,
+\fBitem_opts\fP \-
+set and get menu item options
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int set_item_opts(ITEM *item, Item_Options opts);
-.br
-int item_opts_on(ITEM *item, Item_Options opts);
-.br
-int item_opts_off(ITEM *item, Item_Options opts);
-.br
-Item_Options item_opts(const ITEM *item);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBint set_item_opts(ITEM *\fIitem\fP, Item_Options \fIopts\fP);
+\fBItem_Options item_opts(const ITEM *\fIitem\fP);
+.PP
+\fBint item_opts_on(ITEM *\fIitem\fP, Item_Options \fIopts\fP);
+\fBint item_opts_off(ITEM *\fIitem\fP, Item_Options \fIopts\fP);
+.fi
.SH DESCRIPTION
-The function \fBset_item_opts\fR sets all the given item's option bits (menu
+The function \fBset_item_opts\fP sets all the given item's option bits (menu
option bits may be logically-OR'ed together).
.PP
-The function \fBitem_opts_on\fR turns on the given option bits, and leaves
+The function \fBitem_opts_on\fP turns on the given option bits, and leaves
others alone.
.PP
-The function \fBitem_opts_off\fR turns off the given option bits, and leaves
+The function \fBitem_opts_off\fP turns off the given option bits, and leaves
others alone.
.PP
-The function \fBitem_opts\fR returns the item's current option bits.
+The function \fBitem_opts\fP returns the item's current option bits.
.PP
-There is only one defined option bit mask, \fBO_SELECTABLE\fR. When this is
-on, the item may be selected during menu processing. This option defaults
+There is only one defined option bit mask, \fBO_SELECTABLE\fP. When this is
+on, the item may be selected during menu processing.
+This option defaults
to on.
.SH RETURN VALUE
-Except for \fBitem_opts\fR, each routine returns one of the following:
+Except for \fBitem_opts\fP, each routine returns one of the following:
.TP 5
.B E_OK
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
+System error occurred (see \fBerrno\fP(3)).
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/mitem_userptr.3x b/man/mitem_userptr.3x
index 7b51ec5..f0eab8b 100644
--- a/man/mitem_userptr.3x
+++ b/man/mitem_userptr.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -27,38 +27,39 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: mitem_userptr.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
-.TH mitem_userptr 3X ""
+.\" $Id: mitem_userptr.3x,v 1.34 2024/03/16 15:35:01 tom Exp $
+.TH mitem_userptr 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmitem_userptr\fR \- associate application data with a menu item
+\fBset_item_userptr\fP,
+\fBitem_userptr\fP \-
+associate application data with a menu item
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int set_item_userptr(ITEM *item, void *userptr);
-.br
-void *item_userptr(const ITEM *item);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBint set_item_userptr(ITEM *\fIitem\fP, void *\fIuserptr\fP);
+\fBvoid *item_userptr(const ITEM *\fIitem\fP);
+.fi
.SH DESCRIPTION
Every menu item has a field that can be used to hold application-specific data
-(that is, the menu-driver code leaves it alone). These functions get and set
+(that is, the menu-driver code leaves it alone).
+These functions get and set
that field.
.SH RETURN VALUE
-The function \fBitem_userptr\fR returns a pointer (possibly \fBNULL\fR).
-It does not set errno.
+The function \fBitem_userptr\fP returns a pointer (possibly \fBNULL\fP).
+It does not set \fBerrno\fP.
.PP
The \fBset_item_userptr\fP always returns \fBE_OK\fP (success).
-.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.PP
The user pointer is a void pointer.
We chose not to leave it as a char pointer for SVr4 compatibility.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/mitem_value.3x b/man/mitem_value.3x
index 57cfc53..daa383d 100644
--- a/man/mitem_value.3x
+++ b/man/mitem_value.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -26,45 +27,46 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: mitem_value.3x,v 1.10 2010/12/04 18:40:45 tom Exp $
-.TH mitem_value 3X ""
+.\" $Id: mitem_value.3x,v 1.32 2024/03/16 15:35:01 tom Exp $
+.TH mitem_value 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmitem_value\fR \- set and get menu item values
+\fBset_item_value\fP,
+\fBitem_value\fP \-
+set and get menu item values
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-int set_item_value(ITEM *item, bool value);
-.br
-bool item_value(const ITEM *item);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBint set_item_value(ITEM *\fIitem\fP, bool \fIvalue\fP);
+\fBbool item_value(const ITEM *\fIitem\fP);
+.fi
.SH DESCRIPTION
-If you turn off the menu option \fBO_ONEVALUE\fR (e.g., with
-\fBset_menu_opts\fR or \fBmenu_opts_off\fR; see \fBmenu_opts\fR(3X)), the menu
+If you turn off the menu option \fBO_ONEVALUE\fP (e.g., with
+\fBset_menu_opts\fP or \fBmenu_opts_off\fP; see \fBmenu_opts\fP(3X)), the menu
becomes multi-valued; that is, more than one item may simultaneously be
selected.
.PP
-In a multi_valued menu, you can used \fBset_item_value\fR to select the
-given menu item (second argument \fBTRUE\fR) or deselect it (second argument
-\fBFALSE\fR).
+In a multi_valued menu, you can used \fBset_item_value\fP to select the
+given menu item (second argument \fBTRUE\fP) or deselect it (second argument
+\fBFALSE\fP).
.SH RETURN VALUE
-The function \fBset_item_value\fR returns one of the following:
+The function \fBset_item_value\fP returns one of the following:
.TP 5
.B E_OK
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fP(3)).
.TP 5
.B E_REQUEST_DENIED
The menu driver could not process the request.
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/mitem_visible.3x b/man/mitem_visible.3x
index 4ff9405..c28c603 100644
--- a/man/mitem_visible.3x
+++ b/man/mitem_visible.3x
@@ -1,6 +1,6 @@
-'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998,2010 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 *
@@ -27,27 +27,28 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: mitem_visible.3x,v 1.7 2010/12/04 18:40:45 tom Exp $
-.TH mitem_visible 3X ""
+.\" $Id: mitem_visible.3x,v 1.27 2024/03/16 15:35:01 tom Exp $
+.TH mitem_visible 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBmitem_visible\fR \- check visibility of a menu item
+\fBitem_visible\fP \-
+check visibility of a menu item
.SH SYNOPSIS
-\fB#include <menu.h>\fR
-.br
-bool item_visible(const ITEM *item);
-.br
+.nf
+\fB#include <menu.h>
+.PP
+\fBbool item_visible(const ITEM *\fIitem\fP);
+.fi
.SH DESCRIPTION
A menu item is visible when it is in the portion of a posted menu that
is mapped onto the screen (if the menu is scrollable, in particular, this
portion will be smaller than the whole menu).
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBmenu\fR(3X).
-.SH NOTES
-The header file \fB<menu.h>\fR automatically includes the header file
-\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
+These routines emulate the System V menu library.
+They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
-Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
-S. Raymond.
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric S. Raymond.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%menu\fP(3X)
diff --git a/man/ncurses.3x b/man/ncurses.3x
index 76d55c0..9aaa7ad 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -1,6 +1,7 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2014,2015 Free Software Foundation, Inc. *
+.\" 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 *
.\" copy of this software and associated documentation files (the *
@@ -27,1267 +28,2234 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: ncurses.3x,v 1.124 2015/08/08 14:57:51 tom Exp $
-.hy 0
-.TH ncurses 3X ""
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: ncurses.3x,v 1.214 2024/04/27 17:55:43 tom Exp $
+.TH ncurses 3X 2024-04-27 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.ds n 5
+.
+.\" Add supplementary paragraph tag on its own line after TP.
+.\" Adapted from TQ (which would produce mandoc warnings).
+.de tQ
+. br
+. ns
+. TP
+..
+.
.ds d @TERMINFO@
.SH NAME
-\fBncurses\fR \- CRT screen handling and optimization package
+\fB\%ncurses\fP \-
+character-cell terminal interface with optimized output
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.br
+.nf
+\fB#include <curses.h>
+.fi
.SH DESCRIPTION
-The \fBncurses\fR library routines give the user a terminal-independent method
-of updating character screens with reasonable optimization.
-This implementation is \*(``new curses\*('' (ncurses) and
-is the approved replacement for
-4.4BSD classic curses, which has been discontinued.
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
+The \*(``new curses\*('' library offers the programmer a
+terminal-independent means of reading keyboard and mouse input and
+updating character-cell terminals with output optimized to minimize
+screen updates.
+.I \%ncurses
+replaces the
+.I curses
+libraries from
+System V Release 4 Unix (\*(``SVr4\*('')
+and
+4.4BSD Unix,
+the development of which ceased in the 1990s.
+This document describes
+.I \%ncurses
+version @NCURSES_MAJOR@.@NCURSES_MINOR@
+(patch @NCURSES_PATCH@).
.PP
-The \fBncurses\fR library emulates the curses library of
-System V Release 4 UNIX,
-and XPG4 (X/Open Portability Guide) curses (also known as XSI curses).
-XSI stands for X/Open System Interfaces Extension.
-The \fBncurses\fR library is freely redistributable in source form.
-Differences from the SVr4
-curses are summarized under the
-\fBEXTENSIONS\fP and \fBPORTABILITY\fP sections below and
-described in detail in the respective
-\fBEXTENSIONS\fP, \fBPORTABILITY\fP and \fBBUGS\fP sections
-of individual man pages.
+.I \%ncurses
+permits control of the terminal screen's contents;
+abstraction and subdivision thereof with
+.I windows
+and
+.IR pads ;
+the reading of terminal input;
+control of terminal input and output options;
+environment query routines;
+color manipulation;
+the definition and use of
+.I "soft label"
+keys;
+.I \%term\%info
+capability access;
+a
+.I termcap
+compatibility interface;
+and an abstraction of the system's API for manipulating the terminal
+(such as \fI\%termios\fP(3)).
.PP
-The \fBncurses\fR library also provides many useful extensions,
-i.e., features which cannot be implemented by a simple add-on library
-but which require access to the internals of the library.
+.I \%ncurses
+implements the standard interface described by
+X/Open Curses Issue\ 7.
+In many behavioral details not standardized by X/Open,
+.I \%ncurses
+emulates the
+.I curses
+library of SVr4 and provides numerous useful extensions.
.PP
-A program using these routines must be linked with the \fB\-lncurses\fR option,
-or (if it has been generated) with the debugging library \fB\-lncurses_g\fR.
-(Your system integrator may also have installed these libraries under
-the names \fB\-lcurses\fR and \fB\-lcurses_g\fR.)
-The ncurses_g library generates trace logs (in a file called 'trace' in the
-current directory) that describe curses actions.
-See also the section on \fBALTERNATE CONFIGURATIONS\fP.
+.I \%ncurses
+man pages employ several sections to clarify matters of usage and
+interoperability with other
+.I curses
+implementations.
+.bP
+\*(``NOTES\*('' describes issues and caveats of which any user of the
+.I \%ncurses
+API should be aware,
+such as limitations on the size of an underlying integral type or the
+availability of a preprocessor macro exclusive of a function definition
+(which prevents its address from being taken).
+This section also describes implementation details that will be
+significant to the programmer but which are not standardized.
+.bP
+\*(``EXTENSIONS\*('' presents
+.I \%ncurses
+innovations beyond the X/Open Curses standard and/or the SVr4
+.I curses
+implementation.
+They are termed
+.I extensions
+to indicate that they cannot be implemented solely by using the library
+API,
+but require access to the library's internal state.
+.bP
+\*(``PORTABILITY\*('' discusses matters
+(beyond the exercise of extensions)
+that should be considered when writing to a
+.I curses
+standard,
+or for multiple implementations.
+.bP
+\*(``HISTORY\*('' examines points of detail in
+.I \%ncurses
+and other
+.I curses
+implementations over the decades of their development,
+particularly where precedent or inertia have frustrated better design
+(and,
+in a few cases,
+where such inertia has been overcome).
.PP
-The \fBncurses\fR package supports: overall screen, window and pad
-manipulation; output to windows and pads; reading terminal input; control over
-terminal and \fBcurses\fR input and output options; environment query
-routines; color manipulation; use of soft label keys; terminfo capabilities;
-and access to low-level terminal-manipulation routines.
-.SS Initialization
+A
+.I curses
+application must be linked with the library;
+use the
+.B \-lncurses
+option to your compiler or linker.
+A debugging version of the library may be available;
+if so,
+link with it using
+.BR \-lncurses_g .
+(Your system integrator may have installed these libraries such that you
+can use the options
+.B \-lcurses
+and
+.BR \-lcurses_g ,
+respectively.)
+The
+.I \%ncurses_g
+library generates trace logs
+(in a file called
+.I \%trace
+in the current directory)
+that describe
+.I \%ncurses
+actions.
+See section \*(``ALTERNATE CONFIGURATIONS\*('' below.
+.SS "Application Structure"
+A
+.I curses
+application uses information from the system locale;
+\fI\%setlocale\fP(3) prepares it for
+.I curses
+library calls.
.PP
-The library uses the locale which the calling program has initialized.
-That is normally done with \fBsetlocale\fP:
-.sp
- \fBsetlocale(LC_ALL, "");\fP
-.sp
-If the locale is not initialized,
-the library assumes that characters are printable as in ISO\-8859\-1,
+.RS 4
+.EX
+setlocale(LC_ALL, "");
+.EE
+.RE
+.PP
+If the locale is not thus initialized,
+the library assumes that characters are printable as in ISO\ 8859-1,
to work with certain legacy programs.
-You should initialize the locale and not rely on specific details of
-the library when the locale has not been setup.
+You should initialize the locale;
+do not expect consistent behavior from the library when the locale has
+not been set up.
.PP
-The function \fBinitscr\fR or \fBnewterm\fR
-must be called to initialize the library
-before any of the other routines that deal with windows
-and screens are used.
-The routine \fBendwin\fR must be called before exiting.
+\fB\%initscr\fP(3X) or \fB\%newterm\fP(3X)
+must be called to initialize
+.I curses
+before use of any functions that deal with windows and screens.
.PP
-To get character-at-a-time input without echoing (most
-interactive, screen oriented programs want this), the following
-sequence should be used:
-.sp
- \fBinitscr(); cbreak(); noecho();\fR
-.sp
-Most programs would additionally use the sequence:
-.sp
- \fBnonl();\fR
- \fBintrflush(stdscr, FALSE);\fR
- \fBkeypad(stdscr, TRUE);\fR
-.sp
-Before a \fBcurses\fR program is run, the tab stops of the terminal
-should be set and its initialization strings, if defined, must be output.
-This can be done by executing the \fB@TPUT@ init\fR command
-after the shell environment variable \fBTERM\fR has been exported.
-\fB@TSET@(1)\fR is usually responsible for doing this.
-[See \fBterminfo\fR(\*n) for further details.]
-.SS Datatypes
+To get character-at-a-time input without echoing\(emmost interactive,
+screen-oriented programs want this\(emuse the following sequence.
.PP
-The \fBncurses\fR library permits manipulation of data structures,
-called \fIwindows\fR, which can be thought of as two-dimensional
-arrays of characters representing all or part of a CRT screen.
-A default window called \fBstdscr\fR, which is the size of the terminal
-screen, is supplied.
-Others may be created with \fBnewwin\fR.
+.RS 4
+.EX
+initscr(); cbreak(); noecho();
+.EE
+.RE
.PP
-Note that \fBcurses\fR does not handle overlapping windows, that's done by
-the \fBpanel\fR(3X) library.
-This means that you can either use
-\fBstdscr\fR or divide the screen into tiled windows and not using
-\fBstdscr\fR at all.
-Mixing the two will result in unpredictable, and undesired, effects.
+Most applications perform further setup as follows.
.PP
-Windows are referred to by variables declared as \fBWINDOW *\fR.
-These data structures are manipulated with routines described here and
-elsewhere in the \fBncurses\fR manual pages.
-Among those, the most basic
-routines are \fBmove\fR and \fBaddch\fR.
-More general versions of
-these routines are included with names beginning with \fBw\fR,
-allowing the user to specify a window.
-The routines not beginning
-with \fBw\fR affect \fBstdscr\fR.
+.RS 4
+.EX
+intrflush(stdscr, FALSE);
+keypad(stdscr, TRUE);
+.EE
+.RE
.PP
-After using routines to manipulate a window, \fBrefresh\fR is called,
-telling \fBcurses\fR to make the user's CRT screen look like
-\fBstdscr\fR.
-The characters in a window are actually of type
-\fBchtype\fR, (character and attribute data) so that other information
-about the character may also be stored with each character.
+A
+.I curses
+program then often enters an event loop of some sort.
+Call \fB\%endwin\fP(3X) before exiting.
+.SS Overview
+A
+.I curses
+library abstracts the terminal screen by representing all or part of it
+as a
+.I \%WINDOW
+data structure.
+A
+.I window
+is a rectangular grid of character cells,
+addressed by row and column coordinates
+.RI ( y ,
+.IR x ),
+with the upper left corner as (0, 0).
+A window called
+.BR \%stdscr ,
+the same size as the terminal screen,
+is always available.
+Create others with \fB\%newwin\fP(3X).
.PP
-Special windows called \fIpads\fR may also be manipulated.
-These are windows
-which are not constrained to the size of the screen and whose contents need not
-be completely displayed.
-See \fBcurs_pad\fR(3X) for more information.
+A
+.I curses
+library does not manage overlapping windows
+(but see below).
+You can either use
+.B \%stdscr
+to manage one screen-filling window,
+or tile the screen into non-overlapping windows and not use
+.B \%stdscr
+at all.
+Mixing the two approaches will result in unpredictable and undesired
+effects.
.PP
-In addition to drawing characters on the screen, video attributes and colors
-may be supported, causing the characters to show up in such modes as
-underlined, in reverse video, or in color on terminals that support such
-display enhancements.
-Line drawing characters may be specified to be output.
-On input, \fBcurses\fR is also able to translate arrow and function keys that
-transmit escape sequences into single values.
-The video attributes, line
-drawing characters, and input values use names, defined in \fB<curses.h>\fR,
-such as \fBA_REVERSE\fR, \fBACS_HLINE\fR, and \fBKEY_LEFT\fR.
-.SS Environment variables
+Functions permit manipulation of a window and the
+.I cursor
+identifying the cell within it at which the next output operation will
+occur.
+Among those,
+the most basic are \fB\%move\fP(3X) and \fB\%addch\fP(3X):
+these place the cursor and write a character to
+.BR \%stdscr ,
+respectively.
.PP
-If the environment variables \fBLINES\fR and \fBCOLUMNS\fR are set, or if the
-program is executing in a window environment, line and column information in
-the environment will override information read by \fIterminfo\fR.
-This would affect a program running in an AT&T 630 layer,
-for example, where the size of a
-screen is changeable (see \fBENVIRONMENT\fR).
+Frequent changes to the terminal screen can cause unpleasant flicker or
+inefficient use of the communication channel to the device,
+so the library does not generally update it automatically.
+Therefore,
+after using
+.I curses
+functions to accumulate a set of desired updates that make sense to
+present together,
+call \fB\%refresh\fP(3X) to tell the library to make the user's screen
+look like \fBstdscr\fP.
+The library
+.\" X/Open Curses Issue 7 assumes some optimization will be done, but
+.\" does not mandate it in any way.
+.I optimizes
+its output by computing a minimal number of operations to mutate the
+screen from its state at the previous refresh to the new one.
+Effective optimization demands accurate information about the terminal
+device:
+the management of such information is the province of the
+\fB\%terminfo\fP(3X) API,
+a feature of every standard
+.I curses
+implementation.
.PP
-If the environment variable \fBTERMINFO\fR is defined, any program using
-\fBcurses\fR checks for a local terminal definition before checking in the
-standard place.
-For example, if \fBTERM\fR is set to \fBatt4424\fR, then the
-compiled terminal definition is found in
-.sp
- \fB\*d/a/att4424\fR.
-.sp
-(The \fBa\fR is copied from the first letter of \fBatt4424\fR to avoid
-creation of huge directories.) However, if \fBTERMINFO\fR is set to
-\fB$HOME/myterms\fR, \fBcurses\fR first checks
-.sp
- \fB$HOME/myterms/a/att4424\fR,
-.sp
-and if that fails, it then checks
-.sp
- \fB\*d/a/att4424\fR.
-.sp
-This is useful for developing experimental definitions or when write
-permission in \fB\*d\fR is not available.
+Special windows called
+.I pads
+may also be manipulated.
+These are windows that are not constrained to the size of the terminal
+screen and whose contents need not be completely displayed.
+See \fB\%curs_pad\fP(3X).
.PP
-The integer variables \fBLINES\fR and \fBCOLS\fR are defined in
-\fB<curses.h>\fR and will be filled in by \fBinitscr\fR with the size of the
-screen.
-The constants \fBTRUE\fR and \fBFALSE\fR have the values \fB1\fR and
-\fB0\fR, respectively.
+In addition to drawing characters on the screen,
+rendering attributes and colors may be supported,
+causing the characters to show up in such modes as underlined,
+in reverse video,
+or in color on terminals that support such display enhancements.
+See \fB\%curs_attr\fP(3X).
.PP
-The \fBcurses\fR routines also define the \fBWINDOW *\fR variable \fBcurscr\fR
-which is used for certain low-level operations like clearing and redrawing a
-screen containing garbage.
-The \fBcurscr\fR can be used in only a few routines.
-.\"
-.SS Routine and Argument Names
-Many \fBcurses\fR routines have two or more versions.
-The routines prefixed with \fBw\fR require a window argument.
-The routines prefixed with \fBp\fR require a pad argument.
-Those without a prefix generally use \fBstdscr\fR.
+.I curses
+predefines constants for a small set of forms-drawing graphics
+corresponding to the DEC Alternate Character Set (ACS),
+a feature of VT100 and other terminals.
+See \fB\%waddch\fP(3X).
.PP
-The routines prefixed with \fBmv\fR require a \fIy\fR and \fIx\fR
-coordinate to move to before performing the appropriate action.
-The \fBmv\fR routines imply a call to \fBmove\fR before the call to the
-other routine.
-The coordinate \fIy\fR always refers to the row (of
-the window), and \fIx\fR always refers to the column.
-The upper left-hand corner is always (0,0), not (1,1).
+.I curses
+is implemented using the operating system's terminal driver;
+keystroke events are received not as scan codes but as byte sequences.
+Graphical keycaps
+(alphanumeric and punctuation keys,
+and the space)
+appear as-is.
+Everything else,
+including the tab,
+enter/return,
+keypad,
+arrow,
+and function keys,
+appears as a control character or a multibyte
+.I "escape sequence."
+.I curses
+translates these into unique
+.I "key codes."
+See \fB\%getch\fP(3X).
.PP
-The routines prefixed with \fBmvw\fR take both a window argument and
-\fIx\fR and \fIy\fR coordinates.
-The window argument is always specified before the coordinates.
+.I \%ncurses
+provides reimplementations of the SVr4 \fBpanel\fP(3X), \fBform\fP(3X),
+and \fBmenu\fP(3X) libraries to ease construction of user interfaces
+with
+.IR curses .
+.SS "Initialization"
+The selection of an appropriate value of
+.I TERM
+in the process environment is essential to correct
+.I curses
+and
+.I \%term\%info
+library operation.
+A well-configured system selects a correct
+.I TERM
+value automatically;
+\fB\%tset\fP(1) may assist with troubleshooting exotic situations.
.PP
-In each case, \fIwin\fR is the window affected, and \fIpad\fR is the
-pad affected; \fIwin\fR and \fIpad\fR are always pointers to type
-\fBWINDOW\fR.
+If you change the terminal type,
+export the
+.I TERM
+environment variable in the shell,
+then run \fB\%tset\fP(1) or the
+.RB \*(`` "@TPUT@ init" \*(''
+command.
+See subsection \*(``Tabs and Initialization\*('' of \fB\%terminfo\fP(5).
.PP
-Option setting routines require a Boolean flag \fIbf\fR with the value
-\fBTRUE\fR or \fBFALSE\fR; \fIbf\fR is always of type \fBbool\fR.
-Most of the data types used in the library routines,
-such as \fBWINDOW\fR, \fBSCREEN\fR, \fBbool\fR, and \fBchtype\fR
-are defined in \fB<curses.h>\fR.
-Types used for the terminfo routines such as
-\fBTERMINAL\fR are defined in \fB<term.h>\fR.
+If the environment variables
+.I \%LINES
+and
+.I \%COLUMNS
+are set,
+or if the
+.I curses
+program is executing in a graphical windowing environment,
+the information obtained thence overrides that obtained by
+.IR \%term\%info .
+An
+.I \%ncurses
+extension supports resizable terminals;
+see \fB\%wresize\fP(3X).
.PP
-This manual page describes functions which may appear in any configuration
+If the environment variable
+.I \%TERMINFO
+is defined,
+a
+.I curses
+program checks first for a terminal type description in the location it
+identifies.
+.I \%TERMINFO
+is useful for developing experimental type descriptions or when write
+permission to
+.I \%\*d
+is not available.
+.PP
+See section \*(``ENVIRONMENT\*('' below.
+.SS "Naming Conventions"
+.I curses
+offers many functions in variant forms using a regular set of
+alternatives to the name of an elemental one.
+Those prefixed with \*(``w\*('' require a
+.I \%WINDOW
+pointer argument;
+those with a \*(``mv\*('' prefix first perform cursor movement using
+\fB\%wmove\fP(3X);
+a \*(``mvw\*('' prefix indicates both.
+The \*(``w\*('' function is typically the elemental one;
+the removal of this prefix usually indicates operation on
+.BR \%stdscr .
+.PP
+Four functions prefixed with \*(``p\*('' require a pad argument.
+.PP
+In function synopses,
+.I \%ncurses
+man pages apply the following names to parameters.
+.PP
+.TS
+center;
+Li L.
+bf \fIbool\fP (\fBTRUE\fP or \fBFALSE\fP)
+c a \fIchar\fP or \fIint\fP
+ch a \fIchtype\fP
+wc a \fIwchar_t\fP or \fIwint_t\fP
+wch a \fIcchar_t\fP
+win pointer to a \fIWINDOW\fP
+pad pointer to a \fIWINDOW\fP that is a pad
+.TE
+.SS "Wide and Non-wide Character Configurations"
+This manual page describes functions that appear in any configuration
of the library.
-There are two common configurations of the library:
-.RS 3
-.TP 5
-.I ncurses
-the "normal" library, which handles 8-bit characters.
-The normal (8-bit) library stores characters combined with attributes
-in \fBchtype\fP data.
+There are two common configurations;
+see section \*(``ALTERNATE CONFIGURATIONS\*('' below.
+.TP 10 \" "ncursesw" + 2n
+.I \%ncurses
+is the library in its \*(``non-wide\*('' configuration,
+handling only eight-bit characters.
+It stores a character combined with attributes in a
+.I \%chtype
+datum,
+which is often an alias of
+.IR int .
.IP
-Attributes alone (no corresponding character) may be stored in \fBchtype\fP
-or the equivalent \fBattr_t\fP data.
-In either case, the data is stored in something like an integer.
+Attributes alone
+(with no corresponding character)
+can be stored in variables of
+.I \%chtype
+or
+.I \%attr_t
+type.
+In either case,
+they are represented as an integral bit mask.
.IP
-Each cell (row and column) in a \fBWINDOW\fP is stored as a \fBchtype\fP.
-.TP 5
-.I ncursesw
-the so-called "wide" library, which handles multibyte characters
-(see the section on \fBALTERNATE CONFIGURATIONS\fP).
-The "wide" library includes all of the calls from the "normal" library.
-It adds about one third more calls using data types which store
-multibyte characters:
-.RS 5
-.TP 5
-.B cchar_t
-corresponds to \fBchtype\fP.
-However it is a structure, because more data is stored than can fit into
-an integer.
-The characters are large enough to require a full integer value \- and there
-may be more than one character per cell.
-The video attributes and color are stored in separate fields of the structure.
-.IP
-Each cell (row and column) in a \fBWINDOW\fP is stored as a \fBcchar_t\fP.
-.TP 5
-.B wchar_t
-stores a "wide" character.
-Like \fBchtype\fP, this may be an integer.
-.TP 5
-.B wint_t
-stores a \fBwchar_t\fP or \fBWEOF\fP \- not the same, though both may have
-the same size.
-.RE
-.IP
-The "wide" library provides new functions which are analogous to
-functions in the "normal" library.
-There is a naming convention which relates many of the normal/wide variants:
-a "_w" is inserted into the name.
-For example, \fBwaddch\fP becomes \fBwadd_wch\fP.
-.RE
+Each cell of a
+.I \%WINDOW
+is stored as a
+.IR \%chtype .
+.TP 10
+.I \%ncursesw
+is the library in its \*(``wide\*('' configuration,
+which handles character encodings requiring a larger data type than
+.I \%char
+(a byte-sized type)
+can represent.
+It adds about one third more calls using additional data types that
+can store such
+.I multibyte
+characters.
+.RS 10 \" same as foregoing tag width
+.TP 9 \" "cchar_t" + 2n
+.I \%cchar_t
+corresponds to the non-wide configuration's
+.IR \%chtype .
+It always a structure type,
+because it stores more data than fit into a standard scalar type.
+A character code may not be representable as a
+.IR \%char ,
+and moreover more than one character may occupy a cell
+(as with accent marks and other diacritics).
+Each character is of type
+.IR \%wchar_t ;
+a complex character contains one spacing character and zero or more
+non-spacing characters
+(see below).
+Attributes and color data are stored in separate fields of the
+structure,
+not combined as in
+.IR \%chtype .
.PP
+Each cell of a
+.I \%WINDOW
+is stored as a
+.IR \%cchar_t .
+.PP
+\fB\%setcchar\fP(3X) and \fB\%getcchar\fP(3X)
+store and retrieve
+.I \%cchar_t
+data.
+The wide library API of
+.I \%ncurses
+depends on two data types standardized by ISO C95.
+.TP 9
+.I \%wchar_t
+stores a wide character.
+Like
+.IR \%chtype ,
+it may be an alias of
+.IR int .
+Depending on the character encoding,
+a wide character may be
+.IR spacing ,
+meaning that it occupies a character cell by itself and typically
+accompanies cursor advancement,
+or
+.IR non-spacing ,
+meaning that it occupies the same cell as a spacing character,
+is often regarded as a \*(``modifier\*('' of the base glyph with which
+it combines,
+and typically does not advance the cursor.
+.TP 9
+.I \%wint_t
+can store a
+.I \%wchar_t
+or the constant
+.BR \%WEOF ,
+analogously to the
+.IR int -sized
+character manipulation functions of ISO C and its constant
+.BR \%EOF .
+.RE
+.IP
+The wide library provides additional functions that complement those in
+the non-wide library where the size of the underlying character type is
+significant.
+A somewhat regular naming convention relates many of the wide variants
+to their non-wide counterparts;
+where a non-wide function name contains \*(``ch\*('' or \*(``str\*('',
+prefix it with \*(``_w\*('' to obtain the wide counterpart.
+For example,
+\fB\%waddch\fP becomes \fB\%wadd_wch\fP.
+(Exceptions that add only \*(``w\*('' comprise
+.BR \%addwstr ,
+.BR \%inwstr ,
+and their variants.)
+.IP
+This convention is inapplicable to some non-wide function names,
+so other transformations are used for the wide configuration:
+the window background management function \*(``bkgd\*('' becomes
+\*(``bkgrnd\*('';
+the window border-drawing and -clearing functions are suffixed with
+\*(``_set\*('';
+and character attribute manipulation functions like
+\*(``attron\*('' become \*(``attr_on\*(''.
.\"
-.SS Routine Name Index
-The following table lists each \fBcurses\fR routine and the name of
-the manual page on which it is described.
-Routines flagged with `*'
-are ncurses-specific, not described by XPG4 or present in SVr4.
+.SS "Function Name Index"
+The following table lists the
+.I curses
+functions provided in the non-wide and wide APIs and the corresponding
+man pages that describe them.
+Those flagged with \*(``*\*(''
+are
+.IR \%ncurses "-specific,"
+neither described by X/Open Curses nor present in SVr4.
.PP
.TS
center tab(/);
-l l
l l .
-\fBcurses\fR Routine Name/Manual Page Name
-=
-COLOR_PAIR/\fBcurs_color\fR(3X)
-PAIR_NUMBER/\fBcurs_attr\fR(3X)
-_nc_free_and_exit/\fBcurs_memleaks\fR(3X)*
-_nc_freeall/\fBcurs_memleaks\fR(3X)*
-_nc_tracebits/\fBcurs_trace\fR(3X)*
-_traceattr/\fBcurs_trace\fR(3X)*
-_traceattr2/\fBcurs_trace\fR(3X)*
-_tracechar/\fBcurs_trace\fR(3X)*
-_tracechtype/\fBcurs_trace\fR(3X)*
-_tracechtype2/\fBcurs_trace\fR(3X)*
-_tracedump/\fBcurs_trace\fR(3X)*
-_tracef/\fBcurs_trace\fR(3X)*
-_tracemouse/\fBcurs_trace\fR(3X)*
-add_wch/\fBcurs_add_wch\fR(3X)
-add_wchnstr/\fBcurs_add_wchstr\fR(3X)
-add_wchstr/\fBcurs_add_wchstr\fR(3X)
-addch/\fBcurs_addch\fR(3X)
-addchnstr/\fBcurs_addchstr\fR(3X)
-addchstr/\fBcurs_addchstr\fR(3X)
-addnstr/\fBcurs_addstr\fR(3X)
-addnwstr/\fBcurs_addwstr\fR(3X)
-addstr/\fBcurs_addstr\fR(3X)
-addwstr/\fBcurs_addwstr\fR(3X)
-assume_default_colors/\fBdefault_colors\fR(3X)*
-attr_get/\fBcurs_attr\fR(3X)
-attr_off/\fBcurs_attr\fR(3X)
-attr_on/\fBcurs_attr\fR(3X)
-attr_set/\fBcurs_attr\fR(3X)
-attroff/\fBcurs_attr\fR(3X)
-attron/\fBcurs_attr\fR(3X)
-attrset/\fBcurs_attr\fR(3X)
-baudrate/\fBcurs_termattrs\fR(3X)
-beep/\fBcurs_beep\fR(3X)
-bkgd/\fBcurs_bkgd\fR(3X)
-bkgdset/\fBcurs_bkgd\fR(3X)
-bkgrnd/\fBcurs_bkgrnd\fR(3X)
-bkgrndset/\fBcurs_bkgrnd\fR(3X)
-border/\fBcurs_border\fR(3X)
-border_set/\fBcurs_border_set\fR(3X)
-box/\fBcurs_border\fR(3X)
-box_set/\fBcurs_border_set\fR(3X)
-can_change_color/\fBcurs_color\fR(3X)
-cbreak/\fBcurs_inopts\fR(3X)
-chgat/\fBcurs_attr\fR(3X)
-clear/\fBcurs_clear\fR(3X)
-clearok/\fBcurs_outopts\fR(3X)
-clrtobot/\fBcurs_clear\fR(3X)
-clrtoeol/\fBcurs_clear\fR(3X)
-color_content/\fBcurs_color\fR(3X)
-color_set/\fBcurs_attr\fR(3X)
-copywin/\fBcurs_overlay\fR(3X)
-curs_set/\fBcurs_kernel\fR(3X)
-curses_version/\fBcurs_extend\fR(3X)*
-def_prog_mode/\fBcurs_kernel\fR(3X)
-def_shell_mode/\fBcurs_kernel\fR(3X)
-define_key/\fBdefine_key\fR(3X)*
-del_curterm/\fBcurs_terminfo\fR(3X)
-delay_output/\fBcurs_util\fR(3X)
-delch/\fBcurs_delch\fR(3X)
-deleteln/\fBcurs_deleteln\fR(3X)
-delscreen/\fBcurs_initscr\fR(3X)
-delwin/\fBcurs_window\fR(3X)
-derwin/\fBcurs_window\fR(3X)
-doupdate/\fBcurs_refresh\fR(3X)
-dupwin/\fBcurs_window\fR(3X)
-echo/\fBcurs_inopts\fR(3X)
-echo_wchar/\fBcurs_add_wch\fR(3X)
-echochar/\fBcurs_addch\fR(3X)
-endwin/\fBcurs_initscr\fR(3X)
-erase/\fBcurs_clear\fR(3X)
-erasechar/\fBcurs_termattrs\fR(3X)
-erasewchar/\fBcurs_termattrs\fR(3X)
-filter/\fBcurs_util\fR(3X)
-flash/\fBcurs_beep\fR(3X)
-flushinp/\fBcurs_util\fR(3X)
-get_wch/\fBcurs_get_wch\fR(3X)
-get_wstr/\fBcurs_get_wstr\fR(3X)
-getattrs/\fBcurs_attr\fR(3X)
-getbegx/\fBcurs_legacy\fR(3X)*
-getbegy/\fBcurs_legacy\fR(3X)*
-getbegyx/\fBcurs_getyx\fR(3X)
-getbkgd/\fBcurs_bkgd\fR(3X)
-getbkgrnd/\fBcurs_bkgrnd\fR(3X)
-getcchar/\fBcurs_getcchar\fR(3X)
-getch/\fBcurs_getch\fR(3X)
-getcurx/\fBcurs_legacy\fR(3X)*
-getcury/\fBcurs_legacy\fR(3X)*
-getmaxx/\fBcurs_legacy\fR(3X)*
-getmaxy/\fBcurs_legacy\fR(3X)*
-getmaxyx/\fBcurs_getyx\fR(3X)
-getmouse/\fBcurs_mouse\fR(3X)*
-getn_wstr/\fBcurs_get_wstr\fR(3X)
-getnstr/\fBcurs_getstr\fR(3X)
-getparx/\fBcurs_legacy\fR(3X)*
-getpary/\fBcurs_legacy\fR(3X)*
-getparyx/\fBcurs_getyx\fR(3X)
-getstr/\fBcurs_getstr\fR(3X)
-getsyx/\fBcurs_kernel\fR(3X)
-getwin/\fBcurs_util\fR(3X)
-getyx/\fBcurs_getyx\fR(3X)
-halfdelay/\fBcurs_inopts\fR(3X)
-has_colors/\fBcurs_color\fR(3X)
-has_ic/\fBcurs_termattrs\fR(3X)
-has_il/\fBcurs_termattrs\fR(3X)
-has_key/\fBcurs_getch\fR(3X)*
-hline/\fBcurs_border\fR(3X)
-hline_set/\fBcurs_border_set\fR(3X)
-idcok/\fBcurs_outopts\fR(3X)
-idlok/\fBcurs_outopts\fR(3X)
-immedok/\fBcurs_outopts\fR(3X)
-in_wch/\fBcurs_in_wch\fR(3X)
-in_wchnstr/\fBcurs_in_wchstr\fR(3X)
-in_wchstr/\fBcurs_in_wchstr\fR(3X)
-inch/\fBcurs_inch\fR(3X)
-inchnstr/\fBcurs_inchstr\fR(3X)
-inchstr/\fBcurs_inchstr\fR(3X)
-init_color/\fBcurs_color\fR(3X)
-init_pair/\fBcurs_color\fR(3X)
-initscr/\fBcurs_initscr\fR(3X)
-innstr/\fBcurs_instr\fR(3X)
-innwstr/\fBcurs_inwstr\fR(3X)
-ins_nwstr/\fBcurs_ins_wstr\fR(3X)
-ins_wch/\fBcurs_ins_wch\fR(3X)
-ins_wstr/\fBcurs_ins_wstr\fR(3X)
-insch/\fBcurs_insch\fR(3X)
-insdelln/\fBcurs_deleteln\fR(3X)
-insertln/\fBcurs_deleteln\fR(3X)
-insnstr/\fBcurs_insstr\fR(3X)
-insstr/\fBcurs_insstr\fR(3X)
-instr/\fBcurs_instr\fR(3X)
-intrflush/\fBcurs_inopts\fR(3X)
-inwstr/\fBcurs_inwstr\fR(3X)
-is_cleared/\fBcurs_opaque\fR(3X)*
-is_idcok/\fBcurs_opaque\fR(3X)*
-is_idlok/\fBcurs_opaque\fR(3X)*
-is_immedok/\fBcurs_opaque\fR(3X)*
-is_keypad/\fBcurs_opaque\fR(3X)*
-is_leaveok/\fBcurs_opaque\fR(3X)*
-is_linetouched/\fBcurs_touch\fR(3X)
-is_nodelay/\fBcurs_opaque\fR(3X)*
-is_notimeout/\fBcurs_opaque\fR(3X)*
-is_pad/\fBcurs_opaque\fR(3X)*
-is_scrollok/\fBcurs_opaque\fR(3X)*
-is_subwin/\fBcurs_opaque\fR(3X)*
-is_syncok/\fBcurs_opaque\fR(3X)*
-is_term_resized/\fBresizeterm\fR(3X)*
-is_wintouched/\fBcurs_touch\fR(3X)
-isendwin/\fBcurs_initscr\fR(3X)
-key_defined/\fBkey_defined\fR(3X)*
-key_name/\fBcurs_util\fR(3X)
-keybound/\fBkeybound\fR(3X)*
-keyname/\fBcurs_util\fR(3X)
-keyok/\fBkeyok\fR(3X)*
-keypad/\fBcurs_inopts\fR(3X)
-killchar/\fBcurs_termattrs\fR(3X)
-killwchar/\fBcurs_termattrs\fR(3X)
-leaveok/\fBcurs_outopts\fR(3X)
-longname/\fBcurs_termattrs\fR(3X)
-mcprint/\fBcurs_print\fR(3X)*
-meta/\fBcurs_inopts\fR(3X)
-mouse_trafo/\fBcurs_mouse\fR(3X)*
-mouseinterval/\fBcurs_mouse\fR(3X)*
-mousemask/\fBcurs_mouse\fR(3X)*
-move/\fBcurs_move\fR(3X)
-mvadd_wch/\fBcurs_add_wch\fR(3X)
-mvadd_wchnstr/\fBcurs_add_wchstr\fR(3X)
-mvadd_wchstr/\fBcurs_add_wchstr\fR(3X)
-mvaddch/\fBcurs_addch\fR(3X)
-mvaddchnstr/\fBcurs_addchstr\fR(3X)
-mvaddchstr/\fBcurs_addchstr\fR(3X)
-mvaddnstr/\fBcurs_addstr\fR(3X)
-mvaddnwstr/\fBcurs_addwstr\fR(3X)
-mvaddstr/\fBcurs_addstr\fR(3X)
-mvaddwstr/\fBcurs_addwstr\fR(3X)
-mvchgat/\fBcurs_attr\fR(3X)
-mvcur/\fBcurs_terminfo\fR(3X)
-mvdelch/\fBcurs_delch\fR(3X)
-mvderwin/\fBcurs_window\fR(3X)
-mvget_wch/\fBcurs_get_wch\fR(3X)
-mvget_wstr/\fBcurs_get_wstr\fR(3X)
-mvgetch/\fBcurs_getch\fR(3X)
-mvgetn_wstr/\fBcurs_get_wstr\fR(3X)
-mvgetnstr/\fBcurs_getstr\fR(3X)
-mvgetstr/\fBcurs_getstr\fR(3X)
-mvhline/\fBcurs_border\fR(3X)
-mvhline_set/\fBcurs_border_set\fR(3X)
-mvin_wch/\fBcurs_in_wch\fR(3X)
-mvin_wchnstr/\fBcurs_in_wchstr\fR(3X)
-mvin_wchstr/\fBcurs_in_wchstr\fR(3X)
-mvinch/\fBcurs_inch\fR(3X)
-mvinchnstr/\fBcurs_inchstr\fR(3X)
-mvinchstr/\fBcurs_inchstr\fR(3X)
-mvinnstr/\fBcurs_instr\fR(3X)
-mvinnwstr/\fBcurs_inwstr\fR(3X)
-mvins_nwstr/\fBcurs_ins_wstr\fR(3X)
-mvins_wch/\fBcurs_ins_wch\fR(3X)
-mvins_wstr/\fBcurs_ins_wstr\fR(3X)
-mvinsch/\fBcurs_insch\fR(3X)
-mvinsnstr/\fBcurs_insstr\fR(3X)
-mvinsstr/\fBcurs_insstr\fR(3X)
-mvinstr/\fBcurs_instr\fR(3X)
-mvinwstr/\fBcurs_inwstr\fR(3X)
-mvprintw/\fBcurs_printw\fR(3X)
-mvscanw/\fBcurs_scanw\fR(3X)
-mvvline/\fBcurs_border\fR(3X)
-mvvline_set/\fBcurs_border_set\fR(3X)
-mvwadd_wch/\fBcurs_add_wch\fR(3X)
-mvwadd_wchnstr/\fBcurs_add_wchstr\fR(3X)
-mvwadd_wchstr/\fBcurs_add_wchstr\fR(3X)
-mvwaddch/\fBcurs_addch\fR(3X)
-mvwaddchnstr/\fBcurs_addchstr\fR(3X)
-mvwaddchstr/\fBcurs_addchstr\fR(3X)
-mvwaddnstr/\fBcurs_addstr\fR(3X)
-mvwaddnwstr/\fBcurs_addwstr\fR(3X)
-mvwaddstr/\fBcurs_addstr\fR(3X)
-mvwaddwstr/\fBcurs_addwstr\fR(3X)
-mvwchgat/\fBcurs_attr\fR(3X)
-mvwdelch/\fBcurs_delch\fR(3X)
-mvwget_wch/\fBcurs_get_wch\fR(3X)
-mvwget_wstr/\fBcurs_get_wstr\fR(3X)
-mvwgetch/\fBcurs_getch\fR(3X)
-mvwgetn_wstr/\fBcurs_get_wstr\fR(3X)
-mvwgetnstr/\fBcurs_getstr\fR(3X)
-mvwgetstr/\fBcurs_getstr\fR(3X)
-mvwhline/\fBcurs_border\fR(3X)
-mvwhline_set/\fBcurs_border_set\fR(3X)
-mvwin/\fBcurs_window\fR(3X)
-mvwin_wch/\fBcurs_in_wch\fR(3X)
-mvwin_wchnstr/\fBcurs_in_wchstr\fR(3X)
-mvwin_wchstr/\fBcurs_in_wchstr\fR(3X)
-mvwinch/\fBcurs_inch\fR(3X)
-mvwinchnstr/\fBcurs_inchstr\fR(3X)
-mvwinchstr/\fBcurs_inchstr\fR(3X)
-mvwinnstr/\fBcurs_instr\fR(3X)
-mvwinnwstr/\fBcurs_inwstr\fR(3X)
-mvwins_nwstr/\fBcurs_ins_wstr\fR(3X)
-mvwins_wch/\fBcurs_ins_wch\fR(3X)
-mvwins_wstr/\fBcurs_ins_wstr\fR(3X)
-mvwinsch/\fBcurs_insch\fR(3X)
-mvwinsnstr/\fBcurs_insstr\fR(3X)
-mvwinsstr/\fBcurs_insstr\fR(3X)
-mvwinstr/\fBcurs_instr\fR(3X)
-mvwinwstr/\fBcurs_inwstr\fR(3X)
-mvwprintw/\fBcurs_printw\fR(3X)
-mvwscanw/\fBcurs_scanw\fR(3X)
-mvwvline/\fBcurs_border\fR(3X)
-mvwvline_set/\fBcurs_border_set\fR(3X)
-napms/\fBcurs_kernel\fR(3X)
-newpad/\fBcurs_pad\fR(3X)
-newterm/\fBcurs_initscr\fR(3X)
-newwin/\fBcurs_window\fR(3X)
-nl/\fBcurs_outopts\fR(3X)
-nocbreak/\fBcurs_inopts\fR(3X)
-nodelay/\fBcurs_inopts\fR(3X)
-noecho/\fBcurs_inopts\fR(3X)
-nofilter/\fBcurs_util\fR(3X)*
-nonl/\fBcurs_outopts\fR(3X)
-noqiflush/\fBcurs_inopts\fR(3X)
-noraw/\fBcurs_inopts\fR(3X)
-notimeout/\fBcurs_inopts\fR(3X)
-overlay/\fBcurs_overlay\fR(3X)
-overwrite/\fBcurs_overlay\fR(3X)
-pair_content/\fBcurs_color\fR(3X)
-pechochar/\fBcurs_pad\fR(3X)
-pnoutrefresh/\fBcurs_pad\fR(3X)
-prefresh/\fBcurs_pad\fR(3X)
-printw/\fBcurs_printw\fR(3X)
-putp/\fBcurs_terminfo\fR(3X)
-putwin/\fBcurs_util\fR(3X)
-qiflush/\fBcurs_inopts\fR(3X)
-raw/\fBcurs_inopts\fR(3X)
-redrawwin/\fBcurs_refresh\fR(3X)
-refresh/\fBcurs_refresh\fR(3X)
-reset_prog_mode/\fBcurs_kernel\fR(3X)
-reset_shell_mode/\fBcurs_kernel\fR(3X)
-resetty/\fBcurs_kernel\fR(3X)
-resize_term/\fBresizeterm\fR(3X)*
-resizeterm/\fBresizeterm\fR(3X)*
-restartterm/\fBcurs_terminfo\fR(3X)
-ripoffline/\fBcurs_kernel\fR(3X)
-savetty/\fBcurs_kernel\fR(3X)
-scanw/\fBcurs_scanw\fR(3X)
-scr_dump/\fBcurs_scr_dump\fR(3X)
-scr_init/\fBcurs_scr_dump\fR(3X)
-scr_restore/\fBcurs_scr_dump\fR(3X)
-scr_set/\fBcurs_scr_dump\fR(3X)
-scrl/\fBcurs_scroll\fR(3X)
-scroll/\fBcurs_scroll\fR(3X)
-scrollok/\fBcurs_outopts\fR(3X)
-set_curterm/\fBcurs_terminfo\fR(3X)
-set_term/\fBcurs_initscr\fR(3X)
-setcchar/\fBcurs_getcchar\fR(3X)
-setscrreg/\fBcurs_outopts\fR(3X)
-setsyx/\fBcurs_kernel\fR(3X)
-setterm/\fBcurs_terminfo\fR(3X)
-setupterm/\fBcurs_terminfo\fR(3X)
-slk_attr/\fBcurs_slk\fR(3X)*
-slk_attr_off/\fBcurs_slk\fR(3X)
-slk_attr_on/\fBcurs_slk\fR(3X)
-slk_attr_set/\fBcurs_slk\fR(3X)
-slk_attroff/\fBcurs_slk\fR(3X)
-slk_attron/\fBcurs_slk\fR(3X)
-slk_attrset/\fBcurs_slk\fR(3X)
-slk_clear/\fBcurs_slk\fR(3X)
-slk_color/\fBcurs_slk\fR(3X)
-slk_init/\fBcurs_slk\fR(3X)
-slk_label/\fBcurs_slk\fR(3X)
-slk_noutrefresh/\fBcurs_slk\fR(3X)
-slk_refresh/\fBcurs_slk\fR(3X)
-slk_restore/\fBcurs_slk\fR(3X)
-slk_set/\fBcurs_slk\fR(3X)
-slk_touch/\fBcurs_slk\fR(3X)
-standend/\fBcurs_attr\fR(3X)
-standout/\fBcurs_attr\fR(3X)
-start_color/\fBcurs_color\fR(3X)
-subpad/\fBcurs_pad\fR(3X)
-subwin/\fBcurs_window\fR(3X)
-syncok/\fBcurs_window\fR(3X)
-term_attrs/\fBcurs_termattrs\fR(3X)
-termattrs/\fBcurs_termattrs\fR(3X)
-termname/\fBcurs_termattrs\fR(3X)
-tgetent/\fBcurs_termcap\fR(3X)
-tgetflag/\fBcurs_termcap\fR(3X)
-tgetnum/\fBcurs_termcap\fR(3X)
-tgetstr/\fBcurs_termcap\fR(3X)
-tgoto/\fBcurs_termcap\fR(3X)
-tigetflag/\fBcurs_terminfo\fR(3X)
-tigetnum/\fBcurs_terminfo\fR(3X)
-tigetstr/\fBcurs_terminfo\fR(3X)
-tiparm/\fBcurs_terminfo\fR(3X)*
-timeout/\fBcurs_inopts\fR(3X)
-touchline/\fBcurs_touch\fR(3X)
-touchwin/\fBcurs_touch\fR(3X)
-tparm/\fBcurs_terminfo\fR(3X)
-tputs/\fBcurs_termcap\fR(3X)
-tputs/\fBcurs_terminfo\fR(3X)
-trace/\fBcurs_trace\fR(3X)*
-typeahead/\fBcurs_inopts\fR(3X)
-unctrl/\fBcurs_util\fR(3X)
-unget_wch/\fBcurs_get_wch\fR(3X)
-ungetch/\fBcurs_getch\fR(3X)
-ungetmouse/\fBcurs_mouse\fR(3X)*
-untouchwin/\fBcurs_touch\fR(3X)
-use_default_colors/\fBdefault_colors\fR(3X)*
-use_env/\fBcurs_util\fR(3X)
-use_extended_names/\fBcurs_extend\fR(3X)*
-use_legacy_coding/\fBlegacy_coding\fR(3X)*
-use_tioctl/\fBcurs_util\fR(3X)
-vid_attr/\fBcurs_terminfo\fR(3X)
-vid_puts/\fBcurs_terminfo\fR(3X)
-vidattr/\fBcurs_terminfo\fR(3X)
-vidputs/\fBcurs_terminfo\fR(3X)
-vline/\fBcurs_border\fR(3X)
-vline_set/\fBcurs_border_set\fR(3X)
-vw_printw/\fBcurs_printw\fR(3X)
-vw_scanw/\fBcurs_scanw\fR(3X)
-vwprintw/\fBcurs_printw\fR(3X)
-vwscanw/\fBcurs_scanw\fR(3X)
-wadd_wch/\fBcurs_add_wch\fR(3X)
-wadd_wchnstr/\fBcurs_add_wchstr\fR(3X)
-wadd_wchstr/\fBcurs_add_wchstr\fR(3X)
-waddch/\fBcurs_addch\fR(3X)
-waddchnstr/\fBcurs_addchstr\fR(3X)
-waddchstr/\fBcurs_addchstr\fR(3X)
-waddnstr/\fBcurs_addstr\fR(3X)
-waddnwstr/\fBcurs_addwstr\fR(3X)
-waddstr/\fBcurs_addstr\fR(3X)
-waddwstr/\fBcurs_addwstr\fR(3X)
-wattr_get/\fBcurs_attr\fR(3X)
-wattr_off/\fBcurs_attr\fR(3X)
-wattr_on/\fBcurs_attr\fR(3X)
-wattr_set/\fBcurs_attr\fR(3X)
-wattroff/\fBcurs_attr\fR(3X)
-wattron/\fBcurs_attr\fR(3X)
-wattrset/\fBcurs_attr\fR(3X)
-wbkgd/\fBcurs_bkgd\fR(3X)
-wbkgdset/\fBcurs_bkgd\fR(3X)
-wbkgrnd/\fBcurs_bkgrnd\fR(3X)
-wbkgrndset/\fBcurs_bkgrnd\fR(3X)
-wborder/\fBcurs_border\fR(3X)
-wborder_set/\fBcurs_border_set\fR(3X)
-wchgat/\fBcurs_attr\fR(3X)
-wclear/\fBcurs_clear\fR(3X)
-wclrtobot/\fBcurs_clear\fR(3X)
-wclrtoeol/\fBcurs_clear\fR(3X)
-wcolor_set/\fBcurs_attr\fR(3X)
-wcursyncup/\fBcurs_window\fR(3X)
-wdelch/\fBcurs_delch\fR(3X)
-wdeleteln/\fBcurs_deleteln\fR(3X)
-wecho_wchar/\fBcurs_add_wch\fR(3X)
-wechochar/\fBcurs_addch\fR(3X)
-wenclose/\fBcurs_mouse\fR(3X)*
-werase/\fBcurs_clear\fR(3X)
-wget_wch/\fBcurs_get_wch\fR(3X)
-wget_wstr/\fBcurs_get_wstr\fR(3X)
-wgetbkgrnd/\fBcurs_bkgrnd\fR(3X)
-wgetch/\fBcurs_getch\fR(3X)
-wgetdelay/\fBcurs_opaque\fR(3X)*
-wgetn_wstr/\fBcurs_get_wstr\fR(3X)
-wgetnstr/\fBcurs_getstr\fR(3X)
-wgetparent/\fBcurs_opaque\fR(3X)*
-wgetscrreg/\fBcurs_opaque\fR(3X)*
-wgetstr/\fBcurs_getstr\fR(3X)
-whline/\fBcurs_border\fR(3X)
-whline_set/\fBcurs_border_set\fR(3X)
-win_wch/\fBcurs_in_wch\fR(3X)
-win_wchnstr/\fBcurs_in_wchstr\fR(3X)
-win_wchstr/\fBcurs_in_wchstr\fR(3X)
-winch/\fBcurs_inch\fR(3X)
-winchnstr/\fBcurs_inchstr\fR(3X)
-winchstr/\fBcurs_inchstr\fR(3X)
-winnstr/\fBcurs_instr\fR(3X)
-winnwstr/\fBcurs_inwstr\fR(3X)
-wins_nwstr/\fBcurs_ins_wstr\fR(3X)
-wins_wch/\fBcurs_ins_wch\fR(3X)
-wins_wstr/\fBcurs_ins_wstr\fR(3X)
-winsch/\fBcurs_insch\fR(3X)
-winsdelln/\fBcurs_deleteln\fR(3X)
-winsertln/\fBcurs_deleteln\fR(3X)
-winsnstr/\fBcurs_insstr\fR(3X)
-winsstr/\fBcurs_insstr\fR(3X)
-winstr/\fBcurs_instr\fR(3X)
-winwstr/\fBcurs_inwstr\fR(3X)
-wmouse_trafo/\fBcurs_mouse\fR(3X)*
-wmove/\fBcurs_move\fR(3X)
-wnoutrefresh/\fBcurs_refresh\fR(3X)
-wprintw/\fBcurs_printw\fR(3X)
-wredrawln/\fBcurs_refresh\fR(3X)
-wrefresh/\fBcurs_refresh\fR(3X)
-wresize/\fBwresize\fR(3X)*
-wscanw/\fBcurs_scanw\fR(3X)
-wscrl/\fBcurs_scroll\fR(3X)
-wsetscrreg/\fBcurs_outopts\fR(3X)
-wstandend/\fBcurs_attr\fR(3X)
-wstandout/\fBcurs_attr\fR(3X)
-wsyncdown/\fBcurs_window\fR(3X)
-wsyncup/\fBcurs_window\fR(3X)
-wtimeout/\fBcurs_inopts\fR(3X)
-wtouchln/\fBcurs_touch\fR(3X)
-wunctrl/\fBcurs_util\fR(3X)
-wvline/\fBcurs_border\fR(3X)
-wvline_set/\fBcurs_border_set\fR(3X)
+\f(BIcurses\fP Function Name/Man Page
+_
+COLOR_PAIR/\fBcurs_color\fP(3X)
+PAIR_NUMBER/\fBcurs_color\fP(3X)
+add_wch/\fBcurs_add_wch\fP(3X)
+add_wchnstr/\fBcurs_add_wchstr\fP(3X)
+add_wchstr/\fBcurs_add_wchstr\fP(3X)
+addch/\fBcurs_addch\fP(3X)
+addchnstr/\fBcurs_addchstr\fP(3X)
+addchstr/\fBcurs_addchstr\fP(3X)
+addnstr/\fBcurs_addstr\fP(3X)
+addnwstr/\fBcurs_addwstr\fP(3X)
+addstr/\fBcurs_addstr\fP(3X)
+addwstr/\fBcurs_addwstr\fP(3X)
+alloc_pair/\fBnew_pair\fP(3X)*
+assume_default_colors/\fBdefault_colors\fP(3X)*
+attr_get/\fBcurs_attr\fP(3X)
+attr_off/\fBcurs_attr\fP(3X)
+attr_on/\fBcurs_attr\fP(3X)
+attr_set/\fBcurs_attr\fP(3X)
+attroff/\fBcurs_attr\fP(3X)
+attron/\fBcurs_attr\fP(3X)
+attrset/\fBcurs_attr\fP(3X)
+baudrate/\fBcurs_termattrs\fP(3X)
+beep/\fBcurs_beep\fP(3X)
+bkgd/\fBcurs_bkgd\fP(3X)
+bkgdset/\fBcurs_bkgd\fP(3X)
+bkgrnd/\fBcurs_bkgrnd\fP(3X)
+bkgrndset/\fBcurs_bkgrnd\fP(3X)
+border/\fBcurs_border\fP(3X)
+border_set/\fBcurs_border_set\fP(3X)
+box/\fBcurs_border\fP(3X)
+box_set/\fBcurs_border_set\fP(3X)
+can_change_color/\fBcurs_color\fP(3X)
+cbreak/\fBcurs_inopts\fP(3X)
+chgat/\fBcurs_attr\fP(3X)
+clear/\fBcurs_clear\fP(3X)
+clearok/\fBcurs_outopts\fP(3X)
+clrtobot/\fBcurs_clear\fP(3X)
+clrtoeol/\fBcurs_clear\fP(3X)
+color_content/\fBcurs_color\fP(3X)
+color_set/\fBcurs_attr\fP(3X)
+copywin/\fBcurs_overlay\fP(3X)
+curs_set/\fBcurs_kernel\fP(3X)
+curses_trace/\fBcurs_trace\fP(3X)*
+curses_version/\fBcurs_extend\fP(3X)*
+def_prog_mode/\fBcurs_kernel\fP(3X)
+def_shell_mode/\fBcurs_kernel\fP(3X)
+define_key/\fBdefine_key\fP(3X)*
+del_curterm/\fBcurs_terminfo\fP(3X)
+delay_output/\fBcurs_util\fP(3X)
+delch/\fBcurs_delch\fP(3X)
+deleteln/\fBcurs_deleteln\fP(3X)
+delscreen/\fBcurs_initscr\fP(3X)
+delwin/\fBcurs_window\fP(3X)
+derwin/\fBcurs_window\fP(3X)
+doupdate/\fBcurs_refresh\fP(3X)
+dupwin/\fBcurs_window\fP(3X)
+echo/\fBcurs_inopts\fP(3X)
+echo_wchar/\fBcurs_add_wch\fP(3X)
+echochar/\fBcurs_addch\fP(3X)
+endwin/\fBcurs_initscr\fP(3X)
+erase/\fBcurs_clear\fP(3X)
+erasechar/\fBcurs_termattrs\fP(3X)
+erasewchar/\fBcurs_termattrs\fP(3X)
+exit_curses/\fBcurs_memleaks\fP(3X)*
+exit_terminfo/\fBcurs_memleaks\fP(3X)*
+extended_color_content/\fBcurs_color\fP(3X)*
+extended_pair_content/\fBcurs_color\fP(3X)*
+extended_slk_color/\fBcurs_slk\fP(3X)*
+filter/\fBcurs_util\fP(3X)
+find_pair/\fBnew_pair\fP(3X)*
+flash/\fBcurs_beep\fP(3X)
+flushinp/\fBcurs_util\fP(3X)
+free_pair/\fBnew_pair\fP(3X)*
+get_escdelay/\fBcurs_threads\fP(3X)*
+get_wch/\fBcurs_get_wch\fP(3X)
+get_wstr/\fBcurs_get_wstr\fP(3X)
+getattrs/\fBcurs_attr\fP(3X)
+getbegx/\fBcurs_legacy\fP(3X)*
+getbegy/\fBcurs_legacy\fP(3X)*
+getbegyx/\fBcurs_getyx\fP(3X)
+getbkgd/\fBcurs_bkgd\fP(3X)
+getbkgrnd/\fBcurs_bkgrnd\fP(3X)
+getcchar/\fBcurs_getcchar\fP(3X)
+getch/\fBcurs_getch\fP(3X)
+getcurx/\fBcurs_legacy\fP(3X)*
+getcury/\fBcurs_legacy\fP(3X)*
+getmaxx/\fBcurs_legacy\fP(3X)*
+getmaxy/\fBcurs_legacy\fP(3X)*
+getmaxyx/\fBcurs_getyx\fP(3X)
+getmouse/\fBcurs_mouse\fP(3X)*
+getn_wstr/\fBcurs_get_wstr\fP(3X)
+getnstr/\fBcurs_getstr\fP(3X)
+getparx/\fBcurs_legacy\fP(3X)*
+getpary/\fBcurs_legacy\fP(3X)*
+getparyx/\fBcurs_getyx\fP(3X)
+getstr/\fBcurs_getstr\fP(3X)
+getsyx/\fBcurs_kernel\fP(3X)
+getwin/\fBcurs_util\fP(3X)
+getyx/\fBcurs_getyx\fP(3X)
+halfdelay/\fBcurs_inopts\fP(3X)
+has_colors/\fBcurs_color\fP(3X)
+has_ic/\fBcurs_termattrs\fP(3X)
+has_il/\fBcurs_termattrs\fP(3X)
+has_key/\fBcurs_getch\fP(3X)*
+has_mouse/\fBcurs_mouse\fP(3X)*
+hline/\fBcurs_border\fP(3X)
+hline_set/\fBcurs_border_set\fP(3X)
+idcok/\fBcurs_outopts\fP(3X)
+idlok/\fBcurs_outopts\fP(3X)
+immedok/\fBcurs_outopts\fP(3X)
+in_wch/\fBcurs_in_wch\fP(3X)
+in_wchnstr/\fBcurs_in_wchstr\fP(3X)
+in_wchstr/\fBcurs_in_wchstr\fP(3X)
+inch/\fBcurs_inch\fP(3X)
+inchnstr/\fBcurs_inchstr\fP(3X)
+inchstr/\fBcurs_inchstr\fP(3X)
+init_color/\fBcurs_color\fP(3X)
+init_extended_color/\fBcurs_color\fP(3X)*
+init_extended_pair/\fBcurs_color\fP(3X)*
+init_pair/\fBcurs_color\fP(3X)
+initscr/\fBcurs_initscr\fP(3X)
+innstr/\fBcurs_instr\fP(3X)
+innwstr/\fBcurs_inwstr\fP(3X)
+ins_nwstr/\fBcurs_ins_wstr\fP(3X)
+ins_wch/\fBcurs_ins_wch\fP(3X)
+ins_wstr/\fBcurs_ins_wstr\fP(3X)
+insch/\fBcurs_insch\fP(3X)
+insdelln/\fBcurs_deleteln\fP(3X)
+insertln/\fBcurs_deleteln\fP(3X)
+insnstr/\fBcurs_insstr\fP(3X)
+insstr/\fBcurs_insstr\fP(3X)
+instr/\fBcurs_instr\fP(3X)
+intrflush/\fBcurs_inopts\fP(3X)
+inwstr/\fBcurs_inwstr\fP(3X)
+is_cbreak/\fBcurs_inopts\fP(3X)*
+is_cleared/\fBcurs_opaque\fP(3X)*
+is_echo/\fBcurs_inopts\fP(3X)*
+is_idcok/\fBcurs_opaque\fP(3X)*
+is_idlok/\fBcurs_opaque\fP(3X)*
+is_immedok/\fBcurs_opaque\fP(3X)*
+is_keypad/\fBcurs_opaque\fP(3X)*
+is_leaveok/\fBcurs_opaque\fP(3X)*
+is_linetouched/\fBcurs_touch\fP(3X)
+is_nl/\fBcurs_inopts\fP(3X)*
+is_nodelay/\fBcurs_opaque\fP(3X)*
+is_notimeout/\fBcurs_opaque\fP(3X)*
+is_pad/\fBcurs_opaque\fP(3X)*
+is_raw/\fBcurs_inopts\fP(3X)*
+is_scrollok/\fBcurs_opaque\fP(3X)*
+is_subwin/\fBcurs_opaque\fP(3X)*
+is_syncok/\fBcurs_opaque\fP(3X)*
+is_term_resized/\fBresizeterm\fP(3X)*
+is_wintouched/\fBcurs_touch\fP(3X)
+isendwin/\fBcurs_initscr\fP(3X)
+key_defined/\fBkey_defined\fP(3X)*
+key_name/\fBcurs_util\fP(3X)
+keybound/\fBkeybound\fP(3X)*
+keyname/\fBcurs_util\fP(3X)
+keyok/\fBkeyok\fP(3X)*
+keypad/\fBcurs_inopts\fP(3X)
+killchar/\fBcurs_termattrs\fP(3X)
+killwchar/\fBcurs_termattrs\fP(3X)
+leaveok/\fBcurs_outopts\fP(3X)
+longname/\fBcurs_termattrs\fP(3X)
+mcprint/\fBcurs_print\fP(3X)*
+meta/\fBcurs_inopts\fP(3X)
+mouse_trafo/\fBcurs_mouse\fP(3X)*
+mouseinterval/\fBcurs_mouse\fP(3X)*
+mousemask/\fBcurs_mouse\fP(3X)*
+move/\fBcurs_move\fP(3X)
+mvadd_wch/\fBcurs_add_wch\fP(3X)
+mvadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
+mvadd_wchstr/\fBcurs_add_wchstr\fP(3X)
+mvaddch/\fBcurs_addch\fP(3X)
+mvaddchnstr/\fBcurs_addchstr\fP(3X)
+mvaddchstr/\fBcurs_addchstr\fP(3X)
+mvaddnstr/\fBcurs_addstr\fP(3X)
+mvaddnwstr/\fBcurs_addwstr\fP(3X)
+mvaddstr/\fBcurs_addstr\fP(3X)
+mvaddwstr/\fBcurs_addwstr\fP(3X)
+mvchgat/\fBcurs_attr\fP(3X)
+mvcur/\fBcurs_terminfo\fP(3X)
+mvdelch/\fBcurs_delch\fP(3X)
+mvderwin/\fBcurs_window\fP(3X)
+mvget_wch/\fBcurs_get_wch\fP(3X)
+mvget_wstr/\fBcurs_get_wstr\fP(3X)
+mvgetch/\fBcurs_getch\fP(3X)
+mvgetn_wstr/\fBcurs_get_wstr\fP(3X)
+mvgetnstr/\fBcurs_getstr\fP(3X)
+mvgetstr/\fBcurs_getstr\fP(3X)
+mvhline/\fBcurs_border\fP(3X)
+mvhline_set/\fBcurs_border_set\fP(3X)
+mvin_wch/\fBcurs_in_wch\fP(3X)
+mvin_wchnstr/\fBcurs_in_wchstr\fP(3X)
+mvin_wchstr/\fBcurs_in_wchstr\fP(3X)
+mvinch/\fBcurs_inch\fP(3X)
+mvinchnstr/\fBcurs_inchstr\fP(3X)
+mvinchstr/\fBcurs_inchstr\fP(3X)
+mvinnstr/\fBcurs_instr\fP(3X)
+mvinnwstr/\fBcurs_inwstr\fP(3X)
+mvins_nwstr/\fBcurs_ins_wstr\fP(3X)
+mvins_wch/\fBcurs_ins_wch\fP(3X)
+mvins_wstr/\fBcurs_ins_wstr\fP(3X)
+mvinsch/\fBcurs_insch\fP(3X)
+mvinsnstr/\fBcurs_insstr\fP(3X)
+mvinsstr/\fBcurs_insstr\fP(3X)
+mvinstr/\fBcurs_instr\fP(3X)
+mvinwstr/\fBcurs_inwstr\fP(3X)
+mvprintw/\fBcurs_printw\fP(3X)
+mvscanw/\fBcurs_scanw\fP(3X)
+mvvline/\fBcurs_border\fP(3X)
+mvvline_set/\fBcurs_border_set\fP(3X)
+mvwadd_wch/\fBcurs_add_wch\fP(3X)
+mvwadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
+mvwadd_wchstr/\fBcurs_add_wchstr\fP(3X)
+mvwaddch/\fBcurs_addch\fP(3X)
+mvwaddchnstr/\fBcurs_addchstr\fP(3X)
+mvwaddchstr/\fBcurs_addchstr\fP(3X)
+mvwaddnstr/\fBcurs_addstr\fP(3X)
+mvwaddnwstr/\fBcurs_addwstr\fP(3X)
+mvwaddstr/\fBcurs_addstr\fP(3X)
+mvwaddwstr/\fBcurs_addwstr\fP(3X)
+mvwchgat/\fBcurs_attr\fP(3X)
+mvwdelch/\fBcurs_delch\fP(3X)
+mvwget_wch/\fBcurs_get_wch\fP(3X)
+mvwget_wstr/\fBcurs_get_wstr\fP(3X)
+mvwgetch/\fBcurs_getch\fP(3X)
+mvwgetn_wstr/\fBcurs_get_wstr\fP(3X)
+mvwgetnstr/\fBcurs_getstr\fP(3X)
+mvwgetstr/\fBcurs_getstr\fP(3X)
+mvwhline/\fBcurs_border\fP(3X)
+mvwhline_set/\fBcurs_border_set\fP(3X)
+mvwin/\fBcurs_window\fP(3X)
+mvwin_wch/\fBcurs_in_wch\fP(3X)
+mvwin_wchnstr/\fBcurs_in_wchstr\fP(3X)
+mvwin_wchstr/\fBcurs_in_wchstr\fP(3X)
+mvwinch/\fBcurs_inch\fP(3X)
+mvwinchnstr/\fBcurs_inchstr\fP(3X)
+mvwinchstr/\fBcurs_inchstr\fP(3X)
+mvwinnstr/\fBcurs_instr\fP(3X)
+mvwinnwstr/\fBcurs_inwstr\fP(3X)
+mvwins_nwstr/\fBcurs_ins_wstr\fP(3X)
+mvwins_wch/\fBcurs_ins_wch\fP(3X)
+mvwins_wstr/\fBcurs_ins_wstr\fP(3X)
+mvwinsch/\fBcurs_insch\fP(3X)
+mvwinsnstr/\fBcurs_insstr\fP(3X)
+mvwinsstr/\fBcurs_insstr\fP(3X)
+mvwinstr/\fBcurs_instr\fP(3X)
+mvwinwstr/\fBcurs_inwstr\fP(3X)
+mvwprintw/\fBcurs_printw\fP(3X)
+mvwscanw/\fBcurs_scanw\fP(3X)
+mvwvline/\fBcurs_border\fP(3X)
+mvwvline_set/\fBcurs_border_set\fP(3X)
+napms/\fBcurs_kernel\fP(3X)
+newpad/\fBcurs_pad\fP(3X)
+newterm/\fBcurs_initscr\fP(3X)
+newwin/\fBcurs_window\fP(3X)
+nl/\fBcurs_inopts\fP(3X)
+nocbreak/\fBcurs_inopts\fP(3X)
+nodelay/\fBcurs_inopts\fP(3X)
+noecho/\fBcurs_inopts\fP(3X)
+nofilter/\fBcurs_util\fP(3X)*
+nonl/\fBcurs_inopts\fP(3X)
+noqiflush/\fBcurs_inopts\fP(3X)
+noraw/\fBcurs_inopts\fP(3X)
+notimeout/\fBcurs_inopts\fP(3X)
+overlay/\fBcurs_overlay\fP(3X)
+overwrite/\fBcurs_overlay\fP(3X)
+pair_content/\fBcurs_color\fP(3X)
+pecho_wchar/\fBcurs_pad\fP(3X)
+pechochar/\fBcurs_pad\fP(3X)
+pnoutrefresh/\fBcurs_pad\fP(3X)
+prefresh/\fBcurs_pad\fP(3X)
+printw/\fBcurs_printw\fP(3X)
+putp/\fBcurs_terminfo\fP(3X)
+putwin/\fBcurs_util\fP(3X)
+qiflush/\fBcurs_inopts\fP(3X)
+raw/\fBcurs_inopts\fP(3X)
+redrawwin/\fBcurs_refresh\fP(3X)
+refresh/\fBcurs_refresh\fP(3X)
+reset_color_pairs/\fBcurs_color\fP(3X)*
+reset_prog_mode/\fBcurs_kernel\fP(3X)
+reset_shell_mode/\fBcurs_kernel\fP(3X)
+resetty/\fBcurs_kernel\fP(3X)
+resize_term/\fBresizeterm\fP(3X)*
+resizeterm/\fBresizeterm\fP(3X)*
+restartterm/\fBcurs_terminfo\fP(3X)
+ripoffline/\fBcurs_kernel\fP(3X)
+savetty/\fBcurs_kernel\fP(3X)
+scanw/\fBcurs_scanw\fP(3X)
+scr_dump/\fBcurs_scr_dump\fP(3X)
+scr_init/\fBcurs_scr_dump\fP(3X)
+scr_restore/\fBcurs_scr_dump\fP(3X)
+scr_set/\fBcurs_scr_dump\fP(3X)
+scrl/\fBcurs_scroll\fP(3X)
+scroll/\fBcurs_scroll\fP(3X)
+scrollok/\fBcurs_outopts\fP(3X)
+set_curterm/\fBcurs_terminfo\fP(3X)
+set_escdelay/\fBcurs_threads\fP(3X)*
+set_tabsize/\fBcurs_threads\fP(3X)*
+set_term/\fBcurs_initscr\fP(3X)
+setcchar/\fBcurs_getcchar\fP(3X)
+setscrreg/\fBcurs_outopts\fP(3X)
+setsyx/\fBcurs_kernel\fP(3X)
+setupterm/\fBcurs_terminfo\fP(3X)
+slk_attr/\fBcurs_slk\fP(3X)*
+slk_attr_off/\fBcurs_slk\fP(3X)
+slk_attr_on/\fBcurs_slk\fP(3X)
+slk_attr_set/\fBcurs_slk\fP(3X)
+slk_attroff/\fBcurs_slk\fP(3X)
+slk_attron/\fBcurs_slk\fP(3X)
+slk_attrset/\fBcurs_slk\fP(3X)
+slk_clear/\fBcurs_slk\fP(3X)
+slk_color/\fBcurs_slk\fP(3X)
+slk_init/\fBcurs_slk\fP(3X)
+slk_label/\fBcurs_slk\fP(3X)
+slk_noutrefresh/\fBcurs_slk\fP(3X)
+slk_refresh/\fBcurs_slk\fP(3X)
+slk_restore/\fBcurs_slk\fP(3X)
+slk_set/\fBcurs_slk\fP(3X)
+slk_touch/\fBcurs_slk\fP(3X)
+slk_wset/\fBcurs_slk\fP(3X)
+standend/\fBcurs_attr\fP(3X)
+standout/\fBcurs_attr\fP(3X)
+start_color/\fBcurs_color\fP(3X)
+subpad/\fBcurs_pad\fP(3X)
+subwin/\fBcurs_window\fP(3X)
+syncok/\fBcurs_window\fP(3X)
+term_attrs/\fBcurs_termattrs\fP(3X)
+termattrs/\fBcurs_termattrs\fP(3X)
+termname/\fBcurs_termattrs\fP(3X)
+tgetent/\fBcurs_termcap\fP(3X)
+tgetflag/\fBcurs_termcap\fP(3X)
+tgetnum/\fBcurs_termcap\fP(3X)
+tgetstr/\fBcurs_termcap\fP(3X)
+tgoto/\fBcurs_termcap\fP(3X)
+tigetflag/\fBcurs_terminfo\fP(3X)
+tigetnum/\fBcurs_terminfo\fP(3X)
+tigetstr/\fBcurs_terminfo\fP(3X)
+timeout/\fBcurs_inopts\fP(3X)
+tiparm/\fBcurs_terminfo\fP(3X)
+tiparm_s/\fBcurs_terminfo\fP(3X)*
+tiscan_s/\fBcurs_terminfo\fP(3X)*
+touchline/\fBcurs_touch\fP(3X)
+touchwin/\fBcurs_touch\fP(3X)
+tparm/\fBcurs_terminfo\fP(3X)
+tputs/\fBcurs_termcap\fP(3X)
+tputs/\fBcurs_terminfo\fP(3X)
+trace/\fBcurs_trace\fP(3X)*
+typeahead/\fBcurs_inopts\fP(3X)
+unctrl/\fBcurs_util\fP(3X)
+unget_wch/\fBcurs_get_wch\fP(3X)
+ungetch/\fBcurs_getch\fP(3X)
+ungetmouse/\fBcurs_mouse\fP(3X)*
+untouchwin/\fBcurs_touch\fP(3X)
+use_default_colors/\fBdefault_colors\fP(3X)*
+use_env/\fBcurs_util\fP(3X)
+use_extended_names/\fBcurs_extend\fP(3X)*
+use_legacy_coding/\fBlegacy_coding\fP(3X)*
+use_screen/\fBcurs_threads\fP(3X)*
+use_tioctl/\fBcurs_util\fP(3X)*
+use_window/\fBcurs_threads\fP(3X)*
+vid_attr/\fBcurs_terminfo\fP(3X)
+vid_puts/\fBcurs_terminfo\fP(3X)
+vidattr/\fBcurs_terminfo\fP(3X)
+vidputs/\fBcurs_terminfo\fP(3X)
+vline/\fBcurs_border\fP(3X)
+vline_set/\fBcurs_border_set\fP(3X)
+vw_printw/\fBcurs_printw\fP(3X)
+vw_scanw/\fBcurs_scanw\fP(3X)
+vwprintw/\fBcurs_printw\fP(3X)
+vwscanw/\fBcurs_scanw\fP(3X)
+wadd_wch/\fBcurs_add_wch\fP(3X)
+wadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
+wadd_wchstr/\fBcurs_add_wchstr\fP(3X)
+waddch/\fBcurs_addch\fP(3X)
+waddchnstr/\fBcurs_addchstr\fP(3X)
+waddchstr/\fBcurs_addchstr\fP(3X)
+waddnstr/\fBcurs_addstr\fP(3X)
+waddnwstr/\fBcurs_addwstr\fP(3X)
+waddstr/\fBcurs_addstr\fP(3X)
+waddwstr/\fBcurs_addwstr\fP(3X)
+wattr_get/\fBcurs_attr\fP(3X)
+wattr_off/\fBcurs_attr\fP(3X)
+wattr_on/\fBcurs_attr\fP(3X)
+wattr_set/\fBcurs_attr\fP(3X)
+wattroff/\fBcurs_attr\fP(3X)
+wattron/\fBcurs_attr\fP(3X)
+wattrset/\fBcurs_attr\fP(3X)
+wbkgd/\fBcurs_bkgd\fP(3X)
+wbkgdset/\fBcurs_bkgd\fP(3X)
+wbkgrnd/\fBcurs_bkgrnd\fP(3X)
+wbkgrndset/\fBcurs_bkgrnd\fP(3X)
+wborder/\fBcurs_border\fP(3X)
+wborder_set/\fBcurs_border_set\fP(3X)
+wchgat/\fBcurs_attr\fP(3X)
+wclear/\fBcurs_clear\fP(3X)
+wclrtobot/\fBcurs_clear\fP(3X)
+wclrtoeol/\fBcurs_clear\fP(3X)
+wcolor_set/\fBcurs_attr\fP(3X)
+wcursyncup/\fBcurs_window\fP(3X)
+wdelch/\fBcurs_delch\fP(3X)
+wdeleteln/\fBcurs_deleteln\fP(3X)
+wecho_wchar/\fBcurs_add_wch\fP(3X)
+wechochar/\fBcurs_addch\fP(3X)
+wenclose/\fBcurs_mouse\fP(3X)*
+werase/\fBcurs_clear\fP(3X)
+wget_wch/\fBcurs_get_wch\fP(3X)
+wget_wstr/\fBcurs_get_wstr\fP(3X)
+wgetbkgrnd/\fBcurs_bkgrnd\fP(3X)
+wgetch/\fBcurs_getch\fP(3X)
+wgetdelay/\fBcurs_opaque\fP(3X)*
+wgetn_wstr/\fBcurs_get_wstr\fP(3X)
+wgetnstr/\fBcurs_getstr\fP(3X)
+wgetparent/\fBcurs_opaque\fP(3X)*
+wgetscrreg/\fBcurs_opaque\fP(3X)*
+wgetstr/\fBcurs_getstr\fP(3X)
+whline/\fBcurs_border\fP(3X)
+whline_set/\fBcurs_border_set\fP(3X)
+win_wch/\fBcurs_in_wch\fP(3X)
+win_wchnstr/\fBcurs_in_wchstr\fP(3X)
+win_wchstr/\fBcurs_in_wchstr\fP(3X)
+winch/\fBcurs_inch\fP(3X)
+winchnstr/\fBcurs_inchstr\fP(3X)
+winchstr/\fBcurs_inchstr\fP(3X)
+winnstr/\fBcurs_instr\fP(3X)
+winnwstr/\fBcurs_inwstr\fP(3X)
+wins_nwstr/\fBcurs_ins_wstr\fP(3X)
+wins_wch/\fBcurs_ins_wch\fP(3X)
+wins_wstr/\fBcurs_ins_wstr\fP(3X)
+winsch/\fBcurs_insch\fP(3X)
+winsdelln/\fBcurs_deleteln\fP(3X)
+winsertln/\fBcurs_deleteln\fP(3X)
+winsnstr/\fBcurs_insstr\fP(3X)
+winsstr/\fBcurs_insstr\fP(3X)
+winstr/\fBcurs_instr\fP(3X)
+winwstr/\fBcurs_inwstr\fP(3X)
+wmouse_trafo/\fBcurs_mouse\fP(3X)*
+wmove/\fBcurs_move\fP(3X)
+wnoutrefresh/\fBcurs_refresh\fP(3X)
+wprintw/\fBcurs_printw\fP(3X)
+wredrawln/\fBcurs_refresh\fP(3X)
+wrefresh/\fBcurs_refresh\fP(3X)
+wresize/\fBwresize\fP(3X)*
+wscanw/\fBcurs_scanw\fP(3X)
+wscrl/\fBcurs_scroll\fP(3X)
+wsetscrreg/\fBcurs_outopts\fP(3X)
+wstandend/\fBcurs_attr\fP(3X)
+wstandout/\fBcurs_attr\fP(3X)
+wsyncdown/\fBcurs_window\fP(3X)
+wsyncup/\fBcurs_window\fP(3X)
+wtimeout/\fBcurs_inopts\fP(3X)
+wtouchln/\fBcurs_touch\fP(3X)
+wunctrl/\fBcurs_util\fP(3X)
+wvline/\fBcurs_border\fP(3X)
+wvline_set/\fBcurs_border_set\fP(3X)
.TE
+.PP
+.IR \%ncurses 's
+.I "screen-pointer extension"
+adds additional functions corresponding to many of the above,
+each with an \*(``_sp\*('' suffix;
+see \fBcurs_sp_funcs\fP(3X).
+.PP
+The availability of some extensions is configurable when
+.I \%ncurses
+is compiled;
+see sections \*(``ALTERNATE CONFIGURATIONS\*('' and \*(``EXTENSIONS\*(''
+below.
.SH RETURN VALUE
-Routines that return an integer return \fBERR\fR upon failure and an
-integer value other than \fBERR\fR upon successful completion, unless
-otherwise noted in the routine descriptions.
-.PP
-As a general rule, routines check for null pointers passed as parameters,
-and handle this as an error.
-.PP
-All macros return the value of the \fBw\fR version, except \fBsetscrreg\fR,
-\fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and \fBgetmaxyx\fR.
-The return values of
-\fBsetscrreg\fR,
-\fBwsetscrreg\fR,
-\fBgetyx\fR,
-\fBgetbegyx\fR, and
-\fBgetmaxyx\fR are undefined (i.e., these should not be used as the
-right-hand side of assignment statements).
-.PP
-Routines that return pointers return \fBNULL\fR on error.
+Unless otherwise noted,
+functions that return an integer return
+.B OK
+on success and
+.B ERR
+on failure.
+Functions that return pointers return
+.B NULL
+on failure.
+Typically,
+.I \%ncurses
+treats a null pointer passed as a function parameter as a failure.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH ENVIRONMENT
-The following environment symbols are useful for customizing the
-runtime behavior of the \fBncurses\fR library.
-The most important ones have been already discussed in detail.
-.SS CC
-When set, change occurrences of the command_character
-(i.e., the \fBcmdch\fP capability)
-of the loaded terminfo entries to the value of this variable.
-Very few terminfo entries provide this feature.
+The following symbols from the process environment customize the
+runtime behavior of
+.I \%ncurses
+applications.
+The library may be configured to disregard the variables
+.IR \%TERMINFO ,
+.IR \%TERMINFO_DIRS ,
+.IR \%TERMPATH ,
+and
+.IR HOME ,
+if the user is the superuser (root),
+or the application uses \fI\%setuid\fP(2) or \fI\%setgid\fP(2).
+.SS "\fIBAUDRATE\fP"
+The debugging library checks this variable when the application has
+redirected output to a file.
+Its integral value is used for the baud rate.
+If that value is absent or invalid,
+.I \%ncurses
+uses 9600.
+This feature allows testers to construct repeatable test cases
+that take into account optimization decisions that depend on baud rate.
+.SS "\fICC\fP (command character)"
+When set,
+the
+.B \%command_character
+.RB ( \%cmdch )
+capability value of loaded
+.I \%term\%info
+entries changes to the value of this variable.
+Very few
+.I \%term\%info
+entries provide this feature.
.PP
Because this name is also used in development environments to represent
-the C compiler's name, \fBncurses\fR ignores it if it does not happen to
-be a single character.
-.SS BAUDRATE
-The debugging library checks this environment variable when the application
-has redirected output to a file.
-The variable's numeric value is used for the baudrate.
-If no value is found, \fBncurses\fR uses 9600.
-This allows testers to construct repeatable test-cases
-that take into account costs that depend on baudrate.
-.SS COLUMNS
-Specify the width of the screen in characters.
+the C compiler's name,
+.I \%ncurses
+ignores its value if it is not one character in length.
+.SS "\fICOLUMNS\fP"
+This variable specifies the width of the screen in characters.
Applications running in a windowing environment usually are able to
obtain the width of the window in which they are executing.
-If neither the \fBCOLUMNS\fP value nor the terminal's screen size is available,
-\fBncurses\fR uses the size which may be specified in the terminfo database
-(i.e., the \fBcols\fR capability).
+If
+.I \%COLUMNS
+is not defined and the terminal's screen size is not available from the
+terminal driver,
+.I \%ncurses
+uses the size specified by the
+.B \%columns
+.RB ( \%cols )
+capability of the terminal type's entry in the
+.I \%term\%info
+database,
+if any.
.PP
-It is important that your application use a correct size for the screen.
-This is not always possible because your application may be
-running on a host which does not honor NAWS (Negotiations About Window
-Size), or because you are temporarily running as another user.
-However, setting \fBCOLUMNS\fP and/or \fBLINES\fP overrides the library's
-use of the screen size obtained from the operating system.
+It is important that your application use the correct screen size.
+Automatic detection thereof is not always possible because an
+application may be running on a host that does not honor NAWS
+(Negotiations About Window Size)
+or as a different user ID than the owner of the terminal device file.
+Setting
+.I \%COLUMNS
+and/or
+.I \%LINES
+overrides the library's use of the screen size obtained from the
+operating system.
.PP
-Either \fBCOLUMNS\fP or \fBLINES\fP symbols may be specified independently.
-This is mainly useful to circumvent legacy misfeatures of terminal descriptions,
-e.g., xterm which commonly specifies a 65 line screen.
-For best results, \fBlines\fR and \fBcols\fR should not be specified in
-a terminal description for terminals which are run as emulations.
+The
+.I \%COLUMNS
+and
+.I \%LINES
+variables may be specified independently.
+This property is useful to circumvent misfeatures of legacy terminal
+type descriptions;
+\fI\%xterm\fP(1) descriptions specifying 65 lines were once notorious.
+For best results,
+avoid specifying
+.B cols
+and
+.B lines
+capability codes in
+.I \%term\%info
+descriptions of terminal emulators.
.PP
-Use the \fBuse_env\fR function to disable all use of external environment
-(but not including system calls) to determine the screen size.
-Use the \fBuse_tioctl\fR function to update \fBCOLUMNS\fP or \fBLINES\fP
-to match the screen size obtained from system calls or the terminal database.
-.SS ESCDELAY
-Specifies the total time, in milliseconds, for which ncurses will
-await a character sequence, e.g., a function key.
-The default value, 1000 milliseconds, is enough for most uses.
-However, it is made a variable to accommodate unusual applications.
+\fBuse_env\fP(3X) can disable use of the process environment
+in determining the screen size.
+\fBuse_tioctl\fP(3X) can update
+.I \%COLUMNS
+and
+.I \%LINES
+to match the screen size obtained from system calls or the terminal
+database.
+.SS "\fIESCDELAY\fP"
+For
+.I curses
+to distinguish the ESC character resulting from a user's press of the
+\*(``Escape\*('' key on the input device from one beginning an
+.I "escape sequence"
+(as commonly produced by function keys),
+it waits after receiving the escape character to see if further
+characters are available on the input stream within a short interval.
+A global variable
+.B \%ESCDELAY
+stores this interval in milliseconds.
+The default value of 1000
+(one second)
+is adequate for most uses.
+This environment variable overrides it.
.PP
The most common instance where you may wish to change this value
-is to work with slow hosts, e.g., running on a network.
-If the host cannot read characters rapidly enough, it will have the same
-effect as if the terminal did not send characters rapidly enough.
-The library will still see a timeout.
+is to work with a remote host over a slow communication channel.
+If the host running a
+.I curses
+application does not receive the characters of an escape sequence in a
+timely manner,
+the library can interpret them as multiple key stroke events.
.PP
-Note that xterm mouse events are built up from character sequences
-received from the xterm.
-If your application makes heavy use of multiple-clicking, you may
-wish to lengthen this default value because the timeout applies
-to the composed multi-click event as well as the individual clicks.
+\fI\%xterm\fP(1) mouse events are a form of escape sequence;
+therefore,
+if your application makes heavy use of multiple-clicking,
+you may wish to lengthen the default value because the delay applies
+to the composite multi-click event as well as the individual clicks.
.PP
-In addition to the environment variable,
-this implementation provides a global variable with the same name.
-Portable applications should not rely upon the presence of ESCDELAY
+Portable applications should not rely upon the presence of
+.B \%ESCDELAY
in either form,
but setting the environment variable rather than the global variable
does not create problems when compiling an application.
-.SS HOME
-Tells \fBncurses\fR where your home directory is.
-That is where it may read and write auxiliary terminal descriptions:
.PP
-$HOME/.termcap
-.br
-$HOME/.terminfo
-.SS LINES
-Like COLUMNS, specify the height of the screen in characters.
-See COLUMNS for a detailed description.
-.SS MOUSE_BUTTONS_123
-This applies only to the OS/2 EMX port.
-It specifies the order of buttons on the mouse.
-OS/2 numbers a 3-button mouse inconsistently from other
-platforms:
-.sp
-1 = left
-.br
-2 = right
-.br
-3 = middle.
-.sp
-This variable lets you customize the mouse.
-The variable must be three numeric digits 1\-3 in any order, e.g., 123 or 321.
-If it is not specified, \fBncurses\fR uses 132.
-.SS NCURSES_ASSUMED_COLORS
-Override the compiled-in assumption that the
-terminal's default colors are white-on-black
-(see \fBdefault_colors\fR(3X)).
-You may set the foreground and background color values with this environment
-variable by proving a 2-element list: foreground,background.
-For example, to tell ncurses to not assume anything
-about the colors, set this to "\-1,\-1".
-To make it green-on-black, set it to "2,0".
-Any positive value from zero to the terminfo \fBmax_colors\fR value is allowed.
-.SS NCURSES_CONSOLE2
-This applies only to the MinGW port of ncurses.
+If \fB\%keypad\fP(3X) is disabled for the
+.I curses
+window receiving input,
+a program must disambiguate escape sequences itself.
+.SS "\fIHOME\fP"
+.I \%ncurses
+may read and write auxiliary terminal descriptions in
+.I \%.termcap
+and
+.I \%.terminfo
+files in the user's home directory.
+.SS "\fILINES\fP"
+This counterpart to
+.I \%COLUMNS
+specifies the height of the screen in characters.
+The corresponding
+.I \%term\%info
+capability and code is
+.BR \%lines .
+See the description of the
+.I \%COLUMNS
+variable above.
+.SS "\fIMOUSE_BUTTONS_123\fP"
+(OS/2 EMX port only)
+OS/2 numbers a three-button mouse inconsistently with other platforms,
+such that 1 is the left button,
+2 the right,
+and 3 the middle.
+This variable customizes the mouse button numbering.
+Its value must be three digits 1\-3 in any order.
+By default,
+.I \%ncurses
+assumes a numbering of \*(``132\*(''.
+.SS "\fINCURSES_ASSUMED_COLORS\fP"
+If set,
+this variable overrides the
+.I \%ncurses
+library's compiled-in assumption that the terminal's default colors are
+white on black;
+see \fB\%default_colors\fP(3X).
+Set the foreground and background color values with this environment
+variable by assigning it two integer values separated by a comma,
+indicating foregound and background color numbers,
+respectively.
.PP
-The \fBConsole2\fP program's handling of the Microsoft Console API call
-\fBCreateConsoleScreenBuffer\fP is defective.
-Applications which use this will hang.
-However, it is possible to simulate the action of this call by
-mapping coordinates,
+For example,
+to tell
+.I \%ncurses
+not to assume anything about the colors,
+use a value of \*(``\-1,\-1\*(''.
+To make the default color scheme green on black,
+use \*(``2,0\*(''.
+.I \%ncurses
+accepts integral values from \-1 up to the value of the
+.I \%term\%info
+.B \%max_colors
+.RB ( colors )
+capability.
+.SS "\fINCURSES_CONSOLE2\fP"
+(MinGW port only)
+The
+.I \%Console2
+.\" https://www.hanselman.com/blog/console2-a-better-windows-command-prompt
+program defectively handles the Microsoft Console API call
+.IR \%Create\%Console\%Screen\%Buffer .
+Applications that use it will hang.
+However,
+it is possible to simulate the action of this call by mapping
+coordinates,
explicitly saving and restoring the original screen contents.
-Setting the environment variable \fBNCGDB\fP has the same effect.
-.SS NCURSES_GPM_TERMS
-This applies only to ncurses configured to use the GPM interface.
-.PP
-If present,
-the environment variable is a list of one or more terminal names
-against which the TERM environment variable is matched.
-Setting it to an empty value disables the GPM interface;
-using the built-in support for xterm, etc.
-.PP
-If the environment variable is absent,
-ncurses will attempt to open GPM if TERM contains "linux".
-.SS NCURSES_NO_HARD_TABS
-\fBNcurses\fP may use tabs as part of the cursor movement optimization.
+Setting the environment variable
+.I \%NCGDB
+has the same effect.
+.SS "\fINCURSES_GPM_TERMS\fP"
+(Linux only)
+When
+.I \%ncurses
+is configured to use the GPM interface,
+this variable may list one or more terminal names
+against which the
+.I TERM
+variable
+(see below)
+is matched.
+An empty value disables the GPM interface,
+using
+.IR \%ncurses 's
+built-in support for \fIxterm\fP(1) mouse protocols instead.
+If the variable is absent,
+.I \%ncurses
+attempts to open GPM if
+.I TERM
+contains \*(``linux\*(''.
+.SS "\fINCURSES_NO_HARD_TABS\fP"
+.I \%ncurses
+may use tab characters in cursor movement optimization.
In some cases,
-your terminal driver may not handle these properly.
-Set this environment variable to disable the feature.
-You can also adjust your \fBstty\fP settings to avoid the problem.
-NCURSES_NO_MAGIC_COOKIE
-Some terminals use a magic-cookie feature which requires special handling
-to make highlighting and other video attributes display properly.
-You can suppress the highlighting entirely for these terminals by
-setting this environment variable.
-.SS NCURSES_NO_PADDING
-Most of the terminal descriptions in the terminfo database are written
-for real "hardware" terminals.
-Many people use terminal emulators
-which run in a windowing environment and use curses-based applications.
-Terminal emulators can duplicate
-all of the important aspects of a hardware terminal, but they do not
-have the same limitations.
-The chief limitation of a hardware terminal from the standpoint
-of your application is the management of dataflow, i.e., timing.
+your terminal driver may not handle them properly.
+Set this environment variable to any value to disable the feature.
+You can also adjust your \fI\%stty\fP(1) settings to avoid the problem.
+.SS "\fINCURSES_NO_MAGIC_COOKIE\fP"
+Many terminals store video attributes as a property of a character cell,
+as
+.I curses
+does.
+Historically,
+some recorded changes in video attributes as data that logically
+.I occupies
+character cells on the display,
+switching attributes on or off,
+similarly to tags in a markup language;
+these are termed \*(``magic cookies\*('',
+and must be subsequently overprinted.
+If the
+.I \%term\%info
+entry for your terminal type does not adequately describe its handling
+of magic cookies,
+set this variable to any value to instruct
+.I \%ncurses
+to disable attributes entirely.
+.SS "\fINCURSES_NO_PADDING\fP"
+Most terminal type descriptions in the
+.I \%term\%info
+database detail hardware devices.
+Many people use
+.IR curses -based
+applications in terminal emulator programs that run in a windowing
+environment.
+These programs can duplicate all of the important features of a hardware
+terminal,
+but often lack their limitations.
+Chief among these absent drawbacks is the problem of data flow
+management;
+that is,
+limiting the speed of communication to what the hardware could handle.
Unless a hardware terminal is interfaced into a terminal concentrator
(which does flow control),
-it (or your application) must manage dataflow, preventing overruns.
-The cheapest solution (no hardware cost)
-is for your program to do this by pausing after
-operations that the terminal does slowly, such as clearing the display.
+an application must manage flow control itself to prevent overruns and
+data loss.
.PP
-As a result, many terminal descriptions (including the vt100)
-have delay times embedded.
-You may wish to use these descriptions,
-but not want to pay the performance penalty.
-.PP
-Set the NCURSES_NO_PADDING environment variable to disable all but mandatory
-padding.
-Mandatory padding is used as a part of special control
-sequences such as \fIflash\fR.
-.SS NCURSES_NO_SETBUF
-This setting is obsolete.
-Before changes
-.RS 3
-.bP
-started with 5.9 patch 20120825
-and
-.bP
-continued
-though 5.9 patch 20130126
-.RE
-.PP
-\fBncurses\fR enabled buffered output during terminal initialization.
-This was done (as in SVr4 curses) for performance reasons.
-For testing purposes, both of \fBncurses\fR and certain applications,
+A solution that comes at no hardware cost is for an application to pause
+after directing a terminal to execute an operation that it performs
+slowly,
+such as clearing the display.
+Many terminal type descriptions,
+including that for the VT100,
+embed delay specifications in capabilities.
+You may wish to use these terminal descriptions without paying the
+performance penalty.
+Set
+.I \%NCURSES_NO_PADDING
+to any value to disable all but mandatory padding.
+Mandatory padding is used by such terminal capabilities as
+.B \%flash_screen
+.RB ( flash ).
+.SS "\fINCURSES_NO_SETBUF\fP"
+(Obsolete)
+Prior to internal changes developed in
+.I \%ncurses
+5.9
+(patches 20120825 through 20130126),
+the library used \fI\%setbuf\fP(3) to enable fully buffered output when
+initializing the terminal.
+This was done,
+as in SVr4
+.IR curses ,
+to increase performance.
+For testing purposes,
+both of
+.I \%ncurses
+and of certain applications,
this feature was made optional.
-Setting the NCURSES_NO_SETBUF variable
-disabled output buffering, leaving the output in the original (usually
-line buffered) mode.
+Setting this variable disabled output buffering,
+leaving the output stream in the original
+(usually line-buffered)
+mode.
.PP
-In the current implementation,
-ncurses performs its own buffering and does not require this workaround.
-It does not modify the buffering of the standard output.
+Nowadays,
+.I \%ncurses
+performs its own buffering and does not require this workaround;
+it does not modify the buffering of the standard output stream.
+This approach makes signal handling,
+as for interrupts,
+more robust.
+A drawback is that certain unconventional programs mixed
+\fI\%stdio\fP(3) calls with
+.I \%ncurses
+calls and (usually)
+got the behavior they expected.
+This is no longer the case;
+.I \%ncurses
+does not write to the standard output file descriptor through a
+.IR stdio -buffered
+stream.
.PP
-The reason for the change was to make the behavior for interrupts and
-other signals more robust.
-One drawback is that certain nonconventional programs would mix
-ordinary stdio calls with ncurses calls and (usually) work.
-This is no longer possible since ncurses is not using
-the buffered standard output but its own output (to the same file descriptor).
-As a special case, the low-level calls such as \fBputp\fP still use the
-standard output.
-But high-level curses calls do not.
-.SS NCURSES_NO_UTF8_ACS
-During initialization, the \fBncurses\fR library
-checks for special cases where VT100 line-drawing (and the corresponding
-alternate character set capabilities) described in the terminfo are known
-to be missing.
-Specifically, when running in a UTF\-8 locale,
-the Linux console emulator and the GNU screen program ignore these.
-Ncurses checks the TERM environment variable for these.
-For other special cases, you should set this environment variable.
-Doing this tells ncurses to use Unicode values which correspond to
-the VT100 line-drawing glyphs.
-That works for the special cases cited,
-and is likely to work for terminal emulators.
+As a special case,
+low-level API calls such as \fB\%putp\fP(3X) still use the
+standard output stream.
+High-level
+.I curses
+calls such as \fB\%printw\fP(3X) do not.
+.SS "\fINCURSES_NO_UTF8_ACS\fP"
+At initialization,
+.I \%ncurses
+inspects the
+.I TERM
+environment variable for special cases where VT100 forms-drawing
+characters
+(and the corresponding alternate character set
+.I \%term\%info
+capabilities)
+are known to be unsupported by terminal types that otherwise claim VT100
+compatibility.
+Specifically,
+when running in a UTF-8 locale,
+the Linux virtual console device and the GNU \fI\%screen\fP(1)
+program ignore them.
+Set this variable to a nonzero value to instruct
+.I \%ncurses
+that the terminal's ACS support is broken;
+the library then outputs Unicode code points that correspond to the
+forms-drawing
+characters.
+Set it to zero
+(or a non-integer)
+to disable the special check for terminal type names matching
+\*(``linux\*('' or \*(``screen\*('',
+directing
+.I \%ncurses
+to assume that the ACS feature works if the terminal type description
+advertises it.
.PP
-When setting this variable, you should set it to a nonzero value.
-Setting it to zero (or to a nonnumber)
-disables the special check for "linux" and "screen".
+As an alternative to use of this variable,
+.I \%ncurses
+checks for an extended
+.I \%term\%info
+numeric capability \fBU8\fP
+that can be compiled using
+.RB \*(`` "@TIC@ \-x" \*(''.
+Examples follow.
.PP
-As an alternative to the environment variable,
-ncurses checks for an extended terminfo capability \fBU8\fP.
-This is a numeric capability which can be compiled using \fB@TIC@\ \-x\fP.
-For example
.RS 3
-.ft CW
-.sp
-.nf
+.EX
# linux console, if patched to provide working
-# VT100 shift-in/shift-out, with corresponding font.
-linux-vt100|linux console with VT100 line-graphics,
+# VT100 shift\-in/shift\-out, with corresponding font.
+linux\-vt100|linux console with VT100 line\-graphics,
U8#0, use=linux,
-.sp
+\&
# uxterm with vt100Graphics resource set to false
-xterm-utf8|xterm relying on UTF-8 line-graphics,
+xterm\-utf8|xterm relying on UTF\-8 line\-graphics,
U8#1, use=xterm,
-.fi
-.ft
+.EE
.RE
.PP
-The name "U8" is chosen to be two characters,
-to permit it to be used by applications that use ncurses'
-termcap interface.
-.SS NCURSES_TRACE
-During initialization, the \fBncurses\fR debugging library
-checks the NCURSES_TRACE environment variable.
-If it is defined, to a numeric value, \fBncurses\fR calls the \fBtrace\fR
-function, using that value as the argument.
+The two-character name \*(``U8\*('' was chosen to permit its use via
+.IR \%ncurses 's
+.I termcap
+interface.
+.SS "\fINCURSES_TRACE\fP"
+At initialization,
+.I \%ncurses
+(in its debugging configuration)
+checks for this variable's presence.
+If defined with an integral value,
+the library calls \fB\%curses_trace\fP(3X) with that value as the
+argument.
+.SS "\fITERM\fP"
+The
+.I TERM
+variable denotes the terminal type.
+Each is distinct,
+though many are similar.
+It is commonly set by terminal emulators to help applications find a
+workable terminal description.
+Some choose a popular approximation such as \*(``ansi\*('',
+\*(``vt100\*('', or \*(``xterm\*('' rather than an exact fit to their
+capabilities.
+Not infrequently,
+an application will have problems with that approach;
+for example,
+a key stroke may not operate correctly,
+or produce no effect but seeming garbage characters on the screen.
.PP
-The argument values, which are defined in \fBcurses.h\fR, provide several
-types of information.
-When running with traces enabled, your application will write the
-file \fBtrace\fR to the current directory.
+Setting
+.I TERM
+has no effect on hardware operation;
+it affects the way applications communicate with the terminal.
+Likewise,
+as a general rule
+(\fIxterm\fP(1) being a rare exception),
+terminal emulators that allow you to specify
+.I TERM
+as a parameter or configuration value do not change their behavior to
+match that setting.
+.SS "\fITERMCAP\fP"
+If
+.I \%ncurses
+is configured with
+.I termcap
+support,
+it checks for a terminal type description in
+.I termcap
+format if one in
+.I \%term\%info
+format is not available.
+Setting this variable directs
+.I \%ncurses
+to ignore the usual
+.I termcap
+database location,
+.IR \%/etc/termcap ;
+see
+.I \%TERMPATH
+below.
+.I \%TERMCAP
+should contain either a terminal description
+(with newlines stripped out),
+or a file name indicating where the information required by the
+.I TERM
+environment variable is stored.
+.SS "\fITERMINFO\fP"
+.I \%ncurses
+can be configured to read terminal type description databases in various
+locations using different formats.
+This variable overrides the default location.
+.bP
+Descriptions in
+.I \%term\%info
+format are normally stored in a directory tree using subdirectories
+named by the common first letters of the terminal types named therein.
+This is the scheme used in System\ V.
+.bP
+If
+.I \%ncurses
+is configured to use hashed databases,
+then
+.I \%TERM\%INFO
+may name its location,
+such as
+.IR \%/usr/share/terminfo.db ,
+rather than
+.IR \%/usr/share/terminfo/ .
.PP
-See \fBcurs_trace\fP(3X) for more information.
-.SS TERM
-Denotes your terminal type.
-Each terminal type is distinct, though many are similar.
-.PP
-\fBTERM\fP is commonly set by terminal emulators to help
-applications find a workable terminal description.
-Some of those choose a popular approximation, e.g.,
-\*(``ansi\*('', \*(``vt100\*('', \*(``xterm\*('' rather than an exact fit.
-Not infrequently, your application will have problems with that approach,
-e.g., incorrect function-key definitions.
-.PP
-If you set \fBTERM\fP in your environment,
-it has no effect on the operation of the terminal emulator.
-It only affects the way applications work within the terminal.
-Likewise, as a general rule (\fBxterm\fP being a rare exception),
-terminal emulators which allow you to
-specify \fBTERM\fP as a parameter or configuration value do
-not change their behavior to match that setting.
-.SS TERMCAP
-If the \fBncurses\fR library has been configured with \fItermcap\fR
-support, \fBncurses\fR will check for a terminal's description in
-termcap form if it is not available in the terminfo database.
-.PP
-The TERMCAP environment variable contains either a terminal description (with
-newlines stripped out),
-or a file name telling where the information denoted by
-the TERM environment variable exists.
-In either case, setting it directs \fBncurses\fR to ignore
-the usual place for this information, e.g., /etc/termcap.
-.SS TERMINFO
-Overrides the directory in which \fBncurses\fR searches for your terminal
+The hashed database uses less disk space and is a little faster than the
+directory tree.
+However,
+some applications assume the existence of the directory tree,
+and read it directly
+rather than using the
+.I \%term\%info
+API.
+.bP
+If
+.I \%ncurses
+is configured with
+.I termcap
+support,
+this variable may contain the location of a
+.I \%termcap
+file.
+.bP
+If the value of
+.I \%TERM\%INFO
+begins with \*(``hex:\*('' or \*(``b64:\*('',
+.I \%ncurses
+uses the remainder of the value as a compiled
+.I \%term\%info
description.
-This is the simplest, but not the only way to change the list of directories.
-The complete list of directories in order follows:
-.RS 3
-.bP
-the last directory to which \fBncurses\fR wrote, if any, is searched first
-.bP
-the directory specified by the TERMINFO environment variable
-.bP
-$HOME/.terminfo
-.bP
-directories listed in the TERMINFO_DIRS environment variable
-.bP
-one or more directories whose names are configured and compiled into the
-ncurses library, i.e.,
-.RS 3
-.bP
-@TERMINFO_DIRS@ (corresponding to the TERMINFO_DIRS variable)
-.bP
-@TERMINFO@ (corresponding to the TERMINFO variable)
+You might produce the base64 format using \fB\%infocmp\fP(1M).
+.RS 4
+.IP
+.EX
+TERMINFO=$(infocmp \-0 \-Q2 \-q)
+export TERMINFO
+.EE
.RE
+.IP
+The compiled description is used only if it corresponds to the terminal
+type identified by
+.IR TERM .
+.PP
+Setting
+.I \%TERM\%INFO
+is the simplest,
+but not the only,
+way to direct
+.I \%ncurses
+to a terminal database.
+The search path is as follows.
+.bP
+the last terminal database to which the running
+.I \%ncurses
+application wrote,
+if any
+.bP
+the location specified by the
+.I \%TERM\%INFO
+environment variable
+.bP
+.I $HOME/.terminfo
+.bP
+locations listed in the
+.I \%TERMINFO_DIRS
+environment variable
+.ds td \" empty
+.if !'@TERMINFO_DIRS@'no default value' .as td @TERMINFO_DIRS@
+.if !'@TERMINFO@\*(td'' \{\
+.bP
+location(s) configured and compiled into
+.I \%ncurses
+.RS 3
+.if !'\*(td'' \{\
+.bP
+.I \%@TERMINFO_DIRS@
+.\}
+.if !'@TERMINFO'' .if !'\*(td'@TERMINFO@' \{\
+.bP
+.I \%@TERMINFO@
+.\}
+.\}
.RE
-.SS TERMINFO_DIRS
-Specifies a list of directories to search for terminal descriptions.
-The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
+.SS "\fITERMINFO_DIRS\fP"
+This variable specifies a list of locations,
+akin to
+.IR PATH ,
+in which
+.I \%ncurses
+searches for the terminal type descriptions described by
+.I \%TERMINFO
+above.
+The list items are separated by colons on Unix
+and semicolons on OS/2 EMX.
+System\ V
+.I \%term\%info
+lacks a corresponding feature;
+.I \%TERMINFO_DIRS
+is an
+.I \%ncurses
+extension.
+.SS "\fITERMPATH\fP"
+If
+.I \%TERMCAP
+does not hold a terminal type description or file name,
+then
+.I \%ncurses
+checks the contents of
+.IR \%TERMPATH ,
+a list of locations,
+akin to
+.IR PATH ,
+in which it searches for
+.I termcap
+terminal type descriptions.
+The list items are separated by colons on Unix
+and semicolons on OS/2 EMX.
.PP
-All of the terminal descriptions are in terminfo form.
-Normally these are stored in a directory tree,
-using subdirectories named by the first letter of the terminal names therein.
-.PP
-If \fBncurses\fP is built with a hashed database,
-then each entry in this list can also be the path of the corresponding
-database file.
-.PP
-If \fBncurses\fP is built with a support for reading termcap files
-directly, then an entry in this list may be the path of a termcap file.
-.SS TERMPATH
-If TERMCAP does not hold a file name then \fBncurses\fR checks
-the TERMPATH environment variable.
-This is a list of filenames separated by spaces or colons (i.e., ":") on Unix,
-semicolons on OS/2 EMX.
-.PP
-If the TERMPATH environment variable is not set,
-\fBncurses\fR looks in the files
-/etc/termcap, /usr/share/misc/termcap and $HOME/.termcap, in that order.
-.PP
-The library may be configured to disregard the following variables when the
-current user is the superuser (root), or if the application uses setuid or
-setgid permissions:
-.PP
-$TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
-.SH ALTERNATE CONFIGURATIONS
-Several different configurations are possible,
-depending on the configure script options used when building \fBncurses\fP.
-There are a few main options whose effects are visible to the applications
-developer using \fBncurses\fP:
+If both
+.I \%TERMCAP
+and
+.I \%TERMPATH
+are unset or invalid,
+.I \%ncurses
+searches for the files
+.IR \%/etc/termcap ,
+.IR \%/usr/share/misc/termcap ,
+and
+.IR \%$HOME/.termcap ,
+in that order.
+.SH "ALTERNATE CONFIGURATIONS"
+Many different
+.I \%ncurses
+configurations are possible,
+determined by the options given to the
+.I \%configure
+script when building the library.
+Run the script with the
+.B \-\-help
+option to peruse them all.
+A few are of particular significance to the application developer
+employing
+.IR \%ncurses .
.TP 5
-\-\-disable\-overwrite
-The standard include for \fBncurses\fP is as noted in \fBSYNOPSIS\fP:
-.RS 3
-.sp
-\fB#include <curses.h>\fR
+.B \-\-disable\-overwrite
+The standard include for \fI\%ncurses\fP is as noted in \fBSYNOPSIS\fP:
+.RS 5
+.PP
+.RS 4
+.EX
+\fB#include <curses.h>\fP
+.EE
.RE
-.IP
-This option is used to avoid filename conflicts when \fBncurses\fP
+.PP
+This option is used to avoid filename conflicts when \fI\%ncurses\fP
is not the main implementation of curses of the computer.
-If \fBncurses\fP is installed disabling overwrite, it puts its headers in
-a subdirectory, e.g.,
-.RS 3
-.sp
-\fB#include <ncurses/curses.h>\fR
+If \fI\%ncurses\fP is installed disabling overwrite,
+it puts its headers in a subdirectory,
+e.g.,
+.PP
+.RS 4
+.EX
+\fB#include <ncurses/curses.h>\fP
+.EE
.RE
-.IP
+.PP
It also omits a symbolic link which would allow you to use \fB\-lcurses\fP
to build executables.
+.RE
.TP 5
-\-\-enable\-widec
+.B \-\-enable\-widec
The configure script renames the library and
(if the \fB\-\-disable\-overwrite\fP option is used)
puts the header files in a different subdirectory.
-All of the library names have a "w" appended to them,
+All of the library names have a \*(``w\*('' appended to them,
i.e., instead of
-.RS 3
-.sp
-\fB\-lncurses\fR
+.RS 5
+.PP
+.RS 4
+.EX
+\fB\-lncurses\fP
+.EE
.RE
-.IP
+.PP
you link with
-.RS 3
-.sp
-\fB\-lncursesw\fR
+.PP
+.RS 4
+.EX
+\fB\-lncursesw\fP
+.EE
.RE
-.IP
-You must also define \fB_XOPEN_SOURCE_EXTENDED\fP when compiling for the
-wide-character library to use the extended (wide-character) functions.
-The \fBcurses.h\fP file which is installed for the wide-character
-library is designed to be compatible with the normal library's header.
-Only the size of the \fBWINDOW\fP structure differs, and very few
-applications require more than a pointer to \fBWINDOW\fPs.
+.PP
+You must also enable the wide-character features in the header file
+when compiling for the wide-character library
+to use the extended (wide-character) functions.
+The symbol which enables these features has changed
+since X/Open Curses, Issue 4:
+.bP
+Originally, the wide-character feature required the symbol
+\fB_XOPEN_SOURCE_EXTENDED\fP
+but that was only valid for XPG4 (1996).
+.bP
+Later, that was deemed conflicting with \fB_XOPEN_SOURCE\fP defined to 500.
+.bP
+As of mid-2018,
+none of the features in this implementation require a \fB_XOPEN_SOURCE\fP
+feature greater than 600.
+However, X/Open Curses, Issue 7 (2009) recommends defining it to 700.
+.bP
+Alternatively, you can enable the feature by defining \fBNCURSES_WIDECHAR\fP
+with the caveat that some other header file than \fBcurses.h\fP
+may require a specific value for \fB_XOPEN_SOURCE\fP
+(or a system-specific symbol).
+.PP
+The \fI\%curses.h\fP header file installed for the wide-character
+library is designed to be compatible with the non-wide library's header.
+Only the size of the \fI\%WINDOW\fP structure differs;
+few applications require more than pointers to \fI\%WINDOW\fPs.
+.PP
If the headers are installed allowing overwrite,
the wide-character library's headers should be installed last,
to allow applications to be built using either library
from the same set of headers.
+.RE
.TP 5
-\-\-with\-pthread
+.B \-\-with\-pthread
The configure script renames the library.
-All of the library names have a "t" appended to them
-(before any "w" added by \fB\-\-enable\-widec\fP).
+All of the library names have a \*(``t\*('' appended to them
+(before any \*(``w\*('' added by \fB\-\-enable\-widec\fP).
.IP
The global variables such as \fBLINES\fP are replaced by macros to
allow read-only access.
At the same time, setter-functions are provided to set these values.
Some applications (very few) may require changes to work with this convention.
.TP 5
-\-\-with\-shared
-.TP
-\-\-with\-normal
-.TP
-\-\-with\-debug
-.TP
-\-\-with\-profile
+.B \-\-with\-shared
+.tQ
+.B \-\-with\-normal
+.tQ
+.B \-\-with\-debug
+.tQ
+.B \-\-with\-profile
The shared and normal (static) library names differ by their suffixes,
e.g., \fBlibncurses.so\fP and \fBlibncurses.a\fP.
-The debug and profiling libraries add a "_g" and a "_p" to the root
-names respectively,
+The debug and profiling libraries add a \*(``_g\*(''
+and a \*(``_p\*('' to the root names respectively,
e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP.
.TP 5
-\-\-with\-trace
+.B \-\-with\-termlib
+Low-level functions which do not depend upon whether the library
+supports wide-characters, are provided in the tinfo library.
+.IP
+By doing this, it is possible to share the tinfo library between
+wide/normal configurations as well as reduce the size of the library
+when only low-level functions are needed.
+.IP
+Those functions are described in these pages:
+.RS
+.bP
+\fB\%curs_extend\fP(3X) \- miscellaneous \fIcurses\fP extensions
+.bP
+\fB\%curs_inopts\fP(3X) \- \fIcurses\fP input options
+.bP
+\fB\%curs_kernel\fP(3X) \- low-level \fIcurses\fP routines
+.bP
+\fB\%curs_termattrs\fP(3X) \- \fIcurses\fP environment query routines
+.bP
+\fB\%curs_termcap\fP(3X) \- \fIcurses\fP emulation of \fItermcap\fP
+.bP
+\fB\%curs_terminfo\fP(3X) \- \fIcurses\fP interface to \fIterminfo\fP
+database
+.bP
+\fB\%curs_util\fP(3X) \- miscellaneous \fIcurses\fP utility routines
+.RE
+.TP 5
+.B \-\-with\-trace
The \fBtrace\fP function normally resides in the debug library,
but it is sometimes useful to configure this in the shared library.
Configure scripts should check for the function's existence rather
than assuming it is always in the debug library.
.SH FILES
-.TP 5
-@DATADIR@/tabset
-directory containing initialization files for the terminal capability database
-@TERMINFO@
-terminal capability database
-.SH SEE ALSO
-\fBterminfo\fR(\*n) and related pages whose names begin
-"curs_" for detailed routine descriptions.
-.br
-\fBcurs_variables\fR(3X)
-.SH EXTENSIONS
-The \fBncurses\fR library can be compiled with an option (\fB\-DUSE_GETCAP\fR)
-that falls back to the old-style /etc/termcap file if the terminal setup code
-cannot find a terminfo entry corresponding to \fBTERM\fR.
-Use of this feature
-is not recommended, as it essentially includes an entire termcap compiler in
-the \fBncurses\fR startup code, at significant cost in core and startup cycles.
-.PP
-The \fBncurses\fR library includes facilities for capturing mouse events on
-certain terminals (including xterm).
-See the \fBcurs_mouse\fR(3X)
-manual page for details.
-.PP
-The \fBncurses\fR library includes facilities for responding to window
-resizing events, e.g., when running in an xterm.
-See the \fBresizeterm\fR(3X)
-and \fBwresize\fR(3X) manual pages for details.
-In addition, the library may be configured with a SIGWINCH handler.
-.PP
-The \fBncurses\fR library extends the fixed set of function key capabilities
-of terminals by allowing the application designer to define additional
-key sequences at runtime.
-See the \fBdefine_key\fR(3X)
-\fBkey_defined\fR(3X),
-and \fBkeyok\fR(3X) manual pages for details.
-.PP
-The \fBncurses\fR library can exploit the capabilities of terminals which
-implement the ISO\-6429 SGR 39 and SGR 49 controls, which allow an application
-to reset the terminal to its original foreground and background colors.
-From the users' perspective, the application is able to draw colored
-text on a background whose color is set independently, providing better
-control over color contrasts.
-See the \fBdefault_colors\fR(3X) manual page for details.
-.PP
-The \fBncurses\fR library includes a function for directing application output
-to a printer attached to the terminal device.
-See the \fBcurs_print\fR(3X) manual page for details.
-.SH PORTABILITY
-The \fBncurses\fR library is intended to be BASE-level conformant with XSI
-Curses.
-The EXTENDED XSI Curses functionality
-(including color support) is supported.
-.PP
-A small number of local differences (that is, individual differences between
-the XSI Curses and \fBncurses\fR calls) are described in \fBPORTABILITY\fR
-sections of the library man pages.
-.PP
-Unlike other implementations, this one checks parameters such as pointers
-to WINDOW structures to ensure they are not null.
-The main reason for providing this behavior is to guard against programmer
-error.
-The standard interface does not provide a way for the library
-to tell an application which of several possible errors were detected.
-Relying on this (or some other) extension will adversely affect the
-portability of curses applications.
-.PP
-This implementation also contains several extensions:
-.bP
-The routine \fBhas_key\fR is not part of XPG4, nor is it present in SVr4.
-See the \fBcurs_getch\fR(3X) manual page for details.
-.bP
-The routine \fBslk_attr\fR is not part of XPG4, nor is it present in SVr4.
-See the \fBcurs_slk\fR(3X) manual page for details.
-.bP
-The routines \fBgetmouse\fR, \fBmousemask\fR, \fBungetmouse\fR,
-\fBmouseinterval\fR, and \fBwenclose\fR relating to mouse interfacing are not
-part of XPG4, nor are they present in SVr4.
-See the \fBcurs_mouse\fR(3X) manual page for details.
-.bP
-The routine \fBmcprint\fR was not present in any previous curses implementation.
-See the \fBcurs_print\fR(3X) manual page for details.
-.bP
-The routine \fBwresize\fR is not part of XPG4, nor is it present in SVr4.
-See the \fBwresize\fR(3X) manual page for details.
-.bP
-The WINDOW structure's internal details can be hidden from application
-programs.
-See \fBcurs_opaque\fR(3X) for the discussion of \fBis_scrollok\fR, etc.
-.bP
-This implementation can be configured to provide rudimentary support
-for multi-threaded applications.
-See \fBcurs_threads\fR(3X) for details.
-.bP
-This implementation can also be configured to provide a set of functions which
-improve the ability to manage multiple screens.
-See \fBcurs_sp_funcs\fR(3X) for details.
-.PP
-In historic curses versions, delays embedded in the capabilities \fBcr\fR,
-\fBind\fR, \fBcub1\fR, \fBff\fR and \fBtab\fR activated corresponding delay
-bits in the UNIX tty driver.
-In this implementation, all padding is done by sending NUL bytes.
-This method is slightly more expensive, but narrows the interface
-to the UNIX kernel significantly and increases the package's portability
-correspondingly.
+.TP
+.I @DATADIR@/tabset
+tab stop initialization database
+.TP
+.I \*d
+compiled terminal capability database
.SH NOTES
-The header file \fB<curses.h>\fR automatically includes the header files
-\fB<stdio.h>\fR and \fB<unctrl.h>\fR.
+X/Open Curses permits most functions it specifies to be made available
+as macros as well.
+.\" See X/Open Curses Issue 4, Version 2, pp. 227-234.
+.\" See X/Open Curses Issue 7, pp. 311-318.
+\fI\%ncurses\fP does so
+.bP
+for functions that return values via their parameters,
+.bP
+to support obsolete features,
+.bP
+to reuse functions
+(for example,
+those that move the cursor before another operation),
+and
+.bP
+a few special cases.
.PP
-If standard output from a \fBncurses\fR program is re-directed to something
-which is not a tty, screen updates will be directed to standard error.
-This was an undocumented feature of AT&T System V Release 3 curses.
+If the standard output file descriptor of an
+.I \%ncurses
+program is redirected to something that is not a terminal device,
+the library writes screen updates to the standard error file descriptor.
+This was an undocumented feature of SVr3
+.IR curses .
+.PP
+See subsection \*(``Header Files\*('' below regarding symbols exposed by
+inclusion of \fI\%curses.h\fP.
+.SH EXTENSIONS
+.I \%ncurses
+enables an application to capture mouse events on certain terminals,
+including \fI\%xterm\fP(1);
+see \fB\%curs_mouse\fP(3X).
+.PP
+.I \%ncurses
+provides a means of responding to window resizing events,
+as when running in a GUI terminal emulator application such as
+.IR \%xterm ;
+see \fB\%resizeterm\fP(3X) and \fB\%wresize\fP(3X).
+.PP
+.I \%ncurses
+allows an application to query the terminal for the presence of a wide
+variety of special keys;
+see \fB\%has_key\fP(3X).
+.PP
+.I \%ncurses
+extends the fixed set of function key capabilities specified by X/Open
+Curses by allowing the application programmer to define additional key
+events at runtime;
+see
+\fB\%define_key\fP(3X),
+\fB\%key_defined\fP(3X),
+\fB\%keybound\fP(3X),
+and
+\fB\%keyok\fP(3X).
+.PP
+.I \%ncurses
+can exploit the capabilities of terminals implementing ISO\ 6429/ECMA-48
+SGR\ 39 and SGR\ 49 sequences,
+which allow an application to reset the terminal to its original
+foreground and background colors.
+From a user's perspective,
+the application is able to draw colored text on a background whose color
+is set independently,
+providing better control over color contrasts.
+See \fB\%default_colors\fP(3X).
+.PP
+An
+.I \%ncurses
+application can eschew knowledge of
+.I \%WINDOW
+structure internals,
+instead using accessor functions such as
+\fB\%is_scrollok\fP(3X).
+.PP
+.I \%ncurses
+enables an application to direct application output to a printer
+attached to the terminal device;
+see \fB\%curs_print\fP(3X).
+.PP
+.I \%ncurses
+offers \fB\%slk_attr\fP(3X) as a counterpart of \fB\%attr_get\fP(3X) for
+soft-label key lines,
+and \fB\%extended_slk_color\fP(3X) as a form of \fB\%slk_color\fP(3X)
+that can gather color information from them when many colors are
+supported.
+.PP
+Some extensions are available only if
+.I \%ncurses
+permits modification of \fB\%unctrl\fP(3X)'s behavior;
+see \fB\%use_legacy_coding\fP(3X).
+.I \%ncurses
+is compiled to support them;
+section \*(``ALTERNATE CONFIGURATIONS\*('' describes how.
+.bP
+Rudimentary support for multi-threaded applications may be available;
+see \fBcurs_threads\fP(3X).
+.bP
+Functions that ease the management of multiple screens can be exposed;
+see \fBcurs_sp_funcs\fP(3X).
+.bP
+To aid applications to debug their memory usage,
+.I ncurses
+optionally offers functions to more aggressively free memory it
+dynamically allocates itself;
+see \fBcurs_memleaks\fP(3X).
+.bP
+The library facilitates auditing and troubleshooting of its behavior;
+see \fBcurs_trace\fP(3X).
+.bP
+The compiler option
+.B \%\-DUSE_GETCAP
+causes the library to fall back to reading
+.I \%/etc/termcap
+if the terminal setup code cannot find a
+.I \%term\%info
+entry corresponding to
+.IR TERM .
+Use of this feature is not recommended,
+as it essentially includes an entire
+.I termcap
+compiler in the
+.I \%ncurses
+startup code,
+at a cost in memory usage and application launch latency.
+.PP
+.I \%PDCurses
+and NetBSD
+.I curses
+incorporate some
+.I \%ncurses
+extensions.
+Individual man pages indicate where this is the case.
+.SH PORTABILITY
+X/Open Curses defines two levels of conformance,
+\*(``base\*('' and \*(``enhanced\*(''.
+The latter includes several additional features,
+such as wide-character and color support.
+.I \%ncurses
+intends base-level conformance with X/Open Curses,
+and supports all features of its enhanced level
+except the \fB\%untic\fP utility.
+.PP
+Differences between X/Open Curses and
+.I \%ncurses
+are documented in the \*(``PORTABILITY\*('' sections of applicable man
+pages.
+.SS "Error Checking"
+In many cases, X/Open Curses is vague about error conditions,
+omitting some of the SVr4 documentation.
+.PP
+Unlike other implementations,
+.I \%ncurses
+checks pointer parameters,
+such as those to
+.I \%WINDOW
+structures,
+to ensure that they are not null.
+This is done primarily to guard against programmer error.
+The standard interface does not provide a way for the library
+to tell an application which of several possible errors occurred.
+Relying on this
+(or some other)
+extension adversely affects the portability of
+.I curses
+applications.
+.SS "Padding Differences"
+In historical
+.I curses
+implementations,
+delays embedded in the
+.I \%term\%info
+capabilities
+.B \%carriage_return
+.RB ( cr ),
+.B \%scroll_forward
+.RB ( ind ),
+.B \%cursor_left
+.RB ( cub1 ),
+.B \%form_feed
+.RB ( ff ),
+and
+.B \%tab
+.RB ( ht )
+activated corresponding delay bits in the Unix terminal driver.
+.I \%ncurses
+performs all padding by sending NUL bytes to the device.
+This method is slightly more expensive,
+but narrows the interface to the Unix kernel significantly and
+correspondingly increases the package's portability.
+.SS "Header Files"
+The header file
+.I \%curses.h
+itself includes the header files
+.I \%stdio.h
+and
+.IR \%unctrl.h .
+.PP
+X/Open Curses has more to say,
+.RS 4
+.PP
+The inclusion of
+.I \%curses.h
+may make visible all symbols from the headers
+.IR \%stdio.h ,
+.IR \%term.h ,
+.IR \%termios.h ,
+and
+.IR \%wchar.h .
+.RE
+.PP
+but does not finish the story.
+A more complete account follows.
+.bP
+Starting with 4BSD
+.I curses
+(1980)
+all implementations have provided a
+.I \%curses.h
+file.
+.IP
+BSD
+.I curses
+code included
+.I \%curses.h
+and
+.I \%unctrl.h
+from an internal header file
+.IR \%curses.ext ,
+where
+\*(``ext\*('' abbreviated \*(``externs\*(''.
+.IP
+The implementations of
+.I \%printw
+and
+.I \%scanw
+used undocumented internal functions of the standard I/O library
+.RI ( _doprnt
+and
+.IR _doscan ),
+but nothing in
+.I \%curses.h
+itself relied upon
+.IR \%stdio.h .
+.bP
+SVr2
+.I curses
+added
+.IR \%newterm ,
+which relies upon
+.I \%stdio.h
+because its function prototype employs the
+.I FILE
+type.
+.IP
+SVr4
+.I curses
+added
+.I \%putwin
+and
+.IR \%getwin ,
+which also use
+.IR \%stdio.h .
+.IP
+X/Open Curses specifies all three of these functions.
+.IP
+SVr4
+.I curses
+and X/Open Curses do not require the developer to include
+.I \%stdio.h
+before
+.IR \%curses.h .
+Both document use of
+.I curses
+as requiring only
+.IR \%curses.h .
+.IP
+As a result,
+standard
+.I \%curses.h
+always includes
+.IR \%stdio.h .
+.bP
+X/Open Curses and SVr4
+.I curses
+are inconsistent with respect to
+.IR \%unctrl.h .
+.IP
+As noted in \fBcurs_util\fP(3X),
+.I \%ncurses
+includes
+.I \%unctrl.h
+from
+.I \%curses.h
+(as SVr4 does).
+.bP
+X/Open Curses's comments about
+.I \%term.h
+and
+.I \%termios.h
+may refer to HP-UX and AIX.
+.IP
+HP-UX
+.I curses
+includes
+.I \%term.h
+from
+.I \%curses.h
+to declare
+.I \%setupterm
+in
+.IR \%curses.h ,
+but
+.I \%ncurses
+and Solaris
+.I curses
+do not.
+.IP
+AIX
+.I curses
+includes
+.I \%term.h
+and
+.IR \% termios.h .
+Again,
+.I \%ncurses
+and Solaris
+.I curses
+do not.
+.bP
+X/Open Curses says that
+.I \%curses.h
+.B may
+include
+.IR \%term.h ,
+but does not require it to do so.
+.IP
+Some programs use functions declared in both
+.I \%curses.h
+and
+.IR \%term.h ,
+and must include both header files in the same module.
+Very old versions of AIX
+.I curses
+required inclusion of
+.I \%curses.h
+before
+.IR \%term.h .
+.IP
+The header files supplied by
+.I \%ncurses
+include the standard library headers required for its declarations,
+so
+.IR \%ncurses 's
+own header files can be included in any order.
+But for portability,
+you should include
+.I \%curses.h
+before
+.IR \%term.h .
+.bP
+X/Open Curses says \*(``may make visible\*('' because including a header
+file does not necessarily make visible all of the symbols in it
+(consider
+.B \%#ifdef
+and similar).
+.IP
+For instance,
+.IR \%ncurses 's
+.I \%curses.h
+.B may \" bold to contrast with preceding italic
+include
+.I \%wchar.h
+if the proper symbol is defined,
+and if
+.I \%ncurses
+is configured for wide-character support.
+If
+.I \%wchar.h
+is included,
+its symbols
+.B may \" bold for consistency in this paragraph
+be made visible depending on the value of the
+.B _XOPEN_SOURCE
+feature test macro.
+.bP
+X/Open Curses mandates an application's inclusion of one standard C
+library header in a special case:
+.I \%stdarg.h
+before
+.I \%curses.h
+to prototype the functions
+.I \%vw_printw
+and
+.I \%vw_scanw
+(as well as the obsolete
+.I \%vwprintw
+and
+.IR \%vwscanw ).
+Each of these takes a variadic argument list,
+a
+.I \%va_list
+parameter,
+like that of \fI\%printf\fP(3).
+.IP
+SVr3
+.I curses
+introduced
+the two obsolete functions,
+and X/Open Curses the others.
+In between,
+SVr4
+.I curses
+provided for the possibility that an application might include either
+.I \%varargs.h
+or
+.IR \%stdarg.h .
+These represented contrasting approaches to handling variadic
+argument lists.
+The older interface,
+.IR \%varargs.h ,
+used a pointer to
+.I char \" V7, 32V, System III, 3BSD
+for variadic functions'
+.I \%va_list
+parameter.
+Later,
+the list acquired its own standard data type,
+.IR \%va_list ,
+defined in
+.IR \%stdarg.h ,
+empowering the compiler to check the types of a function call's actual
+parameters against the formal ones declared in its prototype.
+.IP
+No conforming implementations of X/Open Curses require an application
+to include
+.I \%stdarg.h
+before
+.I \%curses.h
+because they either have allowed for a special type,
+or,
+like
+.IR \%ncurses ,
+they include
+.I \%stdarg.h
+themselves to provide a portable interface.
.SH AUTHORS
-Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
-Based on pcurses by Pavel Curtis.
+Zeyd M. Ben-Halim,
+Eric S. Raymond,
+Thomas E. Dickey.
+Based on
+.I \%pcurses
+by Pavel Curtis.
+.SH SEE ALSO
+\fB\%curs_variables\fP(3X),
+\fB\%terminfo\fP(5),
+\fB\%user_caps\fP(5)
diff --git a/man/ncurses6-config.1 b/man/ncurses6-config.1
deleted file mode 100644
index 2131dc7..0000000
--- a/man/ncurses6-config.1
+++ /dev/null
@@ -1,98 +0,0 @@
-.\"***************************************************************************
-.\" Copyright (c) 2010 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 *
-.\" "Software"), to deal in the Software without restriction, including *
-.\" without limitation the rights to use, copy, modify, merge, publish, *
-.\" distribute, distribute with modifications, sublicense, and/or sell *
-.\" copies of the Software, and to permit persons to whom the Software is *
-.\" furnished to do so, subject to the following conditions: *
-.\" *
-.\" The above copyright notice and this permission notice shall be included *
-.\" in all copies or substantial portions of the Software. *
-.\" *
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
-.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
-.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
-.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
-.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
-.\" *
-.\" Except as contained in this notice, the name(s) of the above copyright *
-.\" holders shall not be used in advertising or otherwise to promote the *
-.\" sale, use or other dealings in this Software without prior written *
-.\" authorization. *
-.\"***************************************************************************
-.\"
-.\" $Id: MKncu_config.in,v 1.3 2010/03/06 22:29:17 tom Exp $
-.TH ncurses6-config 1 ""
-.SH NAME
-ncurses6-config \- helper script for ncurses libraries
-.SH SYNOPSIS
-.B ncurses6-config
-[\fIoptions\fR]
-.SH DESCRIPTION
-This is a shell script which simplifies configuring applications against
-a particular set of ncurses libraries.
-.SH OPTIONS
-.TP
-\fB\-\-prefix\fR
-echos the package\-prefix of ncurses
-.TP
-\fB\-\-exec\-prefix\fR
-echos the executable\-prefix of ncurses
-.TP
-\fB\-\-cflags\fR
-echos the C compiler flags needed to compile with ncurses
-.TP
-\fB\-\-libs\fR
-echos the libraries needed to link with ncurses
-.TP
-\fB\-\-version\fR
-echos the release+patchdate version of ncurses
-.TP
-\fB\-\-abi\-version\fR
-echos the ABI version of ncurses
-.TP
-\fB\-\-mouse\-version\fR
-echos the mouse\-interface version of ncurses
-.TP
-\fB\-\-bindir\fR
-echos the directory containing ncurses programs
-.TP
-\fB\-\-datadir\fR
-echos the directory containing ncurses data
-.TP
-\fB\-\-includedir\fR
-echos the directory containing ncurses header files
-.TP
-\fB\-\-libdir\fR
-echos the directory containing ncurses libraries
-.TP
-\fB\-\-mandir\fR
-echos the directory containing ncurses manpages
-.TP
-\fB\-\-terminfo\fR
-echos the $TERMINFO terminfo database path, e.g.,
-.RS
-/system/etc/terminfo
-.RE
-.TP
-\fB\-\-terminfo\-dirs\fR
-echos the $TERMINFO_DIRS directory list, e.g.,
-.RS
-/system/etc/terminfo
-.RE
-.TP
-\fB\-\-termpath\fR
-echos the $TERMPATH termcap list, if support for termcap is configured.
-.TP
-\fB\-\-help\fR
-prints this message
-.SH "SEE ALSO"
-\fBcurses\fR(3X)
-.PP
-This describes \fBncurses\fR
-version 6.0 (patch 20150808).
diff --git a/man/new_pair.3x b/man/new_pair.3x
new file mode 100644
index 0000000..5e844bf
--- /dev/null
+++ b/man/new_pair.3x
@@ -0,0 +1,166 @@
+.\"***************************************************************************
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 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 *
+.\" "Software"), to deal in the Software without restriction, including *
+.\" without limitation the rights to use, copy, modify, merge, publish, *
+.\" distribute, distribute with modifications, sublicense, and/or sell *
+.\" copies of the Software, and to permit persons to whom the Software is *
+.\" furnished to do so, subject to the following conditions: *
+.\" *
+.\" The above copyright notice and this permission notice shall be included *
+.\" in all copies or substantial portions of the Software. *
+.\" *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
+.\" *
+.\" Except as contained in this notice, the name(s) of the above copyright *
+.\" holders shall not be used in advertising or otherwise to promote the *
+.\" sale, use or other dealings in this Software without prior written *
+.\" authorization. *
+.\"***************************************************************************
+.\"
+.\" Author: Thomas E. Dickey
+.\"
+.\" $Id: new_pair.3x,v 1.46 2024/03/16 15:35:01 tom Exp $
+.TH new_pair 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
+.SH NAME
+\fB\%alloc_pair\fP,
+\fB\%find_pair\fP,
+\fB\%free_pair\fP \-
+dynamically allocate \fIcurses\fR color pairs
+.SH SYNOPSIS
+.nf
+\fB#include <curses.h>
+.PP
+\fBint alloc_pair(int \fIfg\fP, int \fIbg\fP);
+\fBint find_pair(int \fIfg\fP, int \fIbg\fP);
+\fBint free_pair(int \fIpair\fP);
+.fi
+.SH DESCRIPTION
+These functions are an extension to the \fIcurses\fP library.
+They permit an application to dynamically allocate a color pair using
+the foreground/background colors rather than assign a fixed color pair number,
+and return an unused pair to the pool.
+.PP
+The number of colors may be related to the number of possible color
+pairs for a given terminal, or it may not:
+.bP
+While almost all terminals allow setting the color \fIattributes\fP
+independently,
+it is unlikely that your terminal allows you to modify the attributes
+of a given character cell without rewriting it.
+That is, the foreground and background colors are applied as a pair.
+.bP
+Color pairs are the \fIcurses\fP library's way of managing a color palette
+on a terminal.
+If the library does not keep track of the \fIcombinations\fP of
+colors which are displayed, it will be inefficient.
+.IP \(bu 4
+For simple terminal emulators
+with only a few dozen color combinations,
+it is convenient to use the maximum number of combinations
+as the limit on color pairs:
+.PP
+.RS 8
+.EX
+\fBCOLORS\fI * \fBCOLORS\fR
+.EE
+.RE
+.IP \(bu 4
+Terminals which support \fIdefault colors\fP distinct
+from \*(``ANSI colors\*(''
+add to the possible combinations, producing this total:
+.PP
+.RS 8
+.EX
+\fI( \fBCOLORS\fI + 1 ) * ( \fBCOLORS\fI + 1 )\fR
+.EE
+.RE
+.bP
+An application might use up to a few dozen color pairs to
+implement a predefined color scheme.
+.IP
+Beyond that lies in the realm of programs using the foreground
+and background colors for \*(``ASCII art\*(''
+(or some other non-textual application).
+.IP
+Also beyond those few dozen pairs, the required size for a table
+to represent the combinations grows rapidly with an increasing number of colors.
+.IP
+These functions allow a developer to let the screen library
+manage color pairs.
+.SS alloc_pair
+The \fBalloc_pair\fP function accepts parameters for
+foreground and background color, and
+checks if that color combination is already associated with a color pair.
+.bP
+If the combination already exists,
+\fBalloc_pair\fP returns the existing pair.
+.bP
+If the combination does not exist,
+\fBalloc_pair\fP allocates a new color pair and returns that.
+.bP
+If the table fills up, \fBalloc_pair\fP discards the least-recently
+allocated entry using \fBfree_pair\fP and allocates a new color pair.
+.PP
+All of the color pairs are allocated from a table of possible color pairs.
+The size of the table is determined by the terminfo \fBpairs\fP capability.
+The table is shared with \fBinit_pair\fP;
+in fact \fBalloc_pair\fP calls \fBinit_pair\fP after
+updating the \fI\%ncurses\fP library's fast index
+to the colors versus color pairs.
+.SS find_pair
+The \fBfind_pair\fP function accepts parameters for
+foreground and background color, and
+checks if that color combination is already associated with a color pair,
+returning the pair number if it has been allocated.
+Otherwise it returns \-1.
+.SS free_pair
+Marks the given color pair as unused,
+i.e., like color pair 0.
+.SH RETURN VALUE
+The \fBalloc_pair\fP function returns a color pair number in the range
+1 through \fBCOLOR_PAIRS\fP\-1, unless it encounters an error updating
+its fast index to the color pair values, preventing it from allocating
+a color pair.
+In that case, it returns \-1.
+.PP
+The \fBfind_pair\fP function returns a color pair number if the
+given color combination has been associated with a color pair,
+or \-1 if not.
+.PP
+Likewise, \fBfree_pair\fP returns \fBOK\fP unless it encounters an
+error updating the fast index or if no such color pair is in use.
+.SH PORTABILITY
+These 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 them be conditioned using \fB\%NCURSES_VERSION\fP.
+.SH AUTHORS
+Thomas Dickey
+.SH SEE ALSO
+\fB\%curs_color\fP(3X)
diff --git a/man/panel.3x b/man/panel.3x
index cc36d22..c63b431 100644
--- a/man/panel.3x
+++ b/man/panel.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2020,2015 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -26,168 +27,264 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: panel.3x,v 1.18 2015/04/11 10:23:49 tom Exp $
-.TH panel 3X ""
-.ds n 5
-.ds d @TERMINFO@
+.\" $Id: panel.3x,v 1.63 2024/03/16 15:35:01 tom Exp $
+.TH panel 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-panel \- panel stack extension for curses
+panel \-
+panel stack extension for \fIcurses\fP
.SH SYNOPSIS
-\fB#include <panel.h>\fR
-.P
-\fBcc [flags] sourcefiles \-lpanel \-lncurses\fR
-.P
-\fBPANEL *new_panel(WINDOW *win)\fR
-.br
-\fBint bottom_panel(PANEL *pan)\fR
-.br
-\fBint top_panel(PANEL *pan)\fR
-.br
-\fBint show_panel(PANEL *pan)\fR
-.br
-\fBvoid update_panels();\fR
-.br
-\fBint hide_panel(PANEL *pan)\fR
-.br
-\fBWINDOW *panel_window(const PANEL *pan)\fR
-.br
-\fBint replace_panel(PANEL *pan, WINDOW *window)\fR
-.br
-\fBint move_panel(PANEL *pan, int starty, int startx)\fR
-.br
-\fBint panel_hidden(const PANEL *pan)\fR
-.br
-\fBPANEL *panel_above(const PANEL *pan)\fR
-.br
-\fBPANEL *panel_below(const PANEL *pan)\fR
-.br
-\fBint set_panel_userptr(PANEL *pan, const void *ptr)\fR
-.br
-\fBconst void *panel_userptr(const PANEL *pan)\fR
-.br
-\fBint del_panel(PANEL *pan)\fR
-.br
-.SH DESCRIPTION
-Panels are \fBcurses\fR(3X) windows with the added feature of
-depth. Panel functions allow the use of stacked windows and ensure
-the proper portions of each window and the curses \fBstdscr\fR window are
-hidden or displayed when panels are added, moved, modified or removed.
-The set of currently visible panels is the stack of panels. The
-\fBstdscr\fR window is beneath all panels, and is not considered part
-of the stack.
-.P
-A window is associated with every panel. The panel routines enable
-you to create, move, hide, and show panels, as well as position a
-panel at any desired location in the stack.
-.P
-Panel routines are a functional layer added to \fBcurses\fR(3X), make only
-high-level curses calls, and work anywhere terminfo curses does.
-.SH FUNCTIONS
-.TP
-.B new_panel(win)
-allocates a \fBPANEL\fR structure, associates it with
-\fBwin\fR, places the panel on the top of the stack (causes it
-to be displayed above any other panel) and returns a
-pointer to the new panel.
-.TP
-.B update_panels()
-refreshes the virtual screen to reflect the relations between the
-panels in the stack, but does not call doupdate() to refresh the
-physical screen.
-Use this function and not \fBwrefresh\fP or \fBwnoutrefresh\fP.
-.B update_panels
-may be called more than once before a call to
-doupdate(), but doupdate() is the function responsible for updating
-the physical screen.
-.TP
-.B del_panel(pan)
-removes the given panel from the stack and deallocates the
-\fBPANEL\fR structure (but not its associated window).
-.TP
-.B hide_panel(pan)
-removes the given panel from the panel stack and thus hides it from
-view. The \fBPANEL\fR structure is not lost, merely removed from the stack.
-.TP
-.B panel_hidden(pan)
-returns \fBTRUE\fP if the panel is in the panel stack,
-\fBFALSE\fP if it is not.
-If the panel is a null pointer, return ERR.
-.TP
-.B show_panel(pan)
-makes a hidden panel visible by placing it on top of the panels in the
-panel stack. See COMPATIBILITY below.
-.TP
-.B top_panel(pan)
-puts the given visible panel on top of all panels in the stack. See
-COMPATIBILITY below.
-.TP
-.B bottom_panel(pan)
-puts panel at the bottom of all panels.
-.TP
-.B move_panel(pan,starty,startx)
-moves the given panel window so that its upper-left corner is at
-\fBstarty\fR, \fBstartx\fR. It does not change the position of the
-panel in the stack. Be sure to use this function, not \fBmvwin()\fR,
-to move a panel window.
-.TP
-.B replace_panel(pan,window)
-replaces the current window of panel with \fBwindow\fR (useful, for
-example if you want to resize a panel; if you're using \fBncurses\fR,
-you can call \fBreplace_panel\fR on the output of \fBwresize\fR(3X)).
-It does not change the position of the panel in the stack.
-.TP
-.B panel_above(pan)
-returns a pointer to the panel above pan. If the panel argument is
-\fB(PANEL *)0\fR, it returns a pointer to the bottom panel in the stack.
-.TP
-.B panel_below(pan)
-returns a pointer to the panel just below pan. If the panel argument
-is \fB(PANEL *)0\fR, it returns a pointer to the top panel in the stack.
-.TP
-.B set_panel_userptr(pan,ptr)
-sets the panel's user pointer.
-.TP
-.B panel_userptr(pan)
-returns the user pointer for a given panel.
-.TP
-.B panel_window(pan)
-returns a pointer to the window of the given panel.
-.SH DIAGNOSTICS
-Each routine that returns a pointer returns \fBNULL\fR if an error
-occurs. Each routine that returns an int value returns \fBOK\fR if it
-executes successfully and \fBERR\fR if not.
-.SH COMPATIBILITY
-Reasonable care has been taken to ensure compatibility
-with the native panel facility introduced in SVr3.2 (inspection of
-the SVr4 manual pages suggests the programming interface is unchanged).
-The \fBPANEL\fR data structures are merely similar. The programmer
-is cautioned not to directly use \fBPANEL\fR fields.
-.P
-The functions \fBshow_panel()\fR and \fBtop_panel()\fR are identical
-in this implementation, and work equally well with displayed or hidden
-panels. In the native System V implementation, \fBshow_panel()\fR is
-intended for making a hidden panel visible (at the top of the stack)
-and \fBtop_panel()\fR is intended for making an already-visible panel
-move to the top of the stack. You are cautioned to use the correct
-function to ensure compatibility with native panel libraries.
-.SH NOTE
-In your library list, libpanel.a should be before libncurses.a; that is,
-you want to say `\-lpanel \-lncurses', not the other way around (which would
-usually give a link-error).
-.SH FILES
-.P
-panel.h
-interface for the panels library
-.P
-libpanel.a
-the panels library itself
-.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_variables\fR(3X),
+.nf
+\fB#include <panel.h>
.PP
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
-.SH AUTHOR
-Originally written by Warren Tucker <wht@n4hgf.mt-park.ga.us>,
-primarily to assist in porting u386mon to systems without a native
-panels library. Repackaged for ncurses by Zeyd ben-Halim.
+\fBPANEL *new_panel(WINDOW *\fIwin\fP);
+.PP
+\fBint bottom_panel(PANEL *\fIpan\fP);
+\fBint top_panel(PANEL *\fIpan\fP);
+\fBint show_panel(PANEL *\fIpan\fP);
+\fBvoid update_panels(void);
+\fBint hide_panel(PANEL *\fIpan\fP);
+.PP
+\fBWINDOW *panel_window(const PANEL *\fIpan\fP);
+\fBint replace_panel(PANEL *\fIpan\fP, WINDOW *\fIwindow\fP);
+\fBint move_panel(PANEL *\fIpan\fP, int \fIstarty\fP, int \fIstartx\fP);
+\fBint panel_hidden(const PANEL *\fIpan\fP);
+.PP
+\fBPANEL *panel_above(const PANEL *\fIpan\fP);
+\fBPANEL *panel_below(const PANEL *\fIpan\fP);
+.PP
+\fBint set_panel_userptr(PANEL *\fIpan\fP, const void *\fIptr\fP);
+\fBconst void *panel_userptr(const PANEL *\fIpan\fP);
+.PP
+\fBint del_panel(PANEL *\fIpan\fP);
+.PP
+\fI/* ncurses extensions */\fP
+\fBPANEL *ground_panel(SCREEN *\fIsp\fP);
+\fBPANEL *ceiling_panel(SCREEN *\fIsp\fP);
+.fi
+.SH DESCRIPTION
+Panels are \fBcurses\fP(3X) windows with the added property of
+depth.
+Panel functions allow the use of stacked windows and ensure that the
+proper portions of each window and the \fIcurses\fP \fB\%stdscr\fP
+window are hidden or displayed when panels are added,
+moved,
+modified,
+or removed.
+The set of currently visible panels is the stack of panels.
+The
+\fB\%stdscr\fP window is beneath all panels,
+and is not considered part of the stack.
+.PP
+A window is associated with each panel.
+The panel routines enable you to create,
+move,
+hide,
+and show panels.
+You can relocate a panel to any desired position in the stack.
+.PP
+Panel routines are a functional layer added to \fIcurses\fP,
+make only high-level \fIcurses\fP calls,
+and work anywhere \fIcurses\fP does.
+.SH FUNCTIONS
+.\" ---------
+.SS bottom_panel
+\fB\%bottom_panel(\fIpan\fB)\fR
+puts panel \fIpan\fP at the bottom of all panels.
+.\" ---------
+.SS ceiling_panel
+\fB\%ceiling_panel(\fIsp\fB)\fR
+acts like \fB\%panel_below(NULL)\fP
+for the given \fISCREEN\fP \fIsp\fP.
+.\" ---------
+.SS del_panel
+\fB\%del_panel(\fIpan\fB)\fR
+removes the given panel \fIpan\fP from the stack and deallocates the
+\fI\%PANEL\fP structure (but not its associated window).
+.\" ---------
+.SS ground_panel
+\fB\%ground_panel(\fIsp\fB)\fR
+acts like \fB\%panel_above(NULL)\fP
+for the given \fISCREEN\fP \fIsp\fP.
+.\" ---------
+.SS hide_panel
+\fB\%hide_panel(\fIpan\fB)\fR
+removes the given panel \fIpan\fP from the panel stack
+and thus hides it from view.
+The \fI\%PANEL\fP structure is not lost,
+merely removed from the stack.
+.\" ---------
+.SS move_panel
+\fB\%move_panel(\fIpan\fB, \fIstarty\fB, \fIstartx\fB)\fR
+moves the given panel \fIpan\fP's window so that its upper-left corner
+is at
+\fIstarty\fP,
+\fIstartx\fP.
+It does not change the position of the panel in the stack.
+Be sure to use this function,
+not \fB\%mvwin\fP(3X),
+to move a panel window.
+.\" ---------
+.SS new_panel
+\fB\%new_panel(\fIwin\fB)\fR allocates a \fI\%PANEL\fR structure,
+associates it with \fIwin\fP,
+places the panel on the top of the stack
+(causes it to be displayed above any other panel)
+and returns a pointer to the new panel.
+.\" ---------
+.SS panel_above
+\fB\%panel_above(\fIpan\fB)\fR
+returns a pointer to the panel above \fIpan\fP.
+If the panel argument is
+\*(``\fB(PANEL *)0\fP\*('',
+it returns a pointer to the bottom panel in the stack.
+.\" ---------
+.SS panel_below
+\fB\%panel_below(\fIpan\fB)\fR
+returns a pointer to the panel just below \fIpan\fP.
+If the panel argument is
+\*(``\fB(PANEL *)0\fP\*('',
+it returns a pointer to the top panel in the stack.
+.\" ---------
+.SS panel_hidden
+\fB\%panel_hidden(\fIpan\fB)\fR
+returns \fBFALSE\fP if the panel \fIpan\fP is in the panel stack,
+and \fBTRUE\fP if it is not.
+If the panel is a null pointer,
+it returns \fBERR\fP.
+.\" ---------
+.SS panel_userptr
+\fB\%panel_userptr(\fIpan\fB)\fR
+returns the user pointer for a given panel \fIpan\fP.
+.\" ---------
+.SS panel_window
+\fB\%panel_window(\fIpan\fB)\fR
+returns a pointer to the window of the given panel \fIpan\fP.
+.\" ---------
+.SS replace_panel
+\fB\%replace_panel(\fIpan\fB, \fIwindow\fB)\fR
+replaces the current window of panel \fIpan\fP with \fIwindow\fP
+This is useful if,
+for example,
+you want to resize a panel.
+In \fI\%ncurses\fP,
+you can call \fB\%replace_panel\fP
+to resize a panel using a window resized with \fB\%wresize\fP(3X).
+It does not change the position of the panel in the stack.
+.\" ---------
+.SS set_panel_userptr
+\fB\%set_panel_userptr(\fIpan\fB, \fIptr\fB)\fR
+sets the panel's user pointer.
+.\" ---------
+.SS show_panel
+\fB\%show_panel(\fIpan\fB)\fR
+makes a hidden panel visible by placing it on top of the panels in the
+panel stack.
+See \*(``PORTABILITY\*('' below.
+.\" ---------
+.SS top_panel
+\fB\%top_panel(\fIpan\fB)\fR
+puts the given visible panel \fIpan\fP on top of all panels in the
+stack.
+See \*(``PORTABILITY\*('' below.
+.\" ---------
+.SS update_panels
+\fB\%update_panels()\fR
+refreshes the virtual screen to reflect the relations between the panels
+in the stack,
+but does not call \fB\%doupdate\fP(3X) to refresh the physical screen.
+Use this function and not \fB\%wrefresh\fP(3X) or
+\fB\%wnoutrefresh\fP(3X).
+.PP
+\fB\%update_panels\fP may be called more than once before a call to
+\fB\%doupdate\fP,
+but \fB\%doupdate\fP is the function responsible for updating
+the physical screen.
+.SH "RETURN VALUE"
+Each routine that returns a pointer returns \fBNULL\fP if an error
+occurs.
+Each routine that returns an int value returns \fBOK\fP if it
+executes successfully and \fBERR\fP if not.
+.PP
+Except as noted,
+the \fIpan\fP and \fIwindow\fP parameters must be non-null.
+If either is null,
+an error is returned.
+.PP
+The \fB\%move_panel\fP function uses \fBmvwin\fP(3X),
+and returns an error if \fB\%mvwin\fP returns an error.
+.SH NOTES
+The header file \fI\%panel.h\fP itself includes the header file
+\fI\%curses.h\fP.
+.SH PORTABILITY
+Reasonable care has been taken to ensure compatibility
+with the native panel facility introduced in System\ V;
+inspection of the SVr4 manual pages suggests the programming interface
+never changed.
+The \fI\%PANEL\fP data structures are merely similar.
+The programmer is cautioned not to directly use \fI\%PANEL\fP fields.
+.PP
+The functions \fB\%show_panel\fP and \fB\%top_panel\fP are identical
+in this implementation,
+and work equally well with displayed or hidden panels.
+In the System\ V implementation,
+\fB\%show_panel\fP is intended for making a hidden panel visible
+(at the top of the stack)
+and \fB\%top_panel\fP is intended for making an already-visible panel
+move to the top of the stack.
+You are cautioned to use the correct
+function to ensure compatibility with System\ V panel libraries.
+.SH HISTORY
+A panel facility was documented in SVr4.2's
+\fICharacter User Interface Programming\fP document.
+.PP
+It is not part of X/Open Curses.
+.PP
+A few implementations exist:
+.bP
+Systems based on SVr4 source code,
+such as Solaris,
+provide this library.
+.bP
+\fI\%ncurses\fP (since version 0.6 in 1993)
+and \fIPDCurses\fP (since version 2.2 in 1995)
+provide a panel library whose common ancestor
+is a public domain implementation by Warren Tucker
+published in \fIu386mon\fP 2.20 (1990).
+.IP
+According to Tucker,
+the System\ V panel library was first released in SVr3.2 (1988),
+and his implementation helped with a port to SVr3.1 (1987).
+.IP
+Several developers have improved each of these;
+they are no longer the same as Tucker's implementation.
+.bP
+NetBSD 8 (2018)
+has a panel library begun by Valery Ushakov in 2015,
+based on the System\ V documentation.
+.SH AUTHORS
+Warren Tucker <wht@n4hgf.mt\-park.ga.us> originally wrote this
+implementation,
+primarily to assist in porting \fI\%u386mon\fP to systems without a
+native panel library.
+.PP
+Zeyd ben-Halim repackaged it for \fI\%ncurses\fP.
+.PP
+Juergen Pfeifer and Thomas E. Dickey revised and improved the library.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%curs_variables\fP(3X)
diff --git a/man/resizeterm.3x b/man/resizeterm.3x
index 177e705..5e23d9f 100644
--- a/man/resizeterm.3x
+++ b/man/resizeterm.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2013,2015 Free Software Foundation, Inc. *
+.\" 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 *
.\" copy of this software and associated documentation files (the *
@@ -28,73 +29,152 @@
.\"
.\" Author: Thomas E. Dickey 1996-on
.\"
-.\" $Id: resizeterm.3x,v 1.19 2015/06/06 23:38:18 tom Exp $
-.TH resizeterm 3X ""
+.\" $Id: resizeterm.3x,v 1.56 2024/03/16 15:35:01 tom Exp $
+.TH resizeterm 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBis_term_resized\fR,
-\fBresize_term\fR,
-\fBresizeterm\fR \- change the curses terminal size
+\fB\%is_term_resized\fP,
+\fB\%resize_term\fP,
+\fB\%resizeterm\fP \-
+manage the terminal dimensions understood by \fIcurses\fR
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBbool is_term_resized(int lines, int columns);\fR
-.br
-\fBint resize_term(int lines, int columns);\fR
-.br
-\fBint resizeterm(int lines, int columns);\fR
+.nf
+\fB#include <curses.h>
+.PP
+\fBbool is_term_resized(int \fIlines\fP, int \fIcolumns\fP);
+\fBint resize_term(int \fIlines\fP, int \fIcolumns\fP);
+\fBint resizeterm(int \fIlines\fP, int \fIcolumns\fP);
+.fi
.SH DESCRIPTION
+This is an extension to the \fIcurses\fP library.
+It provides callers with a hook into the \fI\%ncurses\fP data to resize
+windows,
+primarily for use by programs running in an X Window terminal (e.g., xterm)
+when the terminal's screen size is changed by the user:
+.bP
+\fIcurses\fP windows cannot extend outside the screen.
+If the terminal is shrunk, \fIcurses\fP windows must be shrunk to fit.
+.bP
+If the terminal is stretched,
+rows and/or columns can be added to existing windows.
+The added cells should match the current attributes of the windows.
.PP
-This is an extension to the curses library.
-It provides callers with a hook into the \fBncurses\fR data to resize windows,
-primarily for use by programs running in an X Window terminal (e.g., xterm).
+If the calling program has not set up a handler for \fB\%SIGWINCH\fP
+when it initializes \fI\%ncurses\fP
+(e.g., using \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X)),
+then \fI\%ncurses\fP sets a handler for \fB\%SIGWINCH\fP which notifies
+the library when a window-size event has occurred.
+The library checks for this notification
+.bP
+when reading input data,
+.bP
+when implicitly resuming program mode
+(e.g., between \fB\%endwin\fP(3X) and \fB\%wrefresh\fP(3X)),
+and
+.bP
+when explicitly resuming program mode in \fB\%restartterm\fP(3X).
+.PP
+When the library has found that the terminal's window-size has
+changed, it calls \fB\%resizeterm\fP to update its data structures.
+.PP
+An application which establishes its own \fB\%SIGWINCH\fP handler
+can call \fB\%resizeterm\fP, but in that case, the library will not
+see \fB\%SIGWINCH\fP, and proper layout will rely upon the application.
+.SH FUNCTIONS
.SS resizeterm
-.PP
-The function \fBresizeterm\fR resizes the standard and current windows
+The function \fB\%resizeterm\fP resizes the standard and current windows
+(i.e., \fB\%stdscr\fP and \fB\%curscr\fP)
to the specified dimensions, and adjusts other bookkeeping data used by
-the \fBncurses\fR library that record the window dimensions
-such as the \fBLINES\fP and \fBCOLS\fP variables.
+the \fI\%ncurses\fP library that record the window dimensions
+such as the \fB\%LINES\fP and \fB\%COLS\fP variables.
.SS resize_term
+Most of the work for \fB\%resizeterm\fP is
+done by the inner function \fB\%resize_term\fP.
+The outer function \fB\%resizeterm\fP adds bookkeeping
+for the \fB\%SIGWINCH\fP handler,
+as well as repainting the soft-key area (see \fB\%slk_touch\fP(3X)).
.PP
-Most of the work is done by the inner function \fBresize_term\fR.
-The outer function \fBresizeterm\fR adds bookkeeping for the SIGWINCH handler.
-When resizing the windows,
-\fBresize_term\fR blank-fills the areas that are extended.
-The calling application should fill in these areas with appropriate data.
-The \fBresize_term\fR function attempts to resize all windows.
-However, due to the calling convention of pads,
-it is not possible to resize these
-without additional interaction with the application.
+The \fB\%resize_term\fP function attempts to resize all windows.
+This helps with simple applications.
+However:
+.bP
+It is not possible to automatically resize pads.
+.bP
+Applications which have complicated layouts should check for
+\fB\%KEY_RESIZE\fP returned from \fB\%wgetch\fP,
+and adjust their layout, e.g., using \fB\%wresize\fP and \fB\%mvwin\fP,
+or by recreating the windows.
+.PP
+When resizing windows, \fB\%resize_term\fP recursively adjusts subwindows,
+keeping them within the updated parent window's limits.
+If a top-level window happens to extend to the screen's limits,
+then on resizing the window, \fB\%resize_term\fP will keep the window
+extending to the corresponding limit, regardless of whether the
+screen has shrunk or grown.
.SS is_term_resized
-.PP
-A support function \fBis_term_resized\fR is provided so that applications
-can check if the \fBresize_term\fR function would modify the window structures.
-It returns \fBTRUE\fP if the windows would be modified, and \fBFALSE\fP otherwise.
+A support function \fB\%is_term_resized\fP is provided so that applications
+can check if the \fB\%resize_term\fP function would modify
+the window structures.
+It returns \fBTRUE\fP if the windows would be modified,
+and \fBFALSE\fP otherwise.
.SH RETURN VALUE
Except as noted, these functions return
-the integer \fBERR\fR upon failure and \fBOK\fR on success.
+the integer \fBERR\fP upon failure and \fBOK\fP on success.
They will fail if either of the dimensions are less than or equal to zero,
or if an error occurs while (re)allocating memory for the windows.
.SH NOTES
While these functions are intended to be used to support a signal handler
-(i.e., for SIGWINCH), care should be taken to avoid invoking them in a
-context where \fBmalloc\fR or \fBrealloc\fR may have been interrupted,
+(i.e., for \fB\%SIGWINCH\fP), care should be taken to avoid invoking them in a
+context where \fB\%malloc\fP or \fB\%realloc\fP may have been interrupted,
since it uses those functions.
.PP
-If ncurses is configured to supply its own SIGWINCH handler,
-the \fBresizeterm\fR function \fBungetch\fP's a \fBKEY_RESIZE\fR which
-will be read on the next call to \fBgetch\fR.
-This is used to alert an application that the screen size has changed,
+If \fI\%ncurses\fP is configured to supply its own \fB\%SIGWINCH\fP
+handler,
+.bP
+on receipt of a \fB\%SIGWINCH\fP, the handler sets a flag
+.bP
+which is tested in
+\fB\%wgetch\fP(3X),
+\fB\%doupdate\fP(3X) and
+\fB\%restartterm\fP(3X),
+.bP
+in turn, calling the \fB\%resizeterm\fP function,
+.bP
+which \fB\%ungetch\fP's a \fB\%KEY_RESIZE\fP which
+will be read on the next call to \fB\%wgetch\fP.
+.IP
+The \fB\%KEY_RESIZE\fP alerts an application that the screen size has changed,
and that it should repaint special features such as pads that cannot
be done automatically.
+.IP
+Calling \fB\%resizeterm\fP or \fB\%resize_term\fP
+directly from a signal handler is unsafe.
+This indirect method is used to provide a safe way to resize the
+\fI\%ncurses\fP data structures.
.PP
-If the environment variables \fBLINES\fP or \fBCOLUMNS\fP are set,
+If the environment variables \fILINES\fP or \fI\%COLUMNS\fP are set,
this overrides the library's use of the window size obtained from
the operating system.
-Thus, even if a SIGWINCH is received,
+Thus, even if a \fB\%SIGWINCH\fP is received,
no screen size change may be recorded.
+.SH PORTABILITY
+It is possible to resize the screen with SVr4 \fIcurses\fP,
+by
+.bP
+exiting \fIcurses\fP with \fB\%endwin\fP(3X) and
+.bP
+resuming using \fB\%refresh\fP(3X).
+.PP
+Doing that clears the screen and is visually distracting.
+.PP
+This extension of \fI\%ncurses\fP was introduced in mid-1995.
+It was adopted in NetBSD \fIcurses\fP (2001) and PDCurses (2003).
+.SH AUTHORS
+Thomas Dickey (from an equivalent function written in 1988 for BSD \fIcurses\fP)
.SH SEE ALSO
-\fBcurs_getch\fR(3X),
-\fBcurs_variables\fR(3X),
-\fBwresize\fR(3X).
-.SH AUTHOR
-Thomas Dickey (from an equivalent function written in 1988 for BSD curses).
+\fB\%curs_getch\fP(3X),
+\fB\%curs_variables\fP(3X),
+\fB\%wresize\fP(3X)
diff --git a/man/scr_dump.5 b/man/scr_dump.5
new file mode 100644
index 0000000..95b2142
--- /dev/null
+++ b/man/scr_dump.5
@@ -0,0 +1,476 @@
+.\"***************************************************************************
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 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 *
+.\" "Software"), to deal in the Software without restriction, including *
+.\" without limitation the rights to use, copy, modify, merge, publish, *
+.\" distribute, distribute with modifications, sublicense, and/or sell *
+.\" copies of the Software, and to permit persons to whom the Software is *
+.\" furnished to do so, subject to the following conditions: *
+.\" *
+.\" The above copyright notice and this permission notice shall be included *
+.\" in all copies or substantial portions of the Software. *
+.\" *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
+.\" *
+.\" Except as contained in this notice, the name(s) of the above copyright *
+.\" holders shall not be used in advertising or otherwise to promote the *
+.\" sale, use or other dealings in this Software without prior written *
+.\" authorization. *
+.\"***************************************************************************
+.\"
+.\" $Id: scr_dump.5,v 1.46 2024/03/23 20:42:29 tom Exp $
+.TH scr_dump 5 2024-03-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
+.SH NAME
+scr_dump \-
+\fIcurses\fR screen dump
+.\"SH SYNOPSIS
+.SH DESCRIPTION
+The curses library provides applications with the ability to write the
+contents of a window to an external file using \fBscr_dump\fP or \fBputwin\fP,
+and read it back using \fBscr_restore\fP or \fBgetwin\fP.
+.PP
+The \fBputwin\fP and \fBgetwin\fP functions do the work;
+while \fBscr_dump\fP and \fBscr_restore\fP conveniently save and restore
+the whole screen, i.e., \fBstdscr\fP.
+.SS ncurses6
+A longstanding implementation of screen-dump was
+revised with ncurses6 to remedy problems with the earlier approach:
+.IP \(bu 4
+A \*(``magic number\*('' is written to the beginning of the dump file,
+allowing applications (such as \fBfile\fP(1)) to recognize curses dump files.
+.IP
+Because ncurses6 uses a new format,
+that requires a new magic number
+was unused by other applications.
+This 16-bit number was unused:
+.RS 4
+.PP
+.RS 4
+.EX
+0x8888 (octal \*(``\e210\e210\*('')
+.EE
+.RE
+.PP
+but to be more certain, this 32-bit number was chosen:
+.PP
+.RS 4
+.EX
+0x88888888 (octal \*(``\e210\e210\e210\e210\*('')
+.EE
+.RE
+.PP
+This is the pattern submitted to the maintainers of the \fBfile\fP program:
+.PP
+.RS 4
+.EX
+#
+# ncurses5 (and before) did not use a magic number,
+# making screen dumps "data".
+#
+# ncurses6 (2015) uses this format, ignoring byte-order
+0 string \e210\e210\e210\e210ncurses ncurses6 screen image
+#
+.EE
+.RE
+.RE
+.bP
+The screen dumps are written in textual form,
+so that internal data sizes are not directly related to the dump-format, and
+enabling the library to read dumps from either narrow- or wide-character-
+configurations.
+.IP
+The \fInarrow\fP library configuration holds characters and video attributes
+in a 32-bit \fBchtype\fP, while the \fIwide-character\fP library stores
+this information in the \fBcchar_t\fP structure, which is much larger than
+32-bits.
+.bP
+It is possible to read a screen dump into a terminal with a different
+screen-size,
+because the library truncates or fills the screen as necessary.
+.bP
+The ncurses6 \fBgetwin\fP reads the legacy screen dumps from ncurses5.
+.SS "ncurses5 (Legacy)"
+The screen-dump feature was added to \fI\%ncurses\fP in June 1995.
+While there were fixes and improvements in succeeding years,
+the basic scheme was unchanged:
+.bP
+The \fI\%WINDOW\fP structure was written in binary form.
+.bP
+The \fI\%WINDOW\fP structure refers to lines of data,
+which were written as an array of binary data following the \fI\%WINDOW\fP.
+.bP
+When \fBgetwin\fP restored the window,
+it would keep track of offsets into the array of line-data
+and adjust the \fI\%WINDOW\fP structure which was read back into memory.
+.PP
+This is similar to Unix System\ V,
+but does not write a \*(``magic number\*('' to identify the file format.
+.SH PORTABILITY
+There is no standard format for
+.I curses
+screen dumps.
+A brief survey of the existing implementations follows.
+.SS "X/Open Curses"
+X/Open Curses, Issue 7 specifies little.
+It says
+(boldface emphasis added)
+.RS 3
+.PP
+\*(``[t]he \fI\%getwin()\fP function reads window-related data stored in
+the file by \fI\%putwin()\fP.
+The function then creates and initializes a new window using that data.
+.PP
+The \fI\%putwin()\fP function writes all data associated with \fIwin\fP
+into the \fI\%stdio\fP stream to which \fIfilep\fP points,
+using an \fBunspecified format\fP.
+This information can be retrieved later using \fI\%getwin()\fP.\*(''
+.RE
+.PP
+In the mid-1990s when the X/Open Curses document was written,
+there were still System\ V systems using older,
+less capable
+.I curses
+libraries.
+BSD
+.I curses
+was not relevant to X/Open because it did not meet the criteria
+for base-level conformance;
+see \fB\%ncurses\fP(3X).
+.SS "System V"
+System\ V
+.I curses
+identified the file format by writing a \*(``magic number\*('' at the
+beginning of the dump.
+The \fI\%WINDOW\fP data and the lines of text follow, all in binary form.
+.PP
+Solaris
+.I curses
+has the following definitions.
+.PP
+.RS 4
+.EX
+/* terminfo magic number */
+#define MAGNUM 0432
+
+/* curses screen dump magic number */
+#define SVR2_DUMP_MAGIC_NUMBER 0433
+#define SVR3_DUMP_MAGIC_NUMBER 0434
+.EE
+.RE
+.PP
+That is, the feature was likely introduced in SVr2 (1984),
+and improved in SVr3 (1987).
+Solaris
+.I curses
+has no magic number for SVr4 (1989).
+Other System\ V operating systems
+(AIX and HP-UX)
+use a magic number that would correspond to the following.
+.PP
+.RS 4
+.EX
+/* curses screen dump magic number */
+#define SVR4_DUMP_MAGIC_NUMBER 0435
+.EE
+.RE
+.PP
+That octal number in bytes is 001, 035.
+Because most Unix vendors at the time used big-endian hardware,
+the magic number is written with the high-order byte first.
+.PP
+.RS 4
+.EX
+\e001\e035
+.EE
+.RE
+.PP
+After the magic number,
+the \fI\%WINDOW\fP structure and line data are written in binary format.
+While the magic number used by these systems can be observed with
+\fIod\fP(1),
+none of them documents the format used for screen dumps.
+.PP
+Nor do they use an identical format,
+even with the System\ V family.
+The
+.I \%ncurses
+.I \%savescreen
+test program was used to collect information for this manual page.
+It produced dumps of different size
+(all on 64-bit hardware,
+on 40x80 screens):
+.bP
+AIX (51817 bytes)
+.bP
+HP-UX (90093 bytes)
+.bP
+Solaris 10 (13273 bytes)
+.bP
+\fI\%ncurses\fP5 (12888 bytes)
+.SS Solaris
+As noted above,
+Solaris
+.I curses
+has no magic number corresponding to SVr4
+.IR curses .
+This is odd,
+since Solaris was the first operating system to meet the SVr4
+guidelines.
+Solaris furthermore supplies two versions of
+.IR curses .
+.bP
+The default
+.I curses
+library uses the SVr3 magic number.
+.bP
+An alternate
+.I curses
+library
+(which we term
+.I \%xcurses),
+available in
+.IR /usr/xpg4 ,
+uses a textual format with no magic number.
+.IP
+According to its copyright notice,
+this
+.I \%xcurses
+library was developed by MKS
+(Mortice Kern Systems) from 1990 to 1995.
+.IP
+Like ncurses6,
+it includes a header with parameters.
+Unlike ncurses6,
+the contents of the window are written piecemeal,
+with coordinates and attributes for each chunk of text rather than
+writing the whole window from top to bottom.
+.SS PDCurses
+.I \%PDCurses
+added support for screen dumps in version 2.7 (2005).
+Like System\ V and ncurses5,
+it writes the \fI\%WINDOW\fP structure in binary,
+but begins the file with its three-byte identifier \*(``PDC\*('',
+followed by a single-byte version number.
+.PP
+.RS 4
+.EX
+ \*(``PDC\e001\*(''
+.EE
+.RE
+.SS NetBSD
+As of April 2017,
+NetBSD
+.I curses
+does not support \fB\%scr_dump\fP and \fB\%scr_restore\fP
+(or \fB\%scr_init\fP,
+\fB\%scr_set\fP),
+although it has \fB\%putwin\fP and \fB\%getwin\fP.
+.PP
+Like ncurses5,
+NetBSD \fB\%putwin\fP does not identify its dumps with a useful magic
+number.
+It writes
+.bP
+the
+.I curses
+shared library major and minor versions as the first two bytes
+(for example,
+7 and 1),
+.bP
+followed by a binary dump of the \fI\%WINDOW\fP,
+.bP
+some data for wide characters referenced by the \fI\%WINDOW\fP
+structure,
+and
+.bP
+finally,
+lines as done by other implementations.
+.SH EXAMPLES
+Given a simple program which writes text to the screen
+(and for the sake of example, limiting the screen-size to 10x20):
+.PP
+.RS 4
+.EX
+#include <curses.h>
+
+int
+main(void)
+{
+ putenv("LINES=10");
+ putenv("COLUMNS=20");
+ initscr();
+ start_color();
+ init_pair(1, COLOR_WHITE, COLOR_BLUE);
+ init_pair(2, COLOR_RED, COLOR_BLACK);
+ bkgd(COLOR_PAIR(1));
+ move(4, 5);
+ attron(A_BOLD);
+ addstr("Hello");
+ move(5, 5);
+ attroff(A_BOLD);
+ attrset(A_REVERSE | COLOR_PAIR(2));
+ addstr("World!");
+ refresh();
+ scr_dump("foo.out");
+ endwin();
+ return 0;
+}
+.EE
+.RE
+.PP
+When run using ncurses6, the output looks like this:
+.PP
+.RS 4
+.EX
+\e210\e210\e210\e210ncurses 6.0.20170415
+_cury=5
+_curx=11
+_maxy=9
+_maxx=19
+_flags=14
+_attrs=\e{REVERSE|C2}
+flag=_idcok
+_delay=-1
+_regbottom=9
+_bkgrnd=\e{NORMAL|C1}\es
+rows:
+1:\e{NORMAL|C1}\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es
+2:\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es
+3:\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es
+4:\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es
+5:\es\es\es\es\es\e{BOLD}Hello\e{NORMAL}\es\es\es\es\es\es\es\es\es\es
+6:\es\es\es\es\es\e{REVERSE|C2}World!\e{NORMAL|C1}\es\es\es\es\es\es\es\es\es
+7:\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es
+8:\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es
+9:\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es
+10:\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es
+.EE
+.RE
+.PP
+The first four octal escapes are actually nonprinting characters,
+while the remainder of the file is printable text.
+You may notice:
+.bP
+The actual color pair values are not written to the file.
+.bP
+All characters are shown in printable form; spaces are \*(``\es\*('' to
+ensure they are not overlooked.
+.bP
+Attributes are written in escaped curly braces, e.g., \*(``\e{BOLD}\*('',
+and may include a color pair (C1 or C2 in this example).
+.bP
+The parameters in the header are written out only if they are nonzero.
+When reading back, order does not matter.
+.ne 10
+.PP
+Running the same program with Solaris \fIxpg4\fP curses gives this dump:
+.PP
+.RS 4
+.EX
+MAX=10,20
+BEG=0,0
+SCROLL=0,10
+VMIN=1
+VTIME=0
+FLAGS=0x1000
+FG=0,0
+BG=0,0,
+0,0,0,1,
+0,19,0,0,
+1,0,0,1,
+1,19,0,0,
+2,0,0,1,
+2,19,0,0,
+3,0,0,1,
+3,19,0,0,
+4,0,0,1,
+4,5,0x20,0,Hello
+4,10,0,1,
+4,19,0,0,
+5,0,0,1,
+5,5,0x4,2,World!
+5,11,0,1,
+5,19,0,0,
+6,0,0,1,
+6,19,0,0,
+7,0,0,1,
+7,19,0,0,
+8,0,0,1,
+8,19,0,0,
+9,0,0,1,
+9,19,0,0,
+CUR=11,5
+.EE
+.RE
+.PP
+Solaris \fBgetwin\fP requires that all parameters are present, and
+in the same order.
+The \fIxpg4\fP curses library does not know about the \fBbce\fP
+(back color erase) capability, and does not color the window background.
+.ne 10
+.PP
+On the other hand, the SVr4 curses library does know about the background color.
+However, its screen dumps are in binary.
+Here is the corresponding dump (using \*(``od \-t x1\*(''):
+.PP
+.RS 4
+.EX
+0000000 1c 01 c3 d6 f3 58 05 00 0b 00 0a 00 14 00 00 00
+0000020 00 00 02 00 00 00 00 00 00 00 00 00 00 00 00 00
+0000040 00 00 b8 1a 06 08 cc 1a 06 08 00 00 09 00 10 00
+0000060 00 00 00 80 00 00 20 00 00 00 ff ff ff ff 00 00
+0000100 ff ff ff ff 00 00 00 00 20 80 00 00 20 80 00 00
+0000120 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
+*
+0000620 20 80 00 00 20 80 00 00 20 80 00 00 48 80 00 04
+0000640 65 80 00 04 6c 80 00 04 6c 80 00 04 6f 80 00 04
+0000660 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
+*
+0000740 20 80 00 00 20 80 00 00 20 80 00 00 57 00 81 00
+0000760 6f 00 81 00 72 00 81 00 6c 00 81 00 64 00 81 00
+0001000 21 00 81 00 20 80 00 00 20 80 00 00 20 80 00 00
+0001020 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
+*
+0001540 20 80 00 00 20 80 00 00 00 00 f6 d1 01 00 f6 d1
+0001560 08 00 00 00 40 00 00 00 00 00 00 00 00 00 00 07
+0001600 00 04 00 01 00 01 00 00 00 01 00 00 00 00 00 00
+0001620 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+*
+0002371
+.EE
+.RE
+.SH AUTHORS
+Thomas E. Dickey
+.br
+extended screen-dump format for \fI\%ncurses\fP 6.0 (2015)
+.sp
+Eric S. Raymond
+.br
+screen dump feature in \fI\%ncurses\fP 1.9.2d (1995)
+.SH SEE ALSO
+\fB\%curs_scr_dump\fP(3X),
+\fB\%curs_util\fP(3X)
diff --git a/man/tabs.1 b/man/tabs.1
index f6b797d..059bc1e 100644
--- a/man/tabs.1
+++ b/man/tabs.1
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2008-2011,2013 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 2008-2016,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 *
@@ -26,25 +27,66 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tabs.1,v 1.11 2013/06/22 18:11:57 tom Exp $
-.TH @TABS@ 1 ""
-.ds n 5
+.\" $Id: tabs.1,v 1.59 2024/04/20 19:08:15 tom Exp $
+.TH @TABS@ 1 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
+.
.SH NAME
-\fB@TABS@\fR \- set tabs on a terminal
+\fB\%@TABS@\fP \-
+set terminal tab stops
.SH SYNOPSIS
-\fB@TABS@\fR [\fIoptions\fR]] \fI[tabstop-list]\fR
+\fB@TABS@\fP [\fIoptions\fP] [\fItabstop-list\fP]
.SH DESCRIPTION
-.PP
The \fB@TABS@\fP program clears and sets tab-stops on the terminal.
-This uses the terminfo \fIclear_all_tabs\fP and \fIset_tab\fP capabilities.
+This uses the terminfo \fBclear_all_tabs\fP and \fBset_tab\fP capabilities.
If either is absent, \fB@TABS@\fP is unable to clear/set tab-stops.
The terminal should be configured to use hard tabs, e.g.,
-.sp
-.RS
+.PP
+.RS 4
+.EX
stty tab0
+.EE
.RE
+.PP
+Like \fB@CLEAR@\fP(1), \fB@TABS@\fP writes to the standard output.
+You can redirect the standard output to a file (which prevents
+\fB@TABS@\fP from actually changing the tabstops),
+and later \fBcat\fP the file to the screen, setting tabstops at that point.
+.PP
+These are hardware tabs, which cannot be queried rapidly by applications
+running in the terminal, if at all.
+Curses and other full-screen applications may use hardware tabs
+in optimizing their output to the terminal.
+If the hardware tabstops differ from the information in the terminal
+database, the result is unpredictable.
+Before running curses programs,
+you should either reset tab-stops to the standard interval
+.PP
+.RS 4
+.EX
+tabs \-8
+.EE
+.RE
+.PP
+or use the \fB@RESET@\fP program,
+since the normal initialization sequences do not ensure that tab-stops
+are reset.
.SH OPTIONS
-.SS General Options
+.SS "General Options"
.TP 5
.BI \-T "name"
Tell \fB@TABS@\fP which terminal type to use.
@@ -61,83 +103,255 @@
This option tells \fB@TABS@\fP to check the options and run any debugging
option, but not to modify the terminal settings.
.TP
-\fB\-V\fR
-reports the version of ncurses which was used in this program, and exits.
+\fB\-V\fP
+reports the version of \fI\%ncurses\fP which was used in this program,
+and exits.
.PP
The \fB@TABS@\fP program processes a single list of tab stops.
The last option to be processed which defines a list is the one that
determines the list to be processed.
-.SS Implicit Lists
-Use a single number as an option, e.g., "\fB\-5\fP" to set tabs at the given
-interval (in this case 1, 6, 11, 16, 21, etc.). Tabs are repeated up to
-the right margin of the screen.
+.SS "Implicit Lists"
+Use a single number as an option,
+e.g., \*(``\fB\-5\fP\*('' to set tabs at the given
+interval (in this case 1, 6, 11, 16, 21, etc.).
+Tabs are repeated up to the right margin of the screen.
.PP
-Use "\fB\-0\fP" to clear all tabs.
+Use \*(``\fB\-0\fP\*('' to clear all tabs.
.PP
-Use "\fB\-8\fP" to set tabs to the standard interval.
-.SS Explicit Lists
-An explicit list can be defined after the options (this does not use a "\-").
-The values in the list must be in increasing numeric order, and greater than
-zero. They are separated by a comma or a blank, for example,
-.sp
-.RS
+Use \*(``\fB\-8\fP\*('' to set tabs to the standard interval.
+.SS "Explicit Lists"
+An explicit list can be defined after the options
+(this does not use a \*(``\-\*('').
+The values in the list must be in increasing numeric order,
+and greater than zero.
+They are separated by a comma or a blank, for example,
+.PP
+.RS 4
+.EX
tabs 1,6,11,16,21
-.br
tabs 1 6 11 16 21
+.EE
.RE
-Use a '+' to treat a number as an increment relative to the previous value,
+.PP
+Use a \*(``+\*('' to treat a number
+as an increment relative to the previous value,
e.g.,
-.sp
-.RS
+.PP
+.RS 4
+.EX
tabs 1,+5,+5,+5,+5
+.EE
.RE
+.PP
which is equivalent to the 1,6,11,16,21 example.
-.SS Predefined Tab-Stops
-X/Open defines several predefined lists of tab stops.
+.SS "Predefined Tab Stops"
+POSIX defines several predefined lists of tab stops.
.TP 5
.B \-a
Assembler, IBM S/370, first format
+.br
+1,10,16,36,72
.TP 5
.B \-a2
Assembler, IBM S/370, second format
+.br
+1,10,16,40,72
.TP 5
.B \-c
COBOL, normal format
+.br
+1,8,12,16,20,55
.TP 5
.B \-c2
COBOL compact format
+.br
+1,6,10,14,49
.TP 5
.B \-c3
COBOL compact format extended
+.br
+1,6,10,14,18,22,26,30,34,38,42,46,50,54,58,62,67
.TP 5
.B \-f
FORTRAN
+.br
+1,7,11,15,19,23
.TP 5
.B \-p
PL/I
+.br
+1,5,9,13,17,21,25,29,33,37,41,45,49,53,57,61
.TP 5
.B \-s
SNOBOL
+.br
+1,10,55
.TP 5
.B \-u
UNIVAC 1100 Assembler
+.br
+1,12,20,44
+.SS Margins
+A few terminals expose a means of changing their left and right margins.
+\fB@TABS@\fP supports this feature with an option.
+.TP 5
+.BI +m \ margin
+The effect depends on whether the terminal has the margin capabilities:
+.RS
+.bP
+If the terminal provides the capability for setting the left margin,
+\fB@TABS@\fP uses this,
+and adjusts the available tab stop widths.
+.bP
+If the terminal does not provide the margin capabilities,
+\fB@TABS@\fP imitates their effect,
+putting tab stops at appropriate places on each line.
+The terminal's left margin is not modified.
+.RE
+.IP
+If the
+.I margin
+parameter is omitted,
+the default is 10.
+Use
+.B +m0
+to reset the left margin,
+that is,
+to make it the left edge of the terminal's display.
+Before setting a left margin,
+\fB@TABS@\fP resets the margin to reduce problems that might arise
+from moving the cursor to the left of the current left margin.
+.PP
+When setting or resetting the left margin,
+\fB@TABS@\fP may also reset the right margin.
+.SH FILES
+.TP
+.I @DATADIR@/tabset
+tab stop initialization database
.SH PORTABILITY
+IEEE Std 1003.1/The Open Group Base Specifications Issue 7
+(POSIX.1-2008)
+describes a
+.B tabs
+utility.
+However,
+.bP
+this standard describes a
+.B +m
+option to set a terminal's left margin.
+Very few of the entries in the terminal database provide the
+.B \%set_left_margin
+.RB ( smgl )
+or
+.B \%set_left_margin_parm
+.RB \%( smglp )
+capabilities needed to support the feature.
+.bP
+There is no counterpart in X/Open Curses Issue 7 for this utility,
+unlike \fB@TPUT@\fP(1).
.PP
-X/Open describes a \fB+m\fP option, to set a terminal's left-margin.
-Very few of the entries in the terminal database provide this capability.
+The
+.B \-d
+(debug) and
+.B \-n
+(no-op) options are
+.I \%ncurses
+extensions not provided by other implementations.
+.SH HISTORY
+A
+.B tabs
+utility appeared in PWB/Unix 1.0 (1977).
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=PWB1/sys/source/s2/\
+.\" tabs.c
+A reduced version shipped in Seventh Edition Unix
+(early 1979)
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/src/cmd/tabs.c
+and in 3BSD
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/cmd/\
+.\" tabs.c
+(later the same year);
+it supported a \*(``\-n\*('' option to set the first tab stop at the
+left margin.
+That option is not specified by POSIX.
.PP
-The \fB\-d\fP (debug) and \fB\-n\fP (no-op) options are extensions not provided
-by other implementations.
+The PWB/Unix
+.B tabs
+utility returned in System III (1980),
+and used built-in tables
+to support a half-dozen hardcopy terminal (printer) types.
+It also had logic to support setting the left margin,
+as well as a feature for copying the tab settings from a file.
.PP
-Documentation for other implementations states that there is a limit on the
-number of tab stops. While some terminals may not accept an arbitrary number
-of tab stops, this implementation will attempt to set tab stops up to the
-right margin of the screen, if the given list happens to be that long.
+Versions of the program in later releases of AT&T Unix,
+such as SVr4,
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=SysVR4/cmd/tabs/tabs.c
+added support for the terminal database,
+but retained the tables to support the printers.
+By this time,
+System\ V
+.B tput
+had incorporated the tab stop initialization feature of BSD's
+.B tset
+from 1982,
+but employed the
+.I \%term\%info
+database to do so.
+.PP
+The
+.B +m
+option was documented in the POSIX Base Specifications Issue 5
+(Unix98, 1997),
+then omitted in Issue 6
+(Unix03, 2004)
+without express motivation,
+though an introductory comment
+\*(``and optionally adjusts the margin\*('' remains,
+overlooked in the removal.
+The
+.B tabs
+utility documented in Issues 6 and later has no mechanism for setting
+margins.
+The
+.B +m
+option in
+.I \%ncurses
+\fB\%@TABS@\fP differs from the SVr4 feature by using terminal
+capabilities rather than built-in tables.
+.PP
+POSIX documents no limit on the number of tab stops.
+Other implementations impose one;
+the limit is 20 in PWB/Unix's
+.B tabs
+utility.
+While some terminals may not accept an arbitrary number of tab stops,
+.I \%ncurses
+\fB\%@TABS@\fP attempts to set tab stops up to the right margin if the
+list thereof is sufficiently long.
+.PP
+The \*(``Rationale\*('' section of the Issue 6
+.B tabs
+reference page
+.\" https://pubs.opengroup.org/onlinepubs/009604499/utilities/tabs.html
+details how the committee considered redesigning the
+.B tabs
+and
+.B tput
+utilities,
+without settling on an improved solution.
+It claims that
+.PP
+.RS 4
+\*(``no known historical version of
+.I tabs
+supports the capability of setting arbitrary tab stops.\*(''
+.RE
+.PP
+The feature described in subsection \*(``Explicit Lists\*('' above was
+implemented in PWB/Unix,
+.\" see URL above
+and permitted the setting of abitrary tab stops nevertheless.
.SH SEE ALSO
-\fB@TSET@\fR(1),
-\fB@INFOCMP@\fR(1M),
-\fBcurses\fR(3X),
-\fBterminfo\fR(\*n).
-.PP
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
+\fB\%@INFOCMP@\fP(1M),
+\fB\%@TSET@\fP(1),
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(5)
diff --git a/man/term.5 b/man/term.5
index a4cca9c..cec231f 100644
--- a/man/term.5
+++ b/man/term.5
@@ -1,5 +1,7 @@
+'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2015 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -26,22 +28,48 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: term.5,v 1.22 2015/04/26 14:50:23 tom Exp $
-.TH term 5
-.ds n 5
+.\" $Id: term.5,v 1.77 2024/04/20 21:24:19 tom Exp $
+.TH term 5 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.ds ' \(aq
+.ds ^ \(ha
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.ds ' '
+.ds ^ ^
+.\}
+.ie n .ds CW R
+.el \{
+.ie \n(.g .ds CW CR
+.el .ds CW CW
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
+.
.ds d @TERMINFO@
.SH NAME
-term \- format of compiled term file.
+term \-
+compiled \fIterminfo\fR terminal description
.SH SYNOPSIS
.B term
.SH DESCRIPTION
-.SS STORAGE LOCATION
+.SS "Storage Location"
Compiled terminfo descriptions are placed under the directory \fB\*d\fP.
-Two configurations are supported (when building the ncurses libraries):
+Two configurations are supported
+(when building the \fI\%ncurses\fP libraries):
.TP 5
.B directory tree
A two-level scheme is used to avoid a linear search
-of a huge \s-1UNIX\s+1 system directory: \fB\*d/c/name\fP where
+of a huge Unix system directory: \fB\*d/c/name\fP where
.I name
is the name of the terminal, and
.I c
@@ -60,119 +88,155 @@
and records containing only aliases pointing to the primary name.
.IP
If built to write hashed databases,
-ncurses can still read terminfo databases organized as a directory tree,
+\fI\%ncurses\fP can still read terminfo databases organized as a
+directory tree,
but cannot write entries into the directory tree.
It can write (or rewrite) entries in the hashed database.
.IP
-ncurses distinguishes the two cases in the TERMINFO and TERMINFO_DIRS
-environment variable by assuming a directory tree for entries that
-correspond to an existing directory,
+\fI\%ncurses\fP distinguishes the two cases in the \fI\%TERMINFO\fP and
+\fI\%TERMINFO_DIRS\fP environment variable by assuming a directory tree
+for entries that correspond to an existing directory,
and hashed database otherwise.
-.SS STORAGE FORMAT
+.SS "Legacy Storage Format"
The format has been chosen so that it will be the same on all hardware.
An 8 or more bit byte is assumed, but no assumptions about byte ordering
or sign extension are made.
.PP
-The compiled file is created with the
-.B @TIC@
-program, and read by the routine
-.IR setupterm .
+The compiled file is created with the \fB@TIC@\fP program,
+and read by the routine \fBsetupterm\fP(3X).
The file is divided into six parts:
-the header,
-terminal names,
-boolean flags,
-numbers,
-strings,
-and
-string table.
+.RS 5
+.TP 3
+a) \fIheader\fP,
+.TP 3
+b) \fIterminal names\fP,
+.TP 3
+c) \fIBoolean flags\fP,
+.TP 3
+d) \fInumbers\fP,
+.TP 3
+e) \fIstrings\fP, and
+.TP 3
+f) \fIstring table\fP.
+.RE
.PP
-The header section begins the file.
+The \fIheader\fP section begins the file.
This section contains six short integers in the format
described below.
These integers are
.RS 5
.TP 5
-(1) the magic number (octal 0432);
+(1) the \fImagic number\fP (octal 0432);
.TP 5
-(2) the size, in bytes, of the names section;
+(2) the size, in bytes, of the \fIterminal names\fP section;
.TP 5
-(3) the number of bytes in the boolean section;
+(3) the number of bytes in the \fIBoolean flags\fP section;
.TP 5
-(4) the number of short integers in the numbers section;
+(4) the number of short integers in the \fInumbers\fP section;
.TP 5
-(5) the number of offsets (short integers) in the strings section;
+(5) the number of offsets (short integers) in the \fIstrings\fP section;
.TP 5
-(6) the size, in bytes, of the string table.
+(6) the size, in bytes, of the \fIstring table\fP.
.RE
.PP
-Short integers are stored in two 8-bit bytes.
+The capabilities in the
+\fIBoolean flags\fP,
+\fInumbers\fP, and
+\fIstrings\fP
+sections are in the same order as the file <term.h>.
+.PP
+Short integers are signed, in the range \-32768 to 32767.
+They are stored as two 8-bit bytes.
The first byte contains the least significant 8 bits of the value,
and the second byte contains the most significant 8 bits.
(Thus, the value represented is 256*second+first.)
-The value \-1 is represented by the two bytes 0377, 0377; other negative
-values are illegal. This value generally
-means that the corresponding capability is missing from this terminal.
-Note that this format corresponds to the hardware of the \s-1VAX\s+1
+This format corresponds to the hardware of the \s-1VAX\s+1
and \s-1PDP\s+1-11 (that is, little-endian machines).
Machines where this does not correspond to the hardware must read the
integers as two bytes and compute the little-endian value.
.PP
-The terminal names section comes next.
+Numbers in a terminal description,
+whether they are entries in the \fInumbers\fP or \fIstrings\fP table,
+are positive integers.
+Boolean flags are treated as positive one-byte integers.
+In each case, those positive integers represent a terminal capability.
+The terminal compiler @TIC@ uses negative integers to handle the cases where
+a capability is not available:
+.bP
+If a capability is absent from this terminal,
+@TIC@ stores a \-1 in the corresponding table.
+.IP
+The integer value \-1 is represented by two bytes 0377, 0377.
+.br
+Absent Boolean values are represented by the byte 0 (false).
+.bP
+If a capability has been canceled from this terminal,
+@TIC@ stores a \-2 in the corresponding table.
+.IP
+The integer value \-2 is represented by two bytes 0377, 0376.
+.br
+The Boolean value \-2 is represented by the byte 0376.
+.br
+.bP
+Other negative values are illegal.
+.PP
+The \fIterminal names\fP section comes after the \fIheader\fP.
It contains the first line of the terminfo description,
listing the various names for the terminal,
-separated by the `|' character.
-The section is terminated with an \s-1ASCII NUL\s+1 character.
+separated by the \*(``|\*('' character.
+The \fIterminal names\fP section is terminated
+with an \s-1ASCII NUL\s+1 character.
.PP
-The boolean flags have one byte for each flag.
-This byte is either 0 or 1 as the flag is present or absent.
-The capabilities are in the same order as the file <term.h>.
+The \fIBoolean flags\fP section has one byte for each flag.
+Boolean capabilities are either 1 or 0 (true or false)
+according to whether the terminal supports the given capability or not.
.PP
-Between the boolean section and the number section,
+Between the \fIBoolean flags\fP section and the \fInumber\fP section,
a null byte will be inserted, if necessary,
-to ensure that the number section begins on an even byte (this is a
-relic of the PDP\-11's word-addressed architecture, originally
-designed in to avoid IOT traps induced by addressing a word on an
-odd byte boundary).
+to ensure that the \fInumber\fP section begins on an even byte
+This is a relic of the PDP\-11's word-addressed architecture,
+originally designed to avoid traps induced
+by addressing a word on an odd byte boundary.
All short integers are aligned on a short word boundary.
.PP
-The numbers section is similar to the flags section.
+The \fInumbers\fP section is similar to the \fIBoolean flags\fP section.
Each capability takes up two bytes,
and is stored as a little-endian short integer.
-If the value represented is \-1, the capability is taken to be missing.
.PP
-The strings section is also similar.
-Each capability is stored as a short integer, in the format above.
-A value of \-1 means the capability is missing.
-Otherwise, the value is taken as an offset from the beginning
-of the string table.
-Special characters in ^X or \ec notation are stored in their
+The \fIstrings\fP section is also similar.
+Each capability is stored as a short integer.
+The capability value is an index into the \fIstring table\fP.
+.PP
+The \fIstring table\fP is the last section.
+It contains all of the values of string capabilities referenced in
+the \fIstrings\fP section.
+Each string is null-terminated.
+Special characters in \*^X or \ec notation are stored in their
interpreted form, not the printing representation.
Padding information $<nn> and parameter information %x are
stored intact in uninterpreted form.
-.PP
-The final section is the string table.
-It contains all the values of string capabilities referenced in
-the string section.
-Each string is null terminated.
-.SS EXTENDED STORAGE FORMAT
+.SS "Extended Storage Format"
The previous section describes the conventional terminfo binary format.
With some minor variations of the offsets (see PORTABILITY),
-the same binary format is used in all modern UNIX systems.
-Each system uses a predefined set of boolean, number or string capabilities.
+the same binary format is used in all modern Unix systems.
+Each system uses a predefined set of Boolean, number or string capabilities.
.PP
-The ncurses libraries and applications support extended terminfo binary format,
-allowing users to define capabilities which are loaded at runtime. This
+The \fI\%ncurses\fP libraries and applications support
+extended terminfo binary format,
+allowing users to define capabilities which are loaded at runtime.
+This
extension is made possible by using the fact that the other implementations
stop reading the terminfo data when they have reached the end of the size given
in the header.
-ncurses checks the size, and if it exceeds that due to the predefined data,
+\fI\%ncurses\fP checks the size,
+and if it exceeds that due to the predefined data,
continues to parse according to its own scheme.
.PP
First, it reads the extended header (5 short integers):
.RS 5
.TP 5
(1)
-count of extended boolean capabilities
+count of extended Boolean capabilities
.TP 5
(2)
count of extended numeric capabilities
@@ -181,65 +245,174 @@
count of extended string capabilities
.TP 5
(4)
-size of the extended string table in bytes.
+count of the items in extended string table
.TP 5
(5)
-last offset of the extended string table in bytes.
+size of the extended string table in bytes
.RE
.PP
-Using the counts and sizes, ncurses allocates arrays and reads data
-for the extended capabilities in the same order as the header information.
+The count- and size-values for the extended string table
+include the extended capability \fInames\fP as well as
+extended capability \fIvalues\fP.
+.PP
+Using the counts and sizes,
+\fI\%ncurses\fP allocates arrays and reads data for the extended
+capabilities in the same order as the header information.
.PP
The extended string table contains values for string capabilities.
After the end of these values, it contains the names for each of
-the extended capabilities in order, e.g., booleans, then numbers and
+the extended capabilities in order, e.g., Booleans, then numbers and
finally strings.
+.PP
+By storing terminal descriptions in this way,
+\fI\%ncurses\fP is able to provide a database useful with legacy
+applications,
+as well as providing data for applications which need more than the
+predefined capabilities.
+See \fBuser_caps\fP(5) for an overview
+of the way \fI\%ncurses\fP uses this extended information.
+.PP
+Applications which manipulate terminal data can use the definitions
+described in \fBterm_variables\fP(3X) which associate the long capability
+names with members of a \fBTERMTYPE\fP structure.
.
+.SS "Extended Number Format"
+On occasion, 16-bit signed integers are not large enough.
+With \fI\%ncurses\fP 6.1,
+a new format was introduced by making a few changes
+to the legacy format:
+.bP
+a different magic number (octal 01036)
+.bP
+changing the type for the \fInumber\fP array from signed 16-bit integers
+to signed 32-bit integers.
+.PP
+To maintain compatibility, the library presents the same data structures
+to direct users of the \fBTERMTYPE\fP structure as in previous formats.
+However, that cannot provide callers with the extended numbers.
+The library uses a similar but hidden data structure \fBTERMTYPE2\fP
+to provide data for the terminfo functions.
+.SH FILES
+.TP
+.I \*d
+compiled terminal description database
.SH PORTABILITY
+.SS setupterm
Note that it is possible for
-.I setupterm
+.B setupterm
to expect a different set of capabilities
than are actually present in the file.
Either the database may have been updated since
-.I setupterm
-has been recompiled
+.B setupterm
+was recompiled
(resulting in extra unrecognized entries in the file)
or the program may have been recompiled more recently
than the database was updated
(resulting in missing entries).
The routine
-.I setupterm
+.B setupterm
must be prepared for both possibilities \-
this is why the numbers and sizes are included.
Also, new capabilities must always be added at the end of the lists
-of boolean, number, and string capabilities.
+of Boolean, number, and string capabilities.
+.SS "Binary Format"
+X/Open Curses does not specify a format for the terminfo database.
+System V curses used a directory-tree of binary files,
+one per terminal description.
.PP
Despite the consistent use of little-endian for numbers and the otherwise
self-describing format, it is not wise to count on portability of binary
-terminfo entries between commercial UNIX versions. The problem is that there
+terminfo entries between commercial Unix versions.
+The problem is that there
are at least three versions of terminfo (under HP\-UX, AIX, and OSF/1) which
diverged from System V terminfo after SVr1, and have added extension
capabilities to the string table that (in the binary format) collide with
-System V and XSI Curses extensions. See \fBterminfo\fR(\*n) for detailed
+System V and X/Open Curses extensions.
+See \fBterminfo\fP(5) for detailed
discussion of terminfo source compatibility issues.
-.SH EXAMPLE
-As an example, here is a hex dump of the description for the Lear-Siegler
+.PP
+This implementation is by default compatible with the binary
+terminfo format used by Solaris curses,
+except in a few less-used details
+where it was found that the latter did not match X/Open Curses.
+The format used by the other Unix versions
+can be matched by building \fI\%ncurses\fP
+with different configuration options.
+.SS "Magic Codes"
+The magic number in a binary terminfo file is the first 16-bits (two bytes).
+Besides making it more reliable for the library to check that a file
+is terminfo,
+utilities such as \fBfile\fP(1) also use that to tell what the file-format is.
+System V defined more than one magic number,
+with 0433, 0435 as screen-dumps (see \fBscr_dump\fP(5)).
+This implementation uses 01036 as a continuation of that sequence,
+but with a different high-order byte to avoid confusion.
+.SS "The \fITERMTYPE\fP Structure"
+Direct access to the \fBTERMTYPE\fP structure is provided for legacy
+applications.
+Portable applications should use the \fBtigetflag\fP and related functions
+described in \fBcurs_terminfo\fP(3X) for reading terminal capabilities.
+.SS "Mixed-case Terminal Names"
+A small number of terminal descriptions use uppercase characters in
+their names.
+If the underlying filesystem ignores the difference between
+uppercase and lowercase,
+\fI\%ncurses\fP represents the \*(``first character\*(''
+of the terminal name used as
+the intermediate level of a directory tree in (two-character) hexadecimal form.
+.SS Limits
+\fI\%ncurses\fP stores compiled terminal descriptions
+in three related formats,
+described in the sections
+.bP
+\fBLEGACY STORAGE FORMAT\fP, and
+.bP
+\fBEXTENDED STORAGE FORMAT\fP, and
+.bP
+\fBEXTENDED NUMBER FORMAT\fP.
+.PP
+The legacy storage format and the extended number format differ by
+the types of numeric capability which they can store
+(i.e., 16-bit versus 32-bit integers).
+The extended storage format introduced by \fI\%ncurses\fP 5.0 adds data
+to either of these formats.
+.PP
+Some limitations apply:
+.bP
+total compiled entries cannot exceed 4096 bytes in the legacy format.
+.bP
+total compiled entries cannot exceed 32768 bytes in the extended format.
+.bP
+the name field cannot exceed 128 bytes.
+.PP
+Compiled entries are limited to 32768 bytes because offsets into the
+\fIstrings table\fP use two-byte integers.
+The legacy format could have supported 32768-byte entries,
+but was limited to a virtual memory page's 4096 bytes.
+.SH EXAMPLES
+As an example, here is a description for the Lear-Siegler
ADM\-3, a popular though rather stupid early terminal:
-.nf
-.sp
+.PP
+.EX
adm3a|lsi adm3a,
am,
cols#80, lines#24,
- bel=^G, clear=\032$<1>, cr=^M, cub1=^H, cud1=^J,
- cuf1=^L, cup=\\E=%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K,
- home=^^, ind=^J,
-.sp
-.ft CW
-\s-20000 1a 01 10 00 02 00 03 00 82 00 31 00 61 64 6d 33 ........ ..1.adm3
+ bel=\*^G, clear=\e032$<1>, cr=\*^M, cub1=\*^H, cud1=\*^J,
+ cuf1=\*^L, cup=\eE=%p1%{32}%+%c%p2%{32}%+%c, cuu1=\*^K,
+ home=\*^\*^, ind=\*^J,
+.EE
+.PP
+and a hexadecimal dump of the compiled terminal description:
+.PP
+.if t .in +4n
+.ft \*(CW
+.TS
+Lp-1.
+0000 1a 01 10 00 02 00 03 00 82 00 31 00 61 64 6d 33 ........ ..1.adm3
0010 61 7c 6c 73 69 20 61 64 6d 33 61 00 00 01 50 00 a|lsi ad m3a...P.
0020 ff ff 18 00 ff ff 00 00 02 00 ff ff ff ff 04 00 ........ ........
-0030 ff ff ff ff ff ff ff ff 0a 00 25 00 27 00 ff ff ........ ..%.'...
-0040 29 00 ff ff ff ff 2b 00 ff ff 2d 00 ff ff ff ff ).....+. ..-.....
+0030 ff ff ff ff ff ff ff ff 0a 00 25 00 27 00 ff ff ........ ..%.\*'...
+0040 29 00 ff ff ff ff 2b 00 ff ff 2d 00 ff ff ff ff ).....+. ..\-.....
0050 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........
0060 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........
0070 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........
@@ -256,22 +429,24 @@
0120 ff ff ff ff ff ff 2f 00 07 00 0d 00 1a 24 3c 31 ....../. .....$<1
0130 3e 00 1b 3d 25 70 31 25 7b 33 32 7d 25 2b 25 63 >..=%p1% {32}%+%c
0140 25 70 32 25 7b 33 32 7d 25 2b 25 63 00 0a 00 1e %p2%{32} %+%c....
-0150 00 08 00 0c 00 0b 00 0a 00 ........ .\s+2
-.ft R
-.fi
-.sp
-.SH LIMITS
-Some limitations: total compiled entries cannot exceed 4096 bytes.
-The name field cannot exceed 128 bytes.
-.SH FILES
-\*d/*/* compiled terminal capability data base
-.SH SEE ALSO
-\fBcurses\fR(3X), \fBterminfo\fR(\*n).
+0150 00 08 00 0c 00 0b 00 0a 00 ........ .
+.TE
+.ft
+.in
.SH AUTHORS
Thomas E. Dickey
.br
-extended terminfo format for ncurses 5.0
+extended terminfo format for \fI\%ncurses\fP 5.0
.br
-hashed database support for ncurses 5.6
+hashed database support for \fI\%ncurses\fP 5.6
+.br
+extended number support for \fI\%ncurses\fP 6.1
.sp
Eric S. Raymond
+.br
+documented legacy terminfo format, e.g., from \fIpcurses\fP.
+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%curs_terminfo\fP(3X),
+\fB\%terminfo\fP(5),
+\fB\%user_caps\fP(5)
diff --git a/man/term.7 b/man/term.7
index cee8a01..84d100d 100644
--- a/man/term.7
+++ b/man/term.7
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2011 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2011,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 *
@@ -26,112 +27,147 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: term.7,v 1.23 2011/12/17 23:32:17 tom Exp $
-.TH term 7
-.ds n 5
+.\" $Id: term.7,v 1.48 2024/03/16 15:35:01 tom Exp $
+.TH term 7 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" Miscellaneous
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.ds d @TERMINFO@
.SH NAME
-term \- conventions for naming terminal types
+term \-
+conventions for naming terminal types
+.\"SH SYNOPSIS
.SH DESCRIPTION
-.PP
-The environment variable \fBTERM\fR should normally contain the type name of
-the terminal, console or display-device type you are using. This information
+The environment variable \fITERM\fP should normally contain the type
+name of the terminal,
+console or display-device type you are using.
+This information
is critical for all screen-oriented programs, including your editor and mailer.
.PP
-A default \fBTERM\fR value will be set on a per-line basis by either
-\fB/etc/inittab\fR (e.g., System\-V-like UNIXes)
-or \fB/etc/ttys\fR (BSD UNIXes).
+A default \fITERM\fP value will be set on a per-line basis by either
+\fB/etc/inittab\fP (e.g., System\-V-like Unices)
+or \fB/etc/ttys\fP (BSD Unices).
This will nearly always suffice for workstation and microcomputer consoles.
.PP
-If you use a dialup line, the type of device attached to it may vary. Older
-UNIX systems pre-set a very dumb terminal type like `dumb' or `dialup' on
-dialup lines. Newer ones may pre-set `vt100', reflecting the prevalence of DEC
+If you use a dialup line, the type of device attached to it may vary.
+Older Unix systems pre-set a very dumb terminal type
+like \*(``dumb\*('' or \*(``dialup\*('' on dialup lines.
+Newer ones may pre-set \*(``vt100\*('', reflecting the prevalence of DEC
VT100-compatible terminals and personal-computer emulators.
.PP
-Modern telnets pass your \fBTERM\fR environment variable from the local side to
-the remote one. There can be problems if the remote terminfo or termcap entry
+Modern telnets pass your \fITERM\fP environment variable from the local
+side to the remote one.
+There can be problems if the remote terminfo or termcap entry
for your type is not compatible with yours, but this situation is rare and
-can almost always be avoided by explicitly exporting `vt100' (assuming you
-are in fact using a VT100-superset console, terminal, or terminal emulator.)
+can almost always be avoided by explicitly exporting \*(``vt100\*(''
+(assuming you are in fact using a VT100-superset console,
+terminal, or terminal emulator).
.PP
-In any case, you are free to override the system \fBTERM\fR setting to your
-taste in your shell profile. The \fB@TSET@\fP(1) utility may be of assistance;
+In any case, you are free to override the system \fITERM\fP setting to
+your taste in your shell profile.
+The \fB@TSET@\fP(1) utility may be of assistance;
you can give it a set of rules for deducing or requesting a terminal type based
on the tty device and baud rate.
.PP
-Setting your own \fBTERM\fR value may also be useful if you have created a
-custom entry incorporating options (such as visual bell or reverse-video)
+Setting your own \fITERM\fP value may also be useful if you have created
+a custom entry incorporating options
+(such as visual bell or reverse-video)
which you wish to override the system default type for your line.
.PP
Terminal type descriptions are stored as files of capability data underneath
-\*d. To browse a list of all terminal names recognized by the system, do
+\*d.
+To browse a list of all terminal names recognized by the system, do
.sp
- @TOE@ | more
+ @TOE@ | more
.sp
-from your shell. These capability files are in a binary format optimized for
-retrieval speed (unlike the old text-based \fBtermcap\fR format they replace);
-to examine an entry, you must use the \fB@INFOCMP@\fR(1M) command.
+from your shell.
+These capability files are in a binary format optimized for
+retrieval speed (unlike the old text-based \fBtermcap\fP format they replace);
+to examine an entry, you must use the \fB@INFOCMP@\fP(1M) command.
Invoke it as follows:
.sp
- @INFOCMP@ \fIentry_name\fR
+ @INFOCMP@ \fIentry_name\fP
.sp
-where \fIentry_name\fR is the name of the type you wish to examine (and the
+where \fIentry_name\fP is the name of the type you wish to examine (and the
name of its capability file the subdirectory of \*d named for its first
-letter). This command dumps a capability file in the text format described by
-\fBterminfo\fR(\*n).
+letter).
+This command dumps a capability file in the text format described by
+\fBterminfo\fP(5).
.PP
-The first line of a \fBterminfo\fR(\*n) description gives the names by which
-terminfo knows a terminal, separated by `|' (pipe-bar) characters with the last
-name field terminated by a comma. The first name field is the type's
-\fIprimary name\fR, and is the one to use when setting \fBTERM\fR. The last
-name field (if distinct from the first) is actually a description of the
-terminal type (it may contain blanks; the others must be single words). Name
+The first line of a \fBterminfo\fP(5) description gives the names by which
+terminfo knows a terminal,
+separated by \*(``|\*('' (pipe-bar) characters with the last
+name field terminated by a comma.
+The first name field is the type's
+\fIprimary name\fP,
+and is the one to use when setting \fITERM\fP.
+The last name field
+(if distinct from the first)
+is actually a description of the
+terminal type (it may contain blanks; the others must be single words).
+Name
fields between the first and last (if present) are aliases for the terminal,
usually historical names retained for compatibility.
.PP
There are some conventions for how to choose terminal primary names that help
-keep them informative and unique. Here is a step-by-step guide to naming
+keep them informative and unique.
+Here is a step-by-step guide to naming
terminals that also explains how to parse them:
.PP
-First, choose a root name. The root will consist of a lower-case letter
-followed by up to seven lower-case letters or digits. You need to avoid using
+First, choose a root name.
+The root will consist of a lower-case letter
+followed by up to seven lower-case letters or digits.
+You need to avoid using
punctuation characters in root names, because they are used and interpreted as
filenames and shell meta-characters (such as !, $, *, ?, etc.) embedded in them
-may cause odd and unhelpful behavior. The slash (/), or any other character
+may cause odd and unhelpful behavior.
+The slash (/), or any other character
that may be interpreted by anyone's file system (\e, $, [, ]), is especially
dangerous (terminfo is platform-independent, and choosing names with special
-characters could someday make life difficult for users of a future port). The
+characters could someday make life difficult for users of a future port).
+The
dot (.) character is relatively safe as long as there is at most one per root
name; some historical terminfo names use it.
.PP
The root name for a terminal or workstation console type should almost always
-begin with a vendor prefix (such as \fBhp\fR for Hewlett-Packard, \fBwy\fR for
-Wyse, or \fBatt\fR for AT&T terminals), or a common name of the terminal line
-(\fBvt\fR for the VT series of terminals from DEC, or \fBsun\fR for Sun
-Microsystems workstation consoles, or \fBregent\fR for the ADDS Regent series.
+begin with a vendor prefix (such as \fBhp\fP for Hewlett-Packard, \fBwy\fP for
+Wyse, or \fBatt\fP for AT&T terminals), or a common name of the terminal line
+(\fBvt\fP for the VT series of terminals from DEC, or \fBsun\fP for Sun
+Microsystems workstation consoles, or \fBregent\fP for the ADDS Regent series.
You can list the terminfo tree to see what prefixes are already in common use.
The root name prefix should be followed when appropriate by a model number;
-thus \fBvt100\fR, \fBhp2621\fR, \fBwy50\fR.
+thus \fBvt100\fP, \fBhp2621\fP, \fBwy50\fP.
.PP
The root name for a PC-Unix console type should be the OS name,
-i.e., \fBlinux\fR, \fBbsdos\fR, \fBfreebsd\fR, \fBnetbsd\fR. It should
-\fInot\fR be \fBconsole\fR or any other generic that might cause confusion in a
+i.e., \fBlinux\fP, \fBbsdos\fP, \fBfreebsd\fP, \fBnetbsd\fP. It should
+\fInot\fP be \fBconsole\fP or any other generic that might cause confusion in a
multi-platform environment! If a model number follows, it should indicate
either the OS release level or the console driver release level.
.PP
The root name for a terminal emulator (assuming it does not fit one of the
standard ANSI or vt100 types) should be the program name or a readily
-recognizable abbreviation of it (i.e., \fBversaterm\fR, \fBctrm\fR).
+recognizable abbreviation of it (i.e., \fBversaterm\fP, \fBctrm\fP).
.PP
Following the root name, you may add any reasonable number of hyphen-separated
feature suffixes.
.TP 5
2p
-Has two pages of memory. Likewise 4p, 8p, etc.
+Has two pages of memory.
+Likewise 4p, 8p, etc.
.TP 5
mc
-Magic-cookie. Some terminals (notably older Wyses) can only support one
-attribute without magic-cookie lossage. Their base entry is usually paired
+Magic-cookie.
+Some terminals (notably older Wyses) can only support one
+attribute without magic-cookie lossage.
+Their base entry is usually paired
with another that has this suffix and uses magic cookies to support multiple
attributes.
.TP 5
@@ -167,32 +203,36 @@
Use visible bell (flash) rather than beep.
.TP 5
\-w
-Wide; terminal is in 132 column mode.
+Wide; terminal is in 132-column mode.
.PP
Conventionally, if your terminal type is a variant intended to specify a
-line height, that suffix should go first. So, for a hypothetical FuBarCo
+line height, that suffix should go first.
+So, for a hypothetical FuBarCo
model 2317 terminal in 30-line mode with reverse video, best form would be
-\fBfubar\-30\-rv\fR (rather than, say, `fubar\-rv\-30').
+\fBfubar\-30\-rv\fP (rather than, say, \*(``fubar\-rv\-30\*('').
.PP
Terminal types that are written not as standalone entries, but rather as
components to be plugged into other entries via \fBuse\fP capabilities,
are distinguished by using embedded plus signs rather than dashes.
.PP
Commands which use a terminal type to control display often accept a \-T
-option that accepts a terminal name argument. Such programs should fall back
-on the \fBTERM\fR environment variable when no \-T option is specified.
-.SH PORTABILITY
-For maximum compatibility with older System V UNIXes, names and aliases
-should be unique within the first 14 characters.
+option that accepts a terminal name argument.
+Such programs should fall back
+on the \fITERM\fP environment variable when no \-T option is specified.
.SH FILES
-.TP 5
-\*d/?/*
-compiled terminal capability data base
-.TP 5
-/etc/inittab
-tty line initialization (AT&T-like UNIXes)
-.TP 5
-/etc/ttys
-tty line initialization (BSD-like UNIXes)
+.TP
+.I \*d
+compiled terminal description database
+.TP
+.I /etc/inittab
+tty line initialization (AT&T-like Unices)
+.TP
+.I /etc/ttys
+tty line initialization (BSD-like Unices)
+.SH PORTABILITY
+For maximum compatibility with older System V Unices, names and aliases
+should be unique within the first 14 characters.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBterminfo\fR(\*n), \fBterm\fR(\*n).
+\fB\%curses\fP(3X),
+\fB\%term\fP(5),
+\fB\%terminfo\fP(5)
diff --git a/man/term_variables.3x b/man/term_variables.3x
index ea24737..6aee63f 100644
--- a/man/term_variables.3x
+++ b/man/term_variables.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 2011-2013,2015 Free Software Foundation, Inc. *
+.\" Copyright 2019-2023,2024 Thomas E. Dickey *
+.\" Copyright 2010-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 *
@@ -26,58 +27,58 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: term_variables.3x,v 1.6 2015/04/22 00:34:49 tom Exp $
-.TH term_variables 3X ""
-.ds n 5
-.na
-.hy 0
+.\" $Id: term_variables.3x,v 1.36 2024/03/16 15:35:01 tom Exp $
+.TH term_variables 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.SH NAME
-\fBSP\fP,
-\fBacs_map\fP,
-\fBboolcodes\fP,
-\fBboolfnames\fP,
-\fBboolnames\fP,
-\fBcur_term\fP,
-\fBnumcodes\fP,
-\fBnumfnames\fP,
-\fBnumnames\fP,
-\fBstrcodes\fP,
-\fBstrfnames\fP,
-\fBstrnames\fP,
-\fBttytype\fP
-\- \fBcurses\fR terminfo global variables
-.ad
-.hy
+\fB\%SP\fP,
+\fB\%acs_map\fP,
+\fB\%boolcodes\fP,
+\fB\%boolfnames\fP,
+\fB\%boolnames\fP,
+\fB\%cur_term\fP,
+\fB\%numcodes\fP,
+\fB\%numfnames\fP,
+\fB\%numnames\fP,
+\fB\%strcodes\fP,
+\fB\%strfnames\fP,
+\fB\%strnames\fP,
+\fB\%ttytype\fP \-
+\fIterminfo\fR global variables
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fR
-.br
-\fB#include <term.h>\fR
+\fB#include <curses.h>
+\fB#include <term.h>
.PP
-\fBchtype acs_map[];\fR
-.sp
-\fBTERMINAL * cur_term;\fR
-.sp
-\fBchar ttytype[];\fR
-.sp
-\fBNCURSES_CONST char * const * boolcodes;\fR
-.br
-\fBNCURSES_CONST char * const * boolfnames;\fR
-.br
-\fBNCURSES_CONST char * const * boolnames;\fR
-.sp
-\fBNCURSES_CONST char * const * numcodes;\fR
-.br
-\fBNCURSES_CONST char * const * numfnames;\fR
-.br
-\fBNCURSES_CONST char * const * numnames;\fR
-.sp
-\fBNCURSES_CONST char * const * strcodes;\fR
-.br
-\fBNCURSES_CONST char * const * strfnames;\fR
-.br
-\fBNCURSES_CONST char * const * strnames;\fR
-.br
+\fBchtype acs_map[];
+.PP
+\fBSCREEN * SP;
+.PP
+\fBTERMINAL * cur_term;
+.PP
+\fBchar ttytype[];
+.PP
+\fBNCURSES_CONST char * const boolcodes[];
+\fBNCURSES_CONST char * const boolfnames[];
+\fBNCURSES_CONST char * const boolnames[];
+.PP
+\fBNCURSES_CONST char * const numcodes[];
+\fBNCURSES_CONST char * const numfnames[];
+\fBNCURSES_CONST char * const numnames[];
+.PP
+\fBNCURSES_CONST char * const strcodes[];
+\fBNCURSES_CONST char * const strfnames[];
+\fBNCURSES_CONST char * const strnames[];
.fi
.SH DESCRIPTION
This page summarizes variables provided by the \fBcurses\fP library's
@@ -85,21 +86,21 @@
A more complete description is given in the \fBcurs_terminfo\fP(3X) manual page.
.PP
Depending on the configuration, these may be actual variables,
-or macros (see \fBcurs_threads\fR(3X))
+or macros (see \fBcurs_threads\fP(3X))
which provide read-only access to \fIcurses\fP's state.
In either case, applications should treat them as read-only to avoid
confusing the library.
-.SS Alternate Character Set Mapping
+.SS "Alternate Character Set Mapping"
After initializing the curses or terminfo interfaces,
the \fBacs_map\fP array holds information used to translate cells
with the \fBA_ALTCHARSET\fP video attribute into line-drawing characters.
.PP
The encoding of the information in this array has changed periodically.
-Application developers need only know that it is used for the "ACS_"
+Application developers need only know that it is used for the \*(``ACS_\*(''
constants in <curses.h>.
.PP
The comparable data for the wide-character library is a private variable.
-.SS Current Terminal Data
+.SS "Current Terminal Data"
After initializing the curses or terminfo interfaces,
the \fBcur_term\fP contains data describing the current terminal.
This variable is also set as a side-effect of \fBset_term\fP(3X)
@@ -108,8 +109,8 @@
It is possible to save a value of \fBcur_term\fP for subsequent
use as a parameter to \fBset_term\fP, for switching between screens.
Alternatively, one can save the return value from \fBnewterm\fP
-or \fBsetupterm\fP to reuse in \fBset_term\fP.
-.SS Terminfo Names
+or \fBsetupterm\fP(3X) to reuse in \fBset_term\fP.
+.SS "\fIterminfo\fP Lookup Tables"
The \fB@TIC@\fP(1) and \fB@INFOCMP@\fP(1) programs use lookup tables for
the long and short names of terminfo capabilities,
as well as the corresponding names for termcap capabilities.
@@ -117,7 +118,7 @@
although the hash-tables used by
the terminfo and termcap functions are not available.
.PP
-The long terminfo capability names use a "l" (ell) in their names:
+The long terminfo capability names use a \*(``f\*('' (eff) in their names:
\fBboolfnames\fP,
\fBnumfnames\fP, and
\fBstrfnames\fP.
@@ -132,31 +133,32 @@
\fBnumcodes\fP, and
\fBstrcodes\fP.
.\"
-.SS Terminal Type
+.SS "Terminal Type"
+A terminal description begins with one or more terminal names
+separated by \*(``|\*('' (vertical bars).
On initialization of the curses or terminfo interfaces,
-\fBsetupterm\fP copies the terminal name to the array \fBttytype\fP.
+\fBsetupterm\fP(3X) copies the terminal names to the array \fBttytype\fP.
.\"
-.SS Terminfo Names
-.PP
+.SS "\fIterminfo\fP Names"
In addition to the variables, \fB<term.h>\fP also defines a symbol for each
terminfo capability \fIlong name\fP.
These are in terms of the symbol \fBCUR\fP,
which is defined
.PP
-.nf
-.ft CW
-#define CUR cur_term->type.
-.fi
-.ft R
+.EX
+#define CUR ((TERMTYPE *)(cur_term))\->
+.EE
.PP
These symbols provide a faster method of accessing terminfo capabilities
-than using \fBtigetstr\fR(3X), etc.
+than using \fBtigetstr\fP(3X), etc.
+.PP
+The actual definition of \fBCUR\fP depends upon the implementation,
+but each terminfo library provides these long names defined to point
+into the current terminal description loaded into memory.
.\"
.SH NOTES
The low-level terminfo interface is initialized using
-.hy 0
-\fBsetupterm\fR(3X).
-.hy
+\fB\%setupterm\fP(3X).
The upper-level curses interface uses the low-level terminfo interface,
internally.
.\"
@@ -173,9 +175,7 @@
as described in the \fBTerminfo Names\fP section.
Most, but not all, base the definition upon the \fBcur_term\fP variable.
.SH SEE ALSO
-.hy 0
-\fBcurses\fR(3X),
-\fBcurs_terminfo\fR(3X),
-\fBcurs_threads\fR(3X),
-\fBterminfo\fR(\*n).
-.hy
+\fB\%curses\fP(3X),
+\fB\%curs_terminfo\fP(3X),
+\fB\%curs_threads\fP(3X),
+\fB\%terminfo\fP(5)
diff --git a/man/terminfo.5 b/man/terminfo.5
deleted file mode 100644
index b4bd572..0000000
--- a/man/terminfo.5
+++ /dev/null
@@ -1,3467 +0,0 @@
-'\" t
-.\" DO NOT EDIT THIS FILE BY HAND!
-.\" It is generated from terminfo.head, Caps, and terminfo.tail.
-.\"
-.\" Note: this must be run through tbl before nroff.
-.\" The magic cookie on the first line triggers this under some man programs.
-.\"***************************************************************************
-.\" Copyright (c) 1998-2012,2013 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 *
-.\" "Software"), to deal in the Software without restriction, including *
-.\" without limitation the rights to use, copy, modify, merge, publish, *
-.\" distribute, distribute with modifications, sublicense, and/or sell *
-.\" copies of the Software, and to permit persons to whom the Software is *
-.\" furnished to do so, subject to the following conditions: *
-.\" *
-.\" The above copyright notice and this permission notice shall be included *
-.\" in all copies or substantial portions of the Software. *
-.\" *
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
-.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
-.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
-.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
-.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
-.\" *
-.\" Except as contained in this notice, the name(s) of the above copyright *
-.\" holders shall not be used in advertising or otherwise to promote the *
-.\" sale, use or other dealings in this Software without prior written *
-.\" authorization. *
-.\"***************************************************************************
-.\"
-.\" $Id: terminfo.head,v 1.21 2013/03/09 22:11:36 tom Exp $
-.TH terminfo 5 "" "" "File Formats"
-.ds n 5
-.ds d @TERMINFO@
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
-.de bP
-.IP \(bu 4
-..
-.SH NAME
-terminfo \- terminal capability data base
-.SH SYNOPSIS
-\*d/*/*
-.SH DESCRIPTION
-.I Terminfo
-is a data base describing terminals, used by screen-oriented programs such as
-\fBnvi\fR(1),
-\fBrogue\fR(1)
-and libraries such as
-\fBcurses\fR(3X).
-.I Terminfo
-describes terminals by giving a set of capabilities which they
-have, by specifying how to perform screen operations, and by
-specifying padding requirements and initialization sequences.
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
-.PP
-Entries in
-.I terminfo
-consist of a sequence of `,' separated fields (embedded commas may be
-escaped with a backslash or notated as \\054).
-White space after the `,' separator is ignored.
-The first entry for each terminal gives the names which are known for the
-terminal, separated by `|' characters.
-The first name given is the most common abbreviation for the terminal,
-the last name given should be a long name fully identifying the terminal,
-and all others are understood as synonyms for the terminal name.
-All names but the last should be in lower case and contain no blanks;
-the last name may well contain upper case and blanks for readability.
-.PP
-Lines beginning with a `#' in the first column are treated as comments.
-While comment lines are legal at any point, the output of \fB@CAPTOINFO@\fP
-and \fB@INFOTOCAP@\fP (aliases for \fB@TIC@\fP)
-will move comments so they occur only between entries.
-.PP
-Newlines and leading tabs may be used for formatting entries for readability.
-These are removed from parsed entries.
-The \fB@INFOCMP@\ \-f\fP option relies on this to format if-then-else expressions:
-the result can be read by \fB@TIC@\fP.
-.PP
-Terminal names (except for the last, verbose entry) should
-be chosen using the following conventions.
-The particular piece of hardware making up the terminal should
-have a root name, thus \*(``hp2621\*(''.
-This name should not contain hyphens.
-Modes that the hardware can be in, or user preferences, should
-be indicated by appending a hyphen and a mode suffix.
-Thus, a vt100 in 132 column mode would be vt100\-w.
-The following suffixes should be used where possible:
-.PP
-.TS
-center ;
-l c l
-l l l.
-\fBSuffix Meaning Example\fP
-\-\fInn\fP Number of lines on the screen aaa\-60
-\-\fIn\fPp Number of pages of memory c100\-4p
-\-am With automargins (usually the default) vt100\-am
-\-m Mono mode; suppress color ansi\-m
-\-mc Magic cookie; spaces when highlighting wy30\-mc
-\-na No arrow keys (leave them in local) c100\-na
-\-nam Without automatic margins vt100\-nam
-\-nl No status line att4415\-nl
-\-ns No status line hp2626\-ns
-\-rv Reverse video c100\-rv
-\-s Enable status line vt100\-s
-\-vb Use visible bell instead of beep wy370\-vb
-\-w Wide mode (> 80 columns, usually 132) vt100\-w
-.TE
-.PP
-For more on terminal naming conventions, see the \fBterm(7)\fR manual page.
-.SS Predefined Capabilities
-.\" Head of terminfo man page ends here
-.ps -1
-The following is a complete table of the capabilities included in a
-terminfo description block and available to terminfo-using code. In each
-line of the table,
-
-The \fBvariable\fR is the name by which the programmer (at the terminfo level)
-accesses the capability.
-
-The \fBcapname\fR is the short name used in the text of the database,
-and is used by a person updating the database.
-Whenever possible, capnames are chosen to be the same as or similar to
-the ANSI X3.64-1979 standard (now superseded by ECMA-48, which uses
-identical or very similar names). Semantics are also intended to match
-those of the specification.
-
-The termcap code is the old
-.B termcap
-capability name (some capabilities are new, and have names which termcap
-did not originate).
-.P
-Capability names have no hard length limit, but an informal limit of 5
-characters has been adopted to keep them short and to allow the tabs in
-the source file
-.B Caps
-to line up nicely.
-
-Finally, the description field attempts to convey the semantics of the
-capability. You may find some codes in the description field:
-.TP
-(P)
-indicates that padding may be specified
-.TP
-#[1-9]
-in the description field indicates that the string is passed through tparm with
-parms as given (#\fIi\fP).
-.TP
-(P*)
-indicates that padding may vary in proportion to the number of
-lines affected
-.TP
-(#\d\fIi\fP\u)
-indicates the \fIi\fP\uth\d parameter.
-
-.PP
-These are the boolean capabilities:
-
-.na
-.TS H
-center expand;
-c l l c
-c l l c
-lw25 lw6 lw2 lw20.
-\fBVariable Cap- TCap Description\fR
-\fBBooleans name Code\fR
-auto_left_margin bw bw T{
-cub1 wraps from column 0 to last column
-T}
-auto_right_margin am am T{
-terminal has automatic margins
-T}
-back_color_erase bce ut T{
-screen erased with background color
-T}
-can_change ccc cc T{
-terminal can re-define existing colors
-T}
-ceol_standout_glitch xhp xs T{
-standout not erased by overwriting (hp)
-T}
-col_addr_glitch xhpa YA T{
-only positive motion for hpa/mhpa caps
-T}
-cpi_changes_res cpix YF T{
-changing character pitch changes resolution
-T}
-cr_cancels_micro_mode crxm YB T{
-using cr turns off micro mode
-T}
-dest_tabs_magic_smso xt xt T{
-tabs destructive, magic so char (t1061)
-T}
-eat_newline_glitch xenl xn T{
-newline ignored after 80 cols (concept)
-T}
-erase_overstrike eo eo T{
-can erase overstrikes with a blank
-T}
-generic_type gn gn T{
-generic line type
-T}
-hard_copy hc hc T{
-hardcopy terminal
-T}
-hard_cursor chts HC T{
-cursor is hard to see
-T}
-has_meta_key km km T{
-Has a meta key (i.e., sets 8th-bit)
-T}
-has_print_wheel daisy YC T{
-printer needs operator to change character set
-T}
-has_status_line hs hs T{
-has extra status line
-T}
-hue_lightness_saturation hls hl T{
-terminal uses only HLS color notation (Tektronix)
-T}
-insert_null_glitch in in T{
-insert mode distinguishes nulls
-T}
-lpi_changes_res lpix YG T{
-changing line pitch changes resolution
-T}
-memory_above da da T{
-display may be retained above the screen
-T}
-memory_below db db T{
-display may be retained below the screen
-T}
-move_insert_mode mir mi T{
-safe to move while in insert mode
-T}
-move_standout_mode msgr ms T{
-safe to move while in standout mode
-T}
-needs_xon_xoff nxon nx T{
-padding will not work, xon/xoff required
-T}
-no_esc_ctlc xsb xb T{
-beehive (f1=escape, f2=ctrl C)
-T}
-no_pad_char npc NP T{
-pad character does not exist
-T}
-non_dest_scroll_region ndscr ND T{
-scrolling region is non-destructive
-T}
-non_rev_rmcup nrrmc NR T{
-smcup does not reverse rmcup
-T}
-over_strike os os T{
-terminal can overstrike
-T}
-prtr_silent mc5i 5i T{
-printer will not echo on screen
-T}
-row_addr_glitch xvpa YD T{
-only positive motion for vpa/mvpa caps
-T}
-semi_auto_right_margin sam YE T{
-printing in last column causes cr
-T}
-status_line_esc_ok eslok es T{
-escape can be used on the status line
-T}
-tilde_glitch hz hz T{
-cannot print ~'s (Hazeltine)
-T}
-transparent_underline ul ul T{
-underline character overstrikes
-T}
-xon_xoff xon xo T{
-terminal uses xon/xoff handshaking
-T}
-.TE
-.ad
-
-These are the numeric capabilities:
-
-.na
-.TS H
-center expand;
-c l l c
-c l l c
-lw25 lw6 lw2 lw20.
-\fBVariable Cap- TCap Description\fR
-\fBNumeric name Code\fR
-columns cols co T{
-number of columns in a line
-T}
-init_tabs it it T{
-tabs initially every # spaces
-T}
-label_height lh lh T{
-rows in each label
-T}
-label_width lw lw T{
-columns in each label
-T}
-lines lines li T{
-number of lines on screen or page
-T}
-lines_of_memory lm lm T{
-lines of memory if > line. 0 means varies
-T}
-magic_cookie_glitch xmc sg T{
-number of blank characters left by smso or rmso
-T}
-max_attributes ma ma T{
-maximum combined attributes terminal can handle
-T}
-max_colors colors Co T{
-maximum number of colors on screen
-T}
-max_pairs pairs pa T{
-maximum number of color-pairs on the screen
-T}
-maximum_windows wnum MW T{
-maximum number of definable windows
-T}
-no_color_video ncv NC T{
-video attributes that cannot be used with colors
-T}
-num_labels nlab Nl T{
-number of labels on screen
-T}
-padding_baud_rate pb pb T{
-lowest baud rate where padding needed
-T}
-virtual_terminal vt vt T{
-virtual terminal number (CB/unix)
-T}
-width_status_line wsl ws T{
-number of columns in status line
-T}
-.TE
-.ad
-
-The following numeric capabilities are present in the SVr4.0 term structure,
-but are not yet documented in the man page. They came in with SVr4's
-printer support.
-
-.na
-.TS H
-center expand;
-c l l c
-c l l c
-lw25 lw6 lw2 lw20.
-\fBVariable Cap- TCap Description\fR
-\fBNumeric name Code\fR
-bit_image_entwining bitwin Yo T{
-number of passes for each bit-image row
-T}
-bit_image_type bitype Yp T{
-type of bit-image device
-T}
-buffer_capacity bufsz Ya T{
-numbers of bytes buffered before printing
-T}
-buttons btns BT T{
-number of buttons on mouse
-T}
-dot_horz_spacing spinh Yc T{
-spacing of dots horizontally in dots per inch
-T}
-dot_vert_spacing spinv Yb T{
-spacing of pins vertically in pins per inch
-T}
-max_micro_address maddr Yd T{
-maximum value in micro_..._address
-T}
-max_micro_jump mjump Ye T{
-maximum value in parm_..._micro
-T}
-micro_col_size mcs Yf T{
-character step size when in micro mode
-T}
-micro_line_size mls Yg T{
-line step size when in micro mode
-T}
-number_of_pins npins Yh T{
-numbers of pins in print-head
-T}
-output_res_char orc Yi T{
-horizontal resolution in units per line
-T}
-output_res_horz_inch orhi Yk T{
-horizontal resolution in units per inch
-T}
-output_res_line orl Yj T{
-vertical resolution in units per line
-T}
-output_res_vert_inch orvi Yl T{
-vertical resolution in units per inch
-T}
-print_rate cps Ym T{
-print rate in characters per second
-T}
-wide_char_size widcs Yn T{
-character step size when in double wide mode
-T}
-.TE
-.ad
-
-These are the string capabilities:
-
-.na
-.TS H
-center expand;
-c l l c
-c l l c
-lw25 lw6 lw2 lw20.
-\fBVariable Cap- TCap Description\fR
-\fBString name Code\fR
-acs_chars acsc ac T{
-graphics charset pairs, based on vt100
-T}
-back_tab cbt bt T{
-back tab (P)
-T}
-bell bel bl T{
-audible signal (bell) (P)
-T}
-carriage_return cr cr T{
-carriage return (P*) (P*)
-T}
-change_char_pitch cpi ZA T{
-Change number of characters per inch to #1
-T}
-change_line_pitch lpi ZB T{
-Change number of lines per inch to #1
-T}
-change_res_horz chr ZC T{
-Change horizontal resolution to #1
-T}
-change_res_vert cvr ZD T{
-Change vertical resolution to #1
-T}
-change_scroll_region csr cs T{
-change region to line #1 to line #2 (P)
-T}
-char_padding rmp rP T{
-like ip but when in insert mode
-T}
-clear_all_tabs tbc ct T{
-clear all tab stops (P)
-T}
-clear_margins mgc MC T{
-clear right and left soft margins
-T}
-clear_screen clear cl T{
-clear screen and home cursor (P*)
-T}
-clr_bol el1 cb T{
-Clear to beginning of line
-T}
-clr_eol el ce T{
-clear to end of line (P)
-T}
-clr_eos ed cd T{
-clear to end of screen (P*)
-T}
-column_address hpa ch T{
-horizontal position #1, absolute (P)
-T}
-command_character cmdch CC T{
-terminal settable cmd character in prototype !?
-T}
-create_window cwin CW T{
-define a window #1 from #2,#3 to #4,#5
-T}
-cursor_address cup cm T{
-move to row #1 columns #2
-T}
-cursor_down cud1 do T{
-down one line
-T}
-cursor_home home ho T{
-home cursor (if no cup)
-T}
-cursor_invisible civis vi T{
-make cursor invisible
-T}
-cursor_left cub1 le T{
-move left one space
-T}
-cursor_mem_address mrcup CM T{
-memory relative cursor addressing, move to row #1 columns #2
-T}
-cursor_normal cnorm ve T{
-make cursor appear normal (undo civis/cvvis)
-T}
-cursor_right cuf1 nd T{
-non-destructive space (move right one space)
-T}
-cursor_to_ll ll ll T{
-last line, first column (if no cup)
-T}
-cursor_up cuu1 up T{
-up one line
-T}
-cursor_visible cvvis vs T{
-make cursor very visible
-T}
-define_char defc ZE T{
-Define a character #1, #2 dots wide, descender #3
-T}
-delete_character dch1 dc T{
-delete character (P*)
-T}
-delete_line dl1 dl T{
-delete line (P*)
-T}
-dial_phone dial DI T{
-dial number #1
-T}
-dis_status_line dsl ds T{
-disable status line
-T}
-display_clock dclk DK T{
-display clock
-T}
-down_half_line hd hd T{
-half a line down
-T}
-ena_acs enacs eA T{
-enable alternate char set
-T}
-enter_alt_charset_mode smacs as T{
-start alternate character set (P)
-T}
-enter_am_mode smam SA T{
-turn on automatic margins
-T}
-enter_blink_mode blink mb T{
-turn on blinking
-T}
-enter_bold_mode bold md T{
-turn on bold (extra bright) mode
-T}
-enter_ca_mode smcup ti T{
-string to start programs using cup
-T}
-enter_delete_mode smdc dm T{
-enter delete mode
-T}
-enter_dim_mode dim mh T{
-turn on half-bright mode
-T}
-enter_doublewide_mode swidm ZF T{
-Enter double-wide mode
-T}
-enter_draft_quality sdrfq ZG T{
-Enter draft-quality mode
-T}
-enter_insert_mode smir im T{
-enter insert mode
-T}
-enter_italics_mode sitm ZH T{
-Enter italic mode
-T}
-enter_leftward_mode slm ZI T{
-Start leftward carriage motion
-T}
-enter_micro_mode smicm ZJ T{
-Start micro-motion mode
-T}
-enter_near_letter_quality snlq ZK T{
-Enter NLQ mode
-T}
-enter_normal_quality snrmq ZL T{
-Enter normal-quality mode
-T}
-enter_protected_mode prot mp T{
-turn on protected mode
-T}
-enter_reverse_mode rev mr T{
-turn on reverse video mode
-T}
-enter_secure_mode invis mk T{
-turn on blank mode (characters invisible)
-T}
-enter_shadow_mode sshm ZM T{
-Enter shadow-print mode
-T}
-enter_standout_mode smso so T{
-begin standout mode
-T}
-enter_subscript_mode ssubm ZN T{
-Enter subscript mode
-T}
-enter_superscript_mode ssupm ZO T{
-Enter superscript mode
-T}
-enter_underline_mode smul us T{
-begin underline mode
-T}
-enter_upward_mode sum ZP T{
-Start upward carriage motion
-T}
-enter_xon_mode smxon SX T{
-turn on xon/xoff handshaking
-T}
-erase_chars ech ec T{
-erase #1 characters (P)
-T}
-exit_alt_charset_mode rmacs ae T{
-end alternate character set (P)
-T}
-exit_am_mode rmam RA T{
-turn off automatic margins
-T}
-exit_attribute_mode sgr0 me T{
-turn off all attributes
-T}
-exit_ca_mode rmcup te T{
-strings to end programs using cup
-T}
-exit_delete_mode rmdc ed T{
-end delete mode
-T}
-exit_doublewide_mode rwidm ZQ T{
-End double-wide mode
-T}
-exit_insert_mode rmir ei T{
-exit insert mode
-T}
-exit_italics_mode ritm ZR T{
-End italic mode
-T}
-exit_leftward_mode rlm ZS T{
-End left-motion mode
-T}
-exit_micro_mode rmicm ZT T{
-End micro-motion mode
-T}
-exit_shadow_mode rshm ZU T{
-End shadow-print mode
-T}
-exit_standout_mode rmso se T{
-exit standout mode
-T}
-exit_subscript_mode rsubm ZV T{
-End subscript mode
-T}
-exit_superscript_mode rsupm ZW T{
-End superscript mode
-T}
-exit_underline_mode rmul ue T{
-exit underline mode
-T}
-exit_upward_mode rum ZX T{
-End reverse character motion
-T}
-exit_xon_mode rmxon RX T{
-turn off xon/xoff handshaking
-T}
-fixed_pause pause PA T{
-pause for 2-3 seconds
-T}
-flash_hook hook fh T{
-flash switch hook
-T}
-flash_screen flash vb T{
-visible bell (may not move cursor)
-T}
-form_feed ff ff T{
-hardcopy terminal page eject (P*)
-T}
-from_status_line fsl fs T{
-return from status line
-T}
-goto_window wingo WG T{
-go to window #1
-T}
-hangup hup HU T{
-hang-up phone
-T}
-init_1string is1 i1 T{
-initialization string
-T}
-init_2string is2 is T{
-initialization string
-T}
-init_3string is3 i3 T{
-initialization string
-T}
-init_file if if T{
-name of initialization file
-T}
-init_prog iprog iP T{
-path name of program for initialization
-T}
-initialize_color initc Ic T{
-initialize color #1 to (#2,#3,#4)
-T}
-initialize_pair initp Ip T{
-Initialize color pair #1 to fg=(#2,#3,#4), bg=(#5,#6,#7)
-T}
-insert_character ich1 ic T{
-insert character (P)
-T}
-insert_line il1 al T{
-insert line (P*)
-T}
-insert_padding ip ip T{
-insert padding after inserted character
-T}
-key_a1 ka1 K1 T{
-upper left of keypad
-T}
-key_a3 ka3 K3 T{
-upper right of keypad
-T}
-key_b2 kb2 K2 T{
-center of keypad
-T}
-key_backspace kbs kb T{
-backspace key
-T}
-key_beg kbeg @1 T{
-begin key
-T}
-key_btab kcbt kB T{
-back-tab key
-T}
-key_c1 kc1 K4 T{
-lower left of keypad
-T}
-key_c3 kc3 K5 T{
-lower right of keypad
-T}
-key_cancel kcan @2 T{
-cancel key
-T}
-key_catab ktbc ka T{
-clear-all-tabs key
-T}
-key_clear kclr kC T{
-clear-screen or erase key
-T}
-key_close kclo @3 T{
-close key
-T}
-key_command kcmd @4 T{
-command key
-T}
-key_copy kcpy @5 T{
-copy key
-T}
-key_create kcrt @6 T{
-create key
-T}
-key_ctab kctab kt T{
-clear-tab key
-T}
-key_dc kdch1 kD T{
-delete-character key
-T}
-key_dl kdl1 kL T{
-delete-line key
-T}
-key_down kcud1 kd T{
-down-arrow key
-T}
-key_eic krmir kM T{
-sent by rmir or smir in insert mode
-T}
-key_end kend @7 T{
-end key
-T}
-key_enter kent @8 T{
-enter/send key
-T}
-key_eol kel kE T{
-clear-to-end-of-line key
-T}
-key_eos ked kS T{
-clear-to-end-of-screen key
-T}
-key_exit kext @9 T{
-exit key
-T}
-key_f0 kf0 k0 T{
-F0 function key
-T}
-key_f1 kf1 k1 T{
-F1 function key
-T}
-key_f10 kf10 k; T{
-F10 function key
-T}
-key_f11 kf11 F1 T{
-F11 function key
-T}
-key_f12 kf12 F2 T{
-F12 function key
-T}
-key_f13 kf13 F3 T{
-F13 function key
-T}
-key_f14 kf14 F4 T{
-F14 function key
-T}
-key_f15 kf15 F5 T{
-F15 function key
-T}
-key_f16 kf16 F6 T{
-F16 function key
-T}
-key_f17 kf17 F7 T{
-F17 function key
-T}
-key_f18 kf18 F8 T{
-F18 function key
-T}
-key_f19 kf19 F9 T{
-F19 function key
-T}
-key_f2 kf2 k2 T{
-F2 function key
-T}
-key_f20 kf20 FA T{
-F20 function key
-T}
-key_f21 kf21 FB T{
-F21 function key
-T}
-key_f22 kf22 FC T{
-F22 function key
-T}
-key_f23 kf23 FD T{
-F23 function key
-T}
-key_f24 kf24 FE T{
-F24 function key
-T}
-key_f25 kf25 FF T{
-F25 function key
-T}
-key_f26 kf26 FG T{
-F26 function key
-T}
-key_f27 kf27 FH T{
-F27 function key
-T}
-key_f28 kf28 FI T{
-F28 function key
-T}
-key_f29 kf29 FJ T{
-F29 function key
-T}
-key_f3 kf3 k3 T{
-F3 function key
-T}
-key_f30 kf30 FK T{
-F30 function key
-T}
-key_f31 kf31 FL T{
-F31 function key
-T}
-key_f32 kf32 FM T{
-F32 function key
-T}
-key_f33 kf33 FN T{
-F33 function key
-T}
-key_f34 kf34 FO T{
-F34 function key
-T}
-key_f35 kf35 FP T{
-F35 function key
-T}
-key_f36 kf36 FQ T{
-F36 function key
-T}
-key_f37 kf37 FR T{
-F37 function key
-T}
-key_f38 kf38 FS T{
-F38 function key
-T}
-key_f39 kf39 FT T{
-F39 function key
-T}
-key_f4 kf4 k4 T{
-F4 function key
-T}
-key_f40 kf40 FU T{
-F40 function key
-T}
-key_f41 kf41 FV T{
-F41 function key
-T}
-key_f42 kf42 FW T{
-F42 function key
-T}
-key_f43 kf43 FX T{
-F43 function key
-T}
-key_f44 kf44 FY T{
-F44 function key
-T}
-key_f45 kf45 FZ T{
-F45 function key
-T}
-key_f46 kf46 Fa T{
-F46 function key
-T}
-key_f47 kf47 Fb T{
-F47 function key
-T}
-key_f48 kf48 Fc T{
-F48 function key
-T}
-key_f49 kf49 Fd T{
-F49 function key
-T}
-key_f5 kf5 k5 T{
-F5 function key
-T}
-key_f50 kf50 Fe T{
-F50 function key
-T}
-key_f51 kf51 Ff T{
-F51 function key
-T}
-key_f52 kf52 Fg T{
-F52 function key
-T}
-key_f53 kf53 Fh T{
-F53 function key
-T}
-key_f54 kf54 Fi T{
-F54 function key
-T}
-key_f55 kf55 Fj T{
-F55 function key
-T}
-key_f56 kf56 Fk T{
-F56 function key
-T}
-key_f57 kf57 Fl T{
-F57 function key
-T}
-key_f58 kf58 Fm T{
-F58 function key
-T}
-key_f59 kf59 Fn T{
-F59 function key
-T}
-key_f6 kf6 k6 T{
-F6 function key
-T}
-key_f60 kf60 Fo T{
-F60 function key
-T}
-key_f61 kf61 Fp T{
-F61 function key
-T}
-key_f62 kf62 Fq T{
-F62 function key
-T}
-key_f63 kf63 Fr T{
-F63 function key
-T}
-key_f7 kf7 k7 T{
-F7 function key
-T}
-key_f8 kf8 k8 T{
-F8 function key
-T}
-key_f9 kf9 k9 T{
-F9 function key
-T}
-key_find kfnd @0 T{
-find key
-T}
-key_help khlp %1 T{
-help key
-T}
-key_home khome kh T{
-home key
-T}
-key_ic kich1 kI T{
-insert-character key
-T}
-key_il kil1 kA T{
-insert-line key
-T}
-key_left kcub1 kl T{
-left-arrow key
-T}
-key_ll kll kH T{
-lower-left key (home down)
-T}
-key_mark kmrk %2 T{
-mark key
-T}
-key_message kmsg %3 T{
-message key
-T}
-key_move kmov %4 T{
-move key
-T}
-key_next knxt %5 T{
-next key
-T}
-key_npage knp kN T{
-next-page key
-T}
-key_open kopn %6 T{
-open key
-T}
-key_options kopt %7 T{
-options key
-T}
-key_ppage kpp kP T{
-previous-page key
-T}
-key_previous kprv %8 T{
-previous key
-T}
-key_print kprt %9 T{
-print key
-T}
-key_redo krdo %0 T{
-redo key
-T}
-key_reference kref &1 T{
-reference key
-T}
-key_refresh krfr &2 T{
-refresh key
-T}
-key_replace krpl &3 T{
-replace key
-T}
-key_restart krst &4 T{
-restart key
-T}
-key_resume kres &5 T{
-resume key
-T}
-key_right kcuf1 kr T{
-right-arrow key
-T}
-key_save ksav &6 T{
-save key
-T}
-key_sbeg kBEG &9 T{
-shifted begin key
-T}
-key_scancel kCAN &0 T{
-shifted cancel key
-T}
-key_scommand kCMD *1 T{
-shifted command key
-T}
-key_scopy kCPY *2 T{
-shifted copy key
-T}
-key_screate kCRT *3 T{
-shifted create key
-T}
-key_sdc kDC *4 T{
-shifted delete-character key
-T}
-key_sdl kDL *5 T{
-shifted delete-line key
-T}
-key_select kslt *6 T{
-select key
-T}
-key_send kEND *7 T{
-shifted end key
-T}
-key_seol kEOL *8 T{
-shifted clear-to-end-of-line key
-T}
-key_sexit kEXT *9 T{
-shifted exit key
-T}
-key_sf kind kF T{
-scroll-forward key
-T}
-key_sfind kFND *0 T{
-shifted find key
-T}
-key_shelp kHLP #1 T{
-shifted help key
-T}
-key_shome kHOM #2 T{
-shifted home key
-T}
-key_sic kIC #3 T{
-shifted insert-character key
-T}
-key_sleft kLFT #4 T{
-shifted left-arrow key
-T}
-key_smessage kMSG %a T{
-shifted message key
-T}
-key_smove kMOV %b T{
-shifted move key
-T}
-key_snext kNXT %c T{
-shifted next key
-T}
-key_soptions kOPT %d T{
-shifted options key
-T}
-key_sprevious kPRV %e T{
-shifted previous key
-T}
-key_sprint kPRT %f T{
-shifted print key
-T}
-key_sr kri kR T{
-scroll-backward key
-T}
-key_sredo kRDO %g T{
-shifted redo key
-T}
-key_sreplace kRPL %h T{
-shifted replace key
-T}
-key_sright kRIT %i T{
-shifted right-arrow key
-T}
-key_srsume kRES %j T{
-shifted resume key
-T}
-key_ssave kSAV !1 T{
-shifted save key
-T}
-key_ssuspend kSPD !2 T{
-shifted suspend key
-T}
-key_stab khts kT T{
-set-tab key
-T}
-key_sundo kUND !3 T{
-shifted undo key
-T}
-key_suspend kspd &7 T{
-suspend key
-T}
-key_undo kund &8 T{
-undo key
-T}
-key_up kcuu1 ku T{
-up-arrow key
-T}
-keypad_local rmkx ke T{
-leave 'keyboard_transmit' mode
-T}
-keypad_xmit smkx ks T{
-enter 'keyboard_transmit' mode
-T}
-lab_f0 lf0 l0 T{
-label on function key f0 if not f0
-T}
-lab_f1 lf1 l1 T{
-label on function key f1 if not f1
-T}
-lab_f10 lf10 la T{
-label on function key f10 if not f10
-T}
-lab_f2 lf2 l2 T{
-label on function key f2 if not f2
-T}
-lab_f3 lf3 l3 T{
-label on function key f3 if not f3
-T}
-lab_f4 lf4 l4 T{
-label on function key f4 if not f4
-T}
-lab_f5 lf5 l5 T{
-label on function key f5 if not f5
-T}
-lab_f6 lf6 l6 T{
-label on function key f6 if not f6
-T}
-lab_f7 lf7 l7 T{
-label on function key f7 if not f7
-T}
-lab_f8 lf8 l8 T{
-label on function key f8 if not f8
-T}
-lab_f9 lf9 l9 T{
-label on function key f9 if not f9
-T}
-label_format fln Lf T{
-label format
-T}
-label_off rmln LF T{
-turn off soft labels
-T}
-label_on smln LO T{
-turn on soft labels
-T}
-meta_off rmm mo T{
-turn off meta mode
-T}
-meta_on smm mm T{
-turn on meta mode (8th-bit on)
-T}
-micro_column_address mhpa ZY T{
-Like column_address in micro mode
-T}
-micro_down mcud1 ZZ T{
-Like cursor_down in micro mode
-T}
-micro_left mcub1 Za T{
-Like cursor_left in micro mode
-T}
-micro_right mcuf1 Zb T{
-Like cursor_right in micro mode
-T}
-micro_row_address mvpa Zc T{
-Like row_address #1 in micro mode
-T}
-micro_up mcuu1 Zd T{
-Like cursor_up in micro mode
-T}
-newline nel nw T{
-newline (behave like cr followed by lf)
-T}
-order_of_pins porder Ze T{
-Match software bits to print-head pins
-T}
-orig_colors oc oc T{
-Set all color pairs to the original ones
-T}
-orig_pair op op T{
-Set default pair to its original value
-T}
-pad_char pad pc T{
-padding char (instead of null)
-T}
-parm_dch dch DC T{
-delete #1 characters (P*)
-T}
-parm_delete_line dl DL T{
-delete #1 lines (P*)
-T}
-parm_down_cursor cud DO T{
-down #1 lines (P*)
-T}
-parm_down_micro mcud Zf T{
-Like parm_down_cursor in micro mode
-T}
-parm_ich ich IC T{
-insert #1 characters (P*)
-T}
-parm_index indn SF T{
-scroll forward #1 lines (P)
-T}
-parm_insert_line il AL T{
-insert #1 lines (P*)
-T}
-parm_left_cursor cub LE T{
-move #1 characters to the left (P)
-T}
-parm_left_micro mcub Zg T{
-Like parm_left_cursor in micro mode
-T}
-parm_right_cursor cuf RI T{
-move #1 characters to the right (P*)
-T}
-parm_right_micro mcuf Zh T{
-Like parm_right_cursor in micro mode
-T}
-parm_rindex rin SR T{
-scroll back #1 lines (P)
-T}
-parm_up_cursor cuu UP T{
-up #1 lines (P*)
-T}
-parm_up_micro mcuu Zi T{
-Like parm_up_cursor in micro mode
-T}
-pkey_key pfkey pk T{
-program function key #1 to type string #2
-T}
-pkey_local pfloc pl T{
-program function key #1 to execute string #2
-T}
-pkey_xmit pfx px T{
-program function key #1 to transmit string #2
-T}
-plab_norm pln pn T{
-program label #1 to show string #2
-T}
-print_screen mc0 ps T{
-print contents of screen
-T}
-prtr_non mc5p pO T{
-turn on printer for #1 bytes
-T}
-prtr_off mc4 pf T{
-turn off printer
-T}
-prtr_on mc5 po T{
-turn on printer
-T}
-pulse pulse PU T{
-select pulse dialing
-T}
-quick_dial qdial QD T{
-dial number #1 without checking
-T}
-remove_clock rmclk RC T{
-remove clock
-T}
-repeat_char rep rp T{
-repeat char #1 #2 times (P*)
-T}
-req_for_input rfi RF T{
-send next input char (for ptys)
-T}
-reset_1string rs1 r1 T{
-reset string
-T}
-reset_2string rs2 r2 T{
-reset string
-T}
-reset_3string rs3 r3 T{
-reset string
-T}
-reset_file rf rf T{
-name of reset file
-T}
-restore_cursor rc rc T{
-restore cursor to position of last save_cursor
-T}
-row_address vpa cv T{
-vertical position #1 absolute (P)
-T}
-save_cursor sc sc T{
-save current cursor position (P)
-T}
-scroll_forward ind sf T{
-scroll text up (P)
-T}
-scroll_reverse ri sr T{
-scroll text down (P)
-T}
-select_char_set scs Zj T{
-Select character set, #1
-T}
-set_attributes sgr sa T{
-define video attributes #1-#9 (PG9)
-T}
-set_background setb Sb T{
-Set background color #1
-T}
-set_bottom_margin smgb Zk T{
-Set bottom margin at current line
-T}
-set_bottom_margin_parm smgbp Zl T{
-Set bottom margin at line #1 or (if smgtp is not given) #2 lines from bottom
-T}
-set_clock sclk SC T{
-set clock, #1 hrs #2 mins #3 secs
-T}
-set_color_pair scp sp T{
-Set current color pair to #1
-T}
-set_foreground setf Sf T{
-Set foreground color #1
-T}
-set_left_margin smgl ML T{
-set left soft margin at current column. See smgl. (ML is not in BSD termcap).
-T}
-set_left_margin_parm smglp Zm T{
-Set left (right) margin at column #1
-T}
-set_right_margin smgr MR T{
-set right soft margin at current column
-T}
-set_right_margin_parm smgrp Zn T{
-Set right margin at column #1
-T}
-set_tab hts st T{
-set a tab in every row, current columns
-T}
-set_top_margin smgt Zo T{
-Set top margin at current line
-T}
-set_top_margin_parm smgtp Zp T{
-Set top (bottom) margin at row #1
-T}
-set_window wind wi T{
-current window is lines #1-#2 cols #3-#4
-T}
-start_bit_image sbim Zq T{
-Start printing bit image graphics
-T}
-start_char_set_def scsd Zr T{
-Start character set definition #1, with #2 characters in the set
-T}
-stop_bit_image rbim Zs T{
-Stop printing bit image graphics
-T}
-stop_char_set_def rcsd Zt T{
-End definition of character set #1
-T}
-subscript_characters subcs Zu T{
-List of subscriptable characters
-T}
-superscript_characters supcs Zv T{
-List of superscriptable characters
-T}
-tab ht ta T{
-tab to next 8-space hardware tab stop
-T}
-these_cause_cr docr Zw T{
-Printing any of these characters causes CR
-T}
-to_status_line tsl ts T{
-move to status line, column #1
-T}
-tone tone TO T{
-select touch tone dialing
-T}
-underline_char uc uc T{
-underline char and move past it
-T}
-up_half_line hu hu T{
-half a line up
-T}
-user0 u0 u0 T{
-User string #0
-T}
-user1 u1 u1 T{
-User string #1
-T}
-user2 u2 u2 T{
-User string #2
-T}
-user3 u3 u3 T{
-User string #3
-T}
-user4 u4 u4 T{
-User string #4
-T}
-user5 u5 u5 T{
-User string #5
-T}
-user6 u6 u6 T{
-User string #6
-T}
-user7 u7 u7 T{
-User string #7
-T}
-user8 u8 u8 T{
-User string #8
-T}
-user9 u9 u9 T{
-User string #9
-T}
-wait_tone wait WA T{
-wait for dial-tone
-T}
-xoff_character xoffc XF T{
-XOFF character
-T}
-xon_character xonc XN T{
-XON character
-T}
-zero_motion zerom Zx T{
-No motion for subsequent character
-T}
-.TE
-.ad
-
-The following string capabilities are present in the SVr4.0 term structure,
-but were originally not documented in the man page.
-
-.na
-.TS H
-center expand;
-c l l c
-c l l c
-lw25 lw6 lw2 lw18.
-\fBVariable Cap- TCap Description\fR
-\fBString name Code\fR
-alt_scancode_esc scesa S8 T{
-Alternate escape for scancode emulation
-T}
-bit_image_carriage_return bicr Yv T{
-Move to beginning of same row
-T}
-bit_image_newline binel Zz T{
-Move to next row of the bit image
-T}
-bit_image_repeat birep Xy T{
-Repeat bit image cell #1 #2 times
-T}
-char_set_names csnm Zy T{
-Produce #1'th item from list of character set names
-T}
-code_set_init csin ci T{
-Init sequence for multiple codesets
-T}
-color_names colornm Yw T{
-Give name for color #1
-T}
-define_bit_image_region defbi Yx T{
-Define rectangular bit image region
-T}
-device_type devt dv T{
-Indicate language/codeset support
-T}
-display_pc_char dispc S1 T{
-Display PC character #1
-T}
-end_bit_image_region endbi Yy T{
-End a bit-image region
-T}
-enter_pc_charset_mode smpch S2 T{
-Enter PC character display mode
-T}
-enter_scancode_mode smsc S4 T{
-Enter PC scancode mode
-T}
-exit_pc_charset_mode rmpch S3 T{
-Exit PC character display mode
-T}
-exit_scancode_mode rmsc S5 T{
-Exit PC scancode mode
-T}
-get_mouse getm Gm T{
-Curses should get button events, parameter #1 not documented.
-T}
-key_mouse kmous Km T{
-Mouse event has occurred
-T}
-mouse_info minfo Mi T{
-Mouse status information
-T}
-pc_term_options pctrm S6 T{
-PC terminal options
-T}
-pkey_plab pfxl xl T{
-Program function key #1 to type string #2 and show string #3
-T}
-req_mouse_pos reqmp RQ T{
-Request mouse position
-T}
-scancode_escape scesc S7 T{
-Escape for scancode emulation
-T}
-set0_des_seq s0ds s0 T{
-Shift to codeset 0 (EUC set 0, ASCII)
-T}
-set1_des_seq s1ds s1 T{
-Shift to codeset 1
-T}
-set2_des_seq s2ds s2 T{
-Shift to codeset 2
-T}
-set3_des_seq s3ds s3 T{
-Shift to codeset 3
-T}
-set_a_background setab AB T{
-Set background color to #1, using ANSI escape
-T}
-set_a_foreground setaf AF T{
-Set foreground color to #1, using ANSI escape
-T}
-set_color_band setcolor Yz T{
-Change to ribbon color #1
-T}
-set_lr_margin smglr ML T{
-Set both left and right margins to #1, #2. (ML is not in BSD termcap).
-T}
-set_page_length slines YZ T{
-Set page length to #1 lines
-T}
-set_tb_margin smgtb MT T{
-Sets both top and bottom margins to #1, #2
-T}
-.TE
-.ad
-
-.in .8i
-The XSI Curses standard added these hardcopy capabilities.
-They were used in some post-4.1 versions of System V curses,
-e.g., Solaris 2.5 and IRIX 6.x.
-Except for \fBYI\fP, the \fBncurses\fR termcap names for them are invented.
-According to the XSI Curses standard, they have no termcap names.
-If your compiled terminfo entries use these,
-they may not be binary-compatible with System V terminfo
-entries after SVr4.1; beware!
-
-.na
-.TS H
-center expand;
-c l l c
-c l l c
-lw25 lw6 lw2 lw20.
-\fBVariable Cap- TCap Description\fR
-\fBString name Code\fR
-enter_horizontal_hl_mode ehhlm Xh T{
-Enter horizontal highlight mode
-T}
-enter_left_hl_mode elhlm Xl T{
-Enter left highlight mode
-T}
-enter_low_hl_mode elohlm Xo T{
-Enter low highlight mode
-T}
-enter_right_hl_mode erhlm Xr T{
-Enter right highlight mode
-T}
-enter_top_hl_mode ethlm Xt T{
-Enter top highlight mode
-T}
-enter_vertical_hl_mode evhlm Xv T{
-Enter vertical highlight mode
-T}
-set_a_attributes sgr1 sA T{
-Define second set of video attributes #1-#6
-T}
-set_pglen_inch slength YI T{
-Set page length to #1 hundredth of an inch (some implementations use sL for termcap).
-T}
-.TE
-.ad
-.\" $Id: terminfo.tail,v 1.69 2015/04/26 14:47:23 tom Exp $
-.\" Beginning of terminfo.tail file
-.\" This file is part of ncurses.
-.\" See "terminfo.head" for copyright.
-.ps +1
-.SS User-Defined Capabilities
-.
-The preceding section listed the \fIpredefined\fP capabilities.
-They deal with some special features for terminals no longer
-(or possibly never) produced.
-Occasionally there are special features of newer terminals which
-are awkward or impossible to represent by reusing the predefined
-capabilities.
-.PP
-\fBncurses\fP addresses this limitation by allowing user-defined capabilities.
-The \fB@TIC@\fP and \fB@INFOCMP@\fP programs provide
-the \fB\-x\fP option for this purpose.
-When \fB\-x\fP is set,
-\fB@TIC@\fP treats unknown capabilities as user-defined.
-That is, if \fB@TIC@\fP encounters a capability name
-which it does not recognize,
-it infers its type (boolean, number or string) from the syntax
-and makes an extended table entry for that capability.
-The \fBuse_extended_names\fP function makes this information
-conditionally available to applications.
-The ncurses library provides the data leaving most of the behavior
-to applications:
-.bP
-User-defined capability strings whose name begins
-with \*(``k\*('' are treated as function keys.
-.bP
-The types (boolean, number, string) determined by \fB@TIC@\fP
-can be inferred by successful calls on \fBtigetflag\fP, etc.
-.bP
-If the capability name happens to be two characters,
-the capability is also available through the termcap interface.
-.PP
-While termcap is said to be extensible because it does not use a predefined set
-of capabilities,
-in practice it has been limited to the capabilities defined by
-terminfo implementations.
-As a rule,
-user-defined capabilities intended for use by termcap applications should
-be limited to booleans and numbers to avoid running past the 1023 byte
-limit assumed by termcap implementations and their applications.
-In particular, providing extended sets of function keys (past the 60
-numbered keys and the handful of special named keys) is best done using
-the longer names available using terminfo.
-.
-.SS A Sample Entry
-.
-The following entry, describing an ANSI-standard terminal, is representative
-of what a \fBterminfo\fR entry for a modern terminal typically looks like.
-.PP
-.nf
-.ft CW
-\s-2ansi|ansi/pc-term compatible with color,
- am, mc5i, mir, msgr,
- colors#8, cols#80, it#8, lines#24, ncv#3, pairs#64,
- acsc=+\\020\\,\\021-\\030.^Y0\\333`\\004a\\261f\\370g\\361h\\260
- j\\331k\\277l\\332m\\300n\\305o~p\\304q\\304r\\304s_t\\303
- u\\264v\\301w\\302x\\263y\\363z\\362{\\343|\\330}\\234~\\376,
- bel=^G, blink=\\E[5m, bold=\\E[1m, cbt=\\E[Z, clear=\\E[H\\E[J,
- cr=^M, cub=\\E[%p1%dD, cub1=\\E[D, cud=\\E[%p1%dB, cud1=\\E[B,
- cuf=\\E[%p1%dC, cuf1=\\E[C, cup=\\E[%i%p1%d;%p2%dH,
- cuu=\\E[%p1%dA, cuu1=\\E[A, dch=\\E[%p1%dP, dch1=\\E[P,
- dl=\\E[%p1%dM, dl1=\\E[M, ech=\\E[%p1%dX, ed=\\E[J, el=\\E[K,
- el1=\\E[1K, home=\\E[H, hpa=\\E[%i%p1%dG, ht=\\E[I, hts=\\EH,
- ich=\\E[%p1%d@, il=\\E[%p1%dL, il1=\\E[L, ind=^J,
- indn=\\E[%p1%dS, invis=\\E[8m, kbs=^H, kcbt=\\E[Z, kcub1=\\E[D,
- kcud1=\\E[B, kcuf1=\\E[C, kcuu1=\\E[A, khome=\\E[H, kich1=\\E[L,
- mc4=\\E[4i, mc5=\\E[5i, nel=\\r\\E[S, op=\\E[39;49m,
- rep=%p1%c\\E[%p2%{1}%-%db, rev=\\E[7m, rin=\\E[%p1%dT,
- rmacs=\\E[10m, rmpch=\\E[10m, rmso=\\E[m, rmul=\\E[m,
- s0ds=\\E(B, s1ds=\\E)B, s2ds=\\E*B, s3ds=\\E+B,
- setab=\\E[4%p1%dm, setaf=\\E[3%p1%dm,
- sgr=\\E[0;10%?%p1%t;7%;
- %?%p2%t;4%;
- %?%p3%t;7%;
- %?%p4%t;5%;
- %?%p6%t;1%;
- %?%p7%t;8%;
- %?%p9%t;11%;m,
- sgr0=\\E[0;10m, smacs=\\E[11m, smpch=\\E[11m, smso=\\E[7m,
- smul=\\E[4m, tbc=\\E[3g, u6=\\E[%i%d;%dR, u7=\\E[6n,
- u8=\\E[?%[;0123456789]c, u9=\\E[c, vpa=\\E[%i%p1%dd,
-.fi
-.ft R
-.PP
-Entries may continue onto multiple lines by placing white space at
-the beginning of each line except the first.
-Comments may be included on lines beginning with \*(``#\*(''.
-Capabilities in
-.I terminfo
-are of three types:
-.bP
-Boolean capabilities which indicate that the terminal has
-some particular feature,
-.bP
-numeric capabilities giving the size of the terminal
-or the size of particular delays, and
-.bP
-string
-capabilities, which give a sequence which can be used to perform particular
-terminal operations.
-.PP
-.SS Types of Capabilities
-.PP
-All capabilities have names.
-For instance, the fact that
-ANSI-standard terminals have
-.I "automatic margins"
-(i.e., an automatic return and line-feed
-when the end of a line is reached) is indicated by the capability \fBam\fR.
-Hence the description of ansi includes \fBam\fR.
-Numeric capabilities are followed by the character \*(``#\*('' and then a positive value.
-Thus \fBcols\fR, which indicates the number of columns the terminal has,
-gives the value \*(``80\*('' for ansi.
-Values for numeric capabilities may be specified in decimal, octal or hexadecimal,
-using the C programming language conventions (e.g., 255, 0377 and 0xff or 0xFF).
-.PP
-Finally, string valued capabilities, such as \fBel\fR (clear to end of line
-sequence) are given by the two-character code, an \*(``=\*('', and then a string
-ending at the next following \*(``,\*(''.
-.PP
-A number of escape sequences are provided in the string valued capabilities
-for easy encoding of characters there.
-Both \fB\eE\fR and \fB\ee\fR
-map to an \s-1ESCAPE\s0 character,
-\fB^x\fR maps to a control-x for any appropriate x, and the sequences
-\fB\en \el \er \et \eb \ef \es\fR give
-a newline, line-feed, return, tab, backspace, form-feed, and space.
-Other escapes include
-.bP
-\fB\e^\fR for \fB^\fR,
-.bP
-\fB\e\e\fR for \fB\e\fR,
-.bP
-\fB\e\fR, for comma,
-.bP
-\fB\e:\fR for \fB:\fR,
-.bP
-and \fB\e0\fR for null.
-.IP
-\fB\e0\fR will produce \e200, which does not terminate a string but behaves
-as a null character on most terminals, providing CS7 is specified.
-See stty(1).
-.IP
-The reason for this quirk is to maintain binary compatibility of the
-compiled terminfo files with other implementations,
-e.g., the SVr4 systems, which document this.
-Compiled terminfo files use null-terminated strings, with no lengths.
-Modifying this would require a new binary format,
-which would not work with other implementations.
-.PP
-Finally, characters may be given as three octal digits after a \fB\e\fR.
-.PP
-A delay in milliseconds may appear anywhere in a string capability, enclosed in
-$<..> brackets, as in \fBel\fP=\eEK$<5>, and padding characters are supplied by
-.I tputs
-to provide this delay.
-The delay must be a number with at most one decimal
-place of precision; it may be followed by suffixes \*(``*\*('' or \*(``/\*('' or both.
-A \*(``*\*(''
-indicates that the padding required is proportional to the number of lines
-affected by the operation, and the amount given is the per-affected-unit
-padding required.
-(In the case of insert character, the factor is still the
-number of
-.IR lines
-affected.) Normally, padding is advisory if the device has the \fBxon\fR
-capability; it is used for cost computation but does not trigger delays.
-A \*(``/\*(''
-suffix indicates that the padding is mandatory and forces a delay of the given
-number of milliseconds even on devices for which \fBxon\fR is present to
-indicate flow control.
-.PP
-Sometimes individual capabilities must be commented out.
-To do this, put a period before the capability name.
-For example, see the second
-.B ind
-in the example above.
-.br
-.ne 5
-.PP
-.SS Fetching Compiled Descriptions
-.PP
-The \fBncurses\fP library searches for terminal descriptions in several places.
-It uses only the first description found.
-The library has a compiled-in list of places to search
-which can be overridden by environment variables.
-Before starting to search,
-\fBncurses\fP eliminates duplicates in its search list.
-.bP
-If the environment variable TERMINFO is set, it is interpreted as the pathname
-of a directory containing the compiled description you are working on.
-Only that directory is searched.
-.bP
-If TERMINFO is not set,
-\fBncurses\fR will instead look in the directory \fB$HOME/.terminfo\fR
-for a compiled description.
-.bP
-Next, if the environment variable TERMINFO_DIRS is set,
-\fBncurses\fR will interpret the contents of that variable
-as a list of colon-separated directories (or database files) to be searched.
-.IP
-An empty directory name (i.e., if the variable begins or ends
-with a colon, or contains adjacent colons)
-is interpreted as the system location \fI\*d\fR.
-.bP
-Finally, \fBncurses\fP searches these compiled-in locations:
-.RS
-.bP
-a list of directories (@TERMINFO_DIRS@), and
-.bP
-the system terminfo directory, \fI\*d\fR (the compiled-in default).
-.RE
-.SS Preparing Descriptions
-.PP
-We now outline how to prepare descriptions of terminals.
-The most effective way to prepare a terminal description is by imitating
-the description of a similar terminal in
-.I terminfo
-and to build up a description gradually, using partial descriptions
-with
-.I vi
-or some other screen-oriented program to check that they are correct.
-Be aware that a very unusual terminal may expose deficiencies in
-the ability of the
-.I terminfo
-file to describe it
-or bugs in the screen-handling code of the test program.
-.PP
-To get the padding for insert line right (if the terminal manufacturer
-did not document it) a severe test is to edit a large file at 9600 baud,
-delete 16 or so lines from the middle of the screen, then hit the \*(``u\*(''
-key several times quickly.
-If the terminal messes up, more padding is usually needed.
-A similar test can be used for insert character.
-.PP
-.SS Basic Capabilities
-.PP
-The number of columns on each line for the terminal is given by the
-\fBcols\fR numeric capability.
-If the terminal is a \s-1CRT\s0, then the
-number of lines on the screen is given by the \fBlines\fR capability.
-If the terminal wraps around to the beginning of the next line when
-it reaches the right margin, then it should have the \fBam\fR capability.
-If the terminal can clear its screen, leaving the cursor in the home
-position, then this is given by the \fBclear\fR string capability.
-If the terminal overstrikes
-(rather than clearing a position when a character is struck over)
-then it should have the \fBos\fR capability.
-If the terminal is a printing terminal, with no soft copy unit,
-give it both
-.B hc
-and
-.BR os .
-.RB ( os
-applies to storage scope terminals, such as \s-1TEKTRONIX\s+1 4010
-series, as well as hard copy and APL terminals.)
-If there is a code to move the cursor to the left edge of the current
-row, give this as
-.BR cr .
-(Normally this will be carriage return, control M.)
-If there is a code to produce an audible signal (bell, beep, etc)
-give this as
-.BR bel .
-.PP
-If there is a code to move the cursor one position to the left
-(such as backspace) that capability should be given as
-.BR cub1 .
-Similarly, codes to move to the right, up, and down should be
-given as
-.BR cuf1 ,
-.BR cuu1 ,
-and
-.BR cud1 .
-These local cursor motions should not alter the text they pass over,
-for example, you would not normally use \*(``\fBcuf1\fP=\ \*('' because the
-space would erase the character moved over.
-.PP
-A very important point here is that the local cursor motions encoded
-in
-.I terminfo
-are undefined at the left and top edges of a \s-1CRT\s0 terminal.
-Programs should never attempt to backspace around the left edge,
-unless
-.B bw
-is given,
-and never attempt to go up locally off the top.
-In order to scroll text up, a program will go to the bottom left corner
-of the screen and send the
-.B ind
-(index) string.
-.PP
-To scroll text down, a program goes to the top left corner
-of the screen and sends the
-.B ri
-(reverse index) string.
-The strings
-.B ind
-and
-.B ri
-are undefined when not on their respective corners of the screen.
-.PP
-Parameterized versions of the scrolling sequences are
-.B indn
-and
-.B rin
-which have the same semantics as
-.B ind
-and
-.B ri
-except that they take one parameter, and scroll that many lines.
-They are also undefined except at the appropriate edge of the screen.
-.PP
-The \fBam\fR capability tells whether the cursor sticks at the right
-edge of the screen when text is output, but this does not necessarily
-apply to a
-.B cuf1
-from the last column.
-The only local motion which is defined from the left edge is if
-.B bw
-is given, then a
-.B cub1
-from the left edge will move to the right edge of the previous row.
-If
-.B bw
-is not given, the effect is undefined.
-This is useful for drawing a box around the edge of the screen, for example.
-If the terminal has switch selectable automatic margins,
-the
-.I terminfo
-file usually assumes that this is on; i.e., \fBam\fR.
-If the terminal has a command which moves to the first column of the next
-line, that command can be given as
-.B nel
-(newline).
-It does not matter if the command clears the remainder of the current line,
-so if the terminal has no
-.B cr
-and
-.B lf
-it may still be possible to craft a working
-.B nel
-out of one or both of them.
-.PP
-These capabilities suffice to describe hard-copy and \*(lqglass-tty\*(rq terminals.
-Thus the model 33 teletype is described as
-.PP
-.DT
-.nf
-.ft CW
-.\".in -2
-\s-133\||\|tty33\||\|tty\||\|model 33 teletype,
- bel=^G, cols#72, cr=^M, cud1=^J, hc, ind=^J, os,\s+1
-.\".in +2
-.ft R
-.fi
-.PP
-while the Lear Siegler \s-1ADM-3\s0 is described as
-.PP
-.DT
-.nf
-.ft CW
-.\".in -2
-\s-1adm3\||\|3\||\|lsi adm3,
- am, bel=^G, clear=^Z, cols#80, cr=^M, cub1=^H, cud1=^J,
- ind=^J, lines#24,\s+1
-.\".in +2
-.ft R
-.fi
-.PP
-.SS Parameterized Strings
-.PP
-Cursor addressing and other strings requiring parameters
-in the terminal are described by a
-parameterized string capability,
-with \fIprintf\fP-like escapes such as \fI%x\fR in it.
-For example, to address the cursor, the
-.B cup
-capability is given, using two parameters:
-the row and column to address to.
-(Rows and columns are numbered from zero and refer to the
-physical screen visible to the user, not to any unseen memory.)
-If the terminal has memory relative cursor addressing,
-that can be indicated by
-.BR mrcup .
-.PP
-The parameter mechanism uses a stack and special \fB%\fP codes
-to manipulate it.
-Typically a sequence will push one of the
-parameters onto the stack and then print it in some format.
-Print (e.g., "%d") is a special case.
-Other operations, including "%t" pop their operand from the stack.
-It is noted that more complex operations are often necessary,
-e.g., in the \fBsgr\fP string.
-.PP
-The \fB%\fR encodings have the following meanings:
-.PP
-.TP 5
-\fB%%\fP
-outputs \*(``%\*(''
-.TP
-\fB%\fP\fI[[\fP:\fI]flags][width[.precision]][\fP\fBdoxXs\fP\fI]\fP
-as in \fBprintf\fP, flags are \fI[\-+#]\fP and \fIspace\fP.
-Use a \*(``:\*('' to allow the next character to be a \*(``\-\*('' flag,
-avoiding interpreting "%\-" as an operator.
-.TP
-\f(CW%c\fP
-print pop() like %c in \fBprintf\fP
-.TP
-\fB%s\fP
-print pop() like %s in \fBprintf\fP
-.TP
-\fB%p\fP\fI[1\-9]\fP
-push \fIi\fP'th parameter
-.TP
-\fB%P\fP\fI[a\-z]\fP
-set dynamic variable \fI[a\-z]\fP to pop()
-.TP
-\fB%g\fP\fI[a\-z]/\fP
-get dynamic variable \fI[a\-z]\fP and push it
-.TP
-\fB%P\fP\fI[A\-Z]\fP
-set static variable \fI[a\-z]\fP to \fIpop()\fP
-.TP
-\fB%g\fP\fI[A\-Z]\fP
-get static variable \fI[a\-z]\fP and push it
-.IP
-The terms "static" and "dynamic" are misleading.
-Historically, these are simply two different sets of variables,
-whose values are not reset between calls to \fBtparm\fP.
-However, that fact is not documented in other implementations.
-Relying on it will adversely impact portability to other implementations.
-.TP
-\fB%'\fP\fIc\fP\fB'\fP
-char constant \fIc\fP
-.TP
-\fB%{\fP\fInn\fP\fB}\fP
-integer constant \fInn\fP
-.TP
-\fB%l\fP
-push strlen(pop)
-.TP
-\fB%+\fP, \fB%\-\fP, \fB%*\fP, \fB%/\fP, \fB%m\fP
-arithmetic (%m is mod): \fIpush(pop() op pop())\fP
-.TP
-\fB%&\fP, \fB%|\fP, \fB%^\fP
-bit operations (AND, OR and exclusive-OR): \fIpush(pop() op pop())\fP
-.TP
-\fB%=\fP, \fB%>\fP, \fB%<\fP
-logical operations: \fIpush(pop() op pop())\fP
-.TP
-\fB%A\fP, \fB%O\fP
-logical AND and OR operations (for conditionals)
-.TP
-\fB%!\fP, \fB%~\fP
-unary operations (logical and bit complement): push(op pop())
-.TP
-\fB%i\fP
-add 1 to first two parameters (for ANSI terminals)
-.TP
-\fB%?\fP \fIexpr\fP \fB%t\fP \fIthenpart\fP \fB%e\fP \fIelsepart\fP \fB%;\fP
-This forms an if-then-else.
-The \fB%e\fP \fIelsepart\fP is optional.
-Usually the \fB%?\fP \fIexpr\fP part pushes a value onto the stack,
-and \fB%t\fP pops it from the stack, testing if it is nonzero (true).
-If it is zero (false), control passes to the \fB%e\fP (else) part.
-.IP
-It is possible to form else-if's a la Algol 68:
-.RS
-\fB%?\fP c\d1\u \fB%t\fP b\d1\u \fB%e\fP c\d2\u \fB%t\fP b\d2\u \fB%e\fP c\d3\u \fB%t\fP b\d3\u \fB%e\fP c\d4\u \fB%t\fP b\d4\u \fB%e\fP \fB%;\fP
-.RE
-.IP
-where c\di\u are conditions, b\di\u are bodies.
-.IP
-Use the \fB\-f\fP option of \fB@TIC@\fP or \fB@INFOCMP@\fP to see
-the structure of if-then-else's.
-Some strings, e.g., \fBsgr\fP can be very complicated when written
-on one line.
-The \fB\-f\fP option splits the string into lines with the parts indented.
-.PP
-Binary operations are in postfix form with the operands in the usual order.
-That is, to get x\-5 one would use "%gx%{5}%-".
-\fB%P\fP and \fB%g\fP variables are
-persistent across escape-string evaluations.
-.PP
-Consider the HP2645, which, to get to row 3 and column 12, needs
-to be sent \eE&a12c03Y padded for 6 milliseconds.
-Note that the order
-of the rows and columns is inverted here, and that the row and column
-are printed as two digits.
-Thus its \fBcup\fR capability is \*(lqcup=6\eE&%p2%2dc%p1%2dY\*(rq.
-.PP
-The Microterm \s-1ACT-IV\s0 needs the current row and column sent
-preceded by a \fB^T\fR, with the row and column simply encoded in binary,
-\*(lqcup=^T%p1%c%p2%c\*(rq.
-Terminals which use \*(lq%c\*(rq need to be able to
-backspace the cursor (\fBcub1\fR),
-and to move the cursor up one line on the screen (\fBcuu1\fR).
-This is necessary because it is not always safe to transmit \fB\en\fR
-\fB^D\fR and \fB\er\fR, as the system may change or discard them.
-(The library routines dealing with terminfo set tty modes so that
-tabs are never expanded, so \et is safe to send.
-This turns out to be essential for the Ann Arbor 4080.)
-.PP
-A final example is the \s-1LSI ADM\s0-3a, which uses row and column
-offset by a blank character, thus \*(lqcup=\eE=%p1%' '%+%c%p2%' '%+%c\*(rq.
-After sending \*(``\eE=\*('', this pushes the first parameter, pushes the
-ASCII value for a space (32), adds them (pushing the sum on the stack
-in place of the two previous values) and outputs that value as a character.
-Then the same is done for the second parameter.
-More complex arithmetic is possible using the stack.
-.PP
-.SS Cursor Motions
-.PP
-If the terminal has a fast way to home the cursor
-(to very upper left corner of screen) then this can be given as
-\fBhome\fR; similarly a fast way of getting to the lower left-hand corner
-can be given as \fBll\fR; this may involve going up with \fBcuu1\fR
-from the home position,
-but a program should never do this itself (unless \fBll\fR does) because it
-can make no assumption about the effect of moving up from the home position.
-Note that the home position is the same as addressing to (0,0):
-to the top left corner of the screen, not of memory.
-(Thus, the \eEH sequence on HP terminals cannot be used for
-.BR home .)
-.PP
-If the terminal has row or column absolute cursor addressing,
-these can be given as single parameter capabilities
-.B hpa
-(horizontal position absolute)
-and
-.B vpa
-(vertical position absolute).
-Sometimes these are shorter than the more general two parameter
-sequence (as with the hp2645) and can be used in preference to
-.BR cup .
-If there are parameterized local motions (e.g., move
-.I n
-spaces to the right) these can be given as
-.BR cud ,
-.BR cub ,
-.BR cuf ,
-and
-.BR cuu
-with a single parameter indicating how many spaces to move.
-These are primarily useful if the terminal does not have
-.BR cup ,
-such as the \s-1TEKTRONIX\s+1 4025.
-.PP
-If the terminal needs to be in a special mode when running
-a program that uses these capabilities,
-the codes to enter and exit this mode can be given as \fBsmcup\fR and \fBrmcup\fR.
-This arises, for example, from terminals like the Concept with more than
-one page of memory.
-If the terminal has only memory relative cursor addressing and not screen
-relative cursor addressing, a one screen-sized window must be fixed into
-the terminal for cursor addressing to work properly.
-This is also used for the \s-1TEKTRONIX\s+1 4025,
-where
-.B smcup
-sets the command character to be the one used by terminfo.
-If the \fBsmcup\fP sequence will not restore the screen after an
-\fBrmcup\fP sequence is output (to the state prior to outputting
-\fBrmcup\fP), specify \fBnrrmc\fP.
-.PP
-.SS Area Clears
-.PP
-If the terminal can clear from the current position to the end of the
-line, leaving the cursor where it is, this should be given as \fBel\fR.
-If the terminal can clear from the beginning of the line to the current
-position inclusive, leaving
-the cursor where it is, this should be given as \fBel1\fP.
-If the terminal can clear from the current position to the end of the
-display, then this should be given as \fBed\fR.
-\fBEd\fR is only defined from the first column of a line.
-(Thus, it can be simulated by a request to delete a large number of lines,
-if a true
-.B ed
-is not available.)
-.PP
-.SS Insert/delete line and vertical motions
-.PP
-If the terminal can open a new blank line before the line where the cursor
-is, this should be given as \fBil1\fR; this is done only from the first
-position of a line.
-The cursor must then appear on the newly blank line.
-If the terminal can delete the line which the cursor is on, then this
-should be given as \fBdl1\fR; this is done only from the first position on
-the line to be deleted.
-Versions of
-.B il1
-and
-.B dl1
-which take a single parameter and insert or delete that many lines can
-be given as
-.B il
-and
-.BR dl .
-.PP
-If the terminal has a settable scrolling region (like the vt100)
-the command to set this can be described with the
-.B csr
-capability, which takes two parameters:
-the top and bottom lines of the scrolling region.
-The cursor position is, alas, undefined after using this command.
-.PP
-It is possible to get the effect of insert or delete line using
-.B csr
-on a properly chosen region; the
-.B sc
-and
-.B rc
-(save and restore cursor) commands may be useful for ensuring that
-your synthesized insert/delete string does not move the cursor.
-(Note that the \fBncurses\fR(3X) library does this synthesis
-automatically, so you need not compose insert/delete strings for
-an entry with \fBcsr\fR).
-.PP
-Yet another way to construct insert and delete might be to use a combination of
-index with the memory-lock feature found on some terminals (like the HP\-700/90
-series, which however also has insert/delete).
-.PP
-Inserting lines at the top or bottom of the screen can also be
-done using
-.B ri
-or
-.B ind
-on many terminals without a true insert/delete line,
-and is often faster even on terminals with those features.
-.PP
-The boolean \fBnon_dest_scroll_region\fR should be set if each scrolling
-window is effectively a view port on a screen-sized canvas.
-To test for
-this capability, create a scrolling region in the middle of the screen,
-write something to the bottom line, move the cursor to the top of the region,
-and do \fBri\fR followed by \fBdl1\fR or \fBind\fR.
-If the data scrolled
-off the bottom of the region by the \fBri\fR re-appears, then scrolling
-is non-destructive.
-System V and XSI Curses expect that \fBind\fR, \fBri\fR,
-\fBindn\fR, and \fBrin\fR will simulate destructive scrolling; their
-documentation cautions you not to define \fBcsr\fR unless this is true.
-This \fBcurses\fR implementation is more liberal and will do explicit erases
-after scrolling if \fBndstr\fR is defined.
-.PP
-If the terminal has the ability to define a window as part of
-memory, which all commands affect,
-it should be given as the parameterized string
-.BR wind .
-The four parameters are the starting and ending lines in memory
-and the starting and ending columns in memory, in that order.
-.PP
-If the terminal can retain display memory above, then the
-\fBda\fR capability should be given; if display memory can be retained
-below, then \fBdb\fR should be given.
-These indicate
-that deleting a line or scrolling may bring non-blank lines up from below
-or that scrolling back with \fBri\fR may bring down non-blank lines.
-.PP
-.SS Insert/Delete Character
-.PP
-There are two basic kinds of intelligent terminals with respect to
-insert/delete character which can be described using
-.I terminfo.
-The most common insert/delete character operations affect only the characters
-on the current line and shift characters off the end of the line rigidly.
-Other terminals, such as the Concept 100 and the Perkin Elmer Owl, make
-a distinction between typed and untyped blanks on the screen, shifting
-upon an insert or delete only to an untyped blank on the screen which is
-either eliminated, or expanded to two untyped blanks.
-.PP
-You can determine the
-kind of terminal you have by clearing the screen and then typing
-text separated by cursor motions.
-Type \*(lqabc\ \ \ \ def\*(rq using local
-cursor motions (not spaces) between the \*(lqabc\*(rq and the \*(lqdef\*(rq.
-Then position the cursor before the \*(lqabc\*(rq and put the terminal in insert
-mode.
-If typing characters causes the rest of the line to shift
-rigidly and characters to fall off the end, then your terminal does
-not distinguish between blanks and untyped positions.
-If the \*(lqabc\*(rq
-shifts over to the \*(lqdef\*(rq which then move together around the end of the
-current line and onto the next as you insert, you have the second type of
-terminal, and should give the capability \fBin\fR, which stands for
-\*(lqinsert null\*(rq.
-.PP
-While these are two logically separate attributes (one line versus multi-line
-insert mode, and special treatment of untyped spaces) we have seen no
-terminals whose insert mode cannot be described with the single attribute.
-.PP
-Terminfo can describe both terminals which have an insert mode, and terminals
-which send a simple sequence to open a blank position on the current line.
-Give as \fBsmir\fR the sequence to get into insert mode.
-Give as \fBrmir\fR the sequence to leave insert mode.
-Now give as \fBich1\fR any sequence needed to be sent just before sending
-the character to be inserted.
-Most terminals with a true insert mode
-will not give \fBich1\fR; terminals which send a sequence to open a screen
-position should give it here.
-.PP
-If your terminal has both, insert mode is usually preferable to \fBich1\fR.
-Technically, you should not give both unless the terminal actually requires
-both to be used in combination.
-Accordingly, some non-curses applications get
-confused if both are present; the symptom is doubled characters in an update
-using insert.
-This requirement is now rare; most \fBich\fR sequences do not
-require previous smir, and most smir insert modes do not require \fBich1\fR
-before each character.
-Therefore, the new \fBcurses\fR actually assumes this
-is the case and uses either \fBrmir\fR/\fBsmir\fR or \fBich\fR/\fBich1\fR as
-appropriate (but not both).
-If you have to write an entry to be used under
-new curses for a terminal old enough to need both, include the
-\fBrmir\fR/\fBsmir\fR sequences in \fBich1\fR.
-.PP
-If post insert padding is needed, give this as a number of milliseconds
-in \fBip\fR (a string option).
-Any other sequence which may need to be
-sent after an insert of a single character may also be given in \fBip\fR.
-If your terminal needs both to be placed into an \*(``insert mode\*('' and
-a special code to precede each inserted character, then both
-.BR smir / rmir
-and
-.B ich1
-can be given, and both will be used.
-The
-.B ich
-capability, with one parameter,
-.IR n ,
-will repeat the effects of
-.B ich1
-.I n
-times.
-.PP
-If padding is necessary between characters typed while not
-in insert mode, give this as a number of milliseconds padding in \fBrmp\fP.
-.PP
-It is occasionally necessary to move around while in insert mode
-to delete characters on the same line (e.g., if there is a tab after
-the insertion position).
-If your terminal allows motion while in
-insert mode you can give the capability \fBmir\fR to speed up inserting
-in this case.
-Omitting \fBmir\fR will affect only speed.
-Some terminals
-(notably Datamedia's) must not have \fBmir\fR because of the way their
-insert mode works.
-.PP
-Finally, you can specify
-.B dch1
-to delete a single character,
-.B dch
-with one parameter,
-.IR n ,
-to delete
-.I n characters,
-and delete mode by giving \fBsmdc\fR and \fBrmdc\fR
-to enter and exit delete mode (any mode the terminal needs to be placed
-in for
-.B dch1
-to work).
-.PP
-A command to erase
-.I n
-characters (equivalent to outputting
-.I n
-blanks without moving the cursor)
-can be given as
-.B ech
-with one parameter.
-.PP
-.SS "Highlighting, Underlining, and Visible Bells"
-.PP
-If your terminal has one or more kinds of display attributes,
-these can be represented in a number of different ways.
-You should choose one display form as
-\f2standout mode\fR,
-representing a good, high contrast, easy-on-the-eyes,
-format for highlighting error messages and other attention getters.
-(If you have a choice, reverse video plus half-bright is good,
-or reverse video alone.)
-The sequences to enter and exit standout mode
-are given as \fBsmso\fR and \fBrmso\fR, respectively.
-If the code to change into or out of standout
-mode leaves one or even two blank spaces on the screen,
-as the TVI 912 and Teleray 1061 do,
-then \fBxmc\fR should be given to tell how many spaces are left.
-.PP
-Codes to begin underlining and end underlining can be given as \fBsmul\fR
-and \fBrmul\fR respectively.
-If the terminal has a code to underline the current character and move
-the cursor one space to the right,
-such as the Microterm Mime,
-this can be given as \fBuc\fR.
-.PP
-Other capabilities to enter various highlighting modes include
-.B blink
-(blinking)
-.B bold
-(bold or extra bright)
-.B dim
-(dim or half-bright)
-.B invis
-(blanking or invisible text)
-.B prot
-(protected)
-.B rev
-(reverse video)
-.B sgr0
-(turn off
-.I all
-attribute modes)
-.B smacs
-(enter alternate character set mode)
-and
-.B rmacs
-(exit alternate character set mode).
-Turning on any of these modes singly may or may not turn off other modes.
-.PP
-If there is a sequence to set arbitrary combinations of modes,
-this should be given as
-.B sgr
-(set attributes),
-taking 9 parameters.
-Each parameter is either 0 or nonzero, as the corresponding attribute is on or off.
-The 9 parameters are, in order:
-standout, underline, reverse, blink, dim, bold, blank, protect, alternate
-character set.
-Not all modes need be supported by
-.BR sgr ,
-only those for which corresponding separate attribute commands exist.
-.PP
-For example, the DEC vt220 supports most of the modes:
-.PP
-.TS
-center;
-l l l
-l l l
-lw18 lw14 lw18.
-\fBtparm parameter attribute escape sequence\fP
-
-none none \\E[0m
-p1 standout \\E[0;1;7m
-p2 underline \\E[0;4m
-p3 reverse \\E[0;7m
-p4 blink \\E[0;5m
-p5 dim not available
-p6 bold \\E[0;1m
-p7 invis \\E[0;8m
-p8 protect not used
-p9 altcharset ^O (off) ^N (on)
-.TE
-.PP
-We begin each escape sequence by turning off any existing modes, since
-there is no quick way to determine whether they are active.
-Standout is set up to be the combination of reverse and bold.
-The vt220 terminal has a protect mode,
-though it is not commonly used in sgr
-because it protects characters on the screen from the host's erasures.
-The altcharset mode also is different in that it is either ^O or ^N,
-depending on whether it is off or on.
-If all modes are turned on, the resulting sequence is \\E[0;1;4;5;7;8m^N.
-.PP
-Some sequences are common to different modes.
-For example, ;7 is output when either p1 or p3 is true, that is, if
-either standout or reverse modes are turned on.
-.PP
-Writing out the above sequences, along with their dependencies yields
-.PP
-.ne 11
-.TS
-center;
-l l l
-l l l
-lw18 lw14 lw18.
-\fBsequence when to output terminfo translation\fP
-
-.ft CW
-\\E[0 always \\E[0
-;1 if p1 or p6 %?%p1%p6%|%t;1%;
-;4 if p2 %?%p2%|%t;4%;
-;5 if p4 %?%p4%|%t;5%;
-;7 if p1 or p3 %?%p1%p3%|%t;7%;
-;8 if p7 %?%p7%|%t;8%;
-m always m
-^N or ^O if p9 ^N, else ^O %?%p9%t^N%e^O%;
-.ft R
-.TE
-.PP
-Putting this all together into the sgr sequence gives:
-.PP
-.ft CW
-.nf
- sgr=\\E[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p4%t;5%;
- %?%p1%p3%|%t;7%;%?%p7%t;8%;m%?%p9%t\\016%e\\017%;,
-.fi
-.ft R
-.PP
-Remember that if you specify sgr, you must also specify sgr0.
-Also, some implementations rely on sgr being given if sgr0 is,
-Not all terminfo entries necessarily have an sgr string, however.
-Many terminfo entries are derived from termcap entries
-which have no sgr string.
-The only drawback to adding an sgr string is that termcap also
-assumes that sgr0 does not exit alternate character set mode.
-.PP
-Terminals with the \*(``magic cookie\*('' glitch
-.RB ( xmc )
-deposit special \*(``cookies\*('' when they receive mode-setting sequences,
-which affect the display algorithm rather than having extra bits for
-each character.
-Some terminals, such as the HP 2621, automatically leave standout
-mode when they move to a new line or the cursor is addressed.
-Programs using standout mode should exit standout mode before
-moving the cursor or sending a newline,
-unless the
-.B msgr
-capability, asserting that it is safe to move in standout mode, is present.
-.PP
-If the terminal has
-a way of flashing the screen to indicate an error quietly (a bell replacement)
-then this can be given as \fBflash\fR; it must not move the cursor.
-.PP
-If the cursor needs to be made more visible than normal when it is
-not on the bottom line (to make, for example, a non-blinking underline into an
-easier to find block or blinking underline)
-give this sequence as
-.BR cvvis .
-If there is a way to make the cursor completely invisible, give that as
-.BR civis .
-The capability
-.BR cnorm
-should be given which undoes the effects of both of these modes.
-.PP
-If your terminal correctly generates underlined characters
-(with no special codes needed)
-even though it does not overstrike,
-then you should give the capability \fBul\fR.
-If a character overstriking another leaves both characters on the screen,
-specify the capability \fBos\fP.
-If overstrikes are erasable with a blank,
-then this should be indicated by giving \fBeo\fR.
-.PP
-.SS Keypad and Function Keys
-.PP
-If the terminal has a keypad that transmits codes when the keys are pressed,
-this information can be given.
-Note that it is not possible to handle
-terminals where the keypad only works in local (this applies, for example,
-to the unshifted HP 2621 keys).
-If the keypad can be set to transmit or not transmit,
-give these codes as \fBsmkx\fR and \fBrmkx\fR.
-Otherwise the keypad is assumed to always transmit.
-.PP
-The codes sent by the left arrow, right arrow, up arrow, down arrow,
-and home keys can be given as
-\fBkcub1, kcuf1, kcuu1, kcud1, \fRand\fB khome\fR respectively.
-If there are function keys such as f0, f1, ..., f10, the codes they send
-can be given as \fBkf0, kf1, ..., kf10\fR.
-If these keys have labels other than the default f0 through f10, the labels
-can be given as \fBlf0, lf1, ..., lf10\fR.
-.PP
-The codes transmitted by certain other special keys can be given:
-.bP
-.B kll
-(home down),
-.bP
-.B kbs
-(backspace),
-.bP
-.B ktbc
-(clear all tabs),
-.bP
-.B kctab
-(clear the tab stop in this column),
-.bP
-.B kclr
-(clear screen or erase key),
-.bP
-.B kdch1
-(delete character),
-.bP
-.B kdl1
-(delete line),
-.bP
-.B krmir
-(exit insert mode),
-.bP
-.B kel
-(clear to end of line),
-.bP
-.B ked
-(clear to end of screen),
-.bP
-.B kich1
-(insert character or enter insert mode),
-.bP
-.B kil1
-(insert line),
-.bP
-.B knp
-(next page),
-.bP
-.B kpp
-(previous page),
-.bP
-.B kind
-(scroll forward/down),
-.bP
-.B kri
-(scroll backward/up),
-.bP
-.B khts
-(set a tab stop in this column).
-.PP
-In addition, if the keypad has a 3 by 3 array of keys including the four
-arrow keys, the other five keys can be given as
-.BR ka1 ,
-.BR ka3 ,
-.BR kb2 ,
-.BR kc1 ,
-and
-.BR kc3 .
-These keys are useful when the effects of a 3 by 3 directional pad are needed.
-.PP
-Strings to program function keys can be given as
-.BR pfkey ,
-.BR pfloc ,
-and
-.BR pfx .
-A string to program screen labels should be specified as \fBpln\fP.
-Each of these strings takes two parameters: the function key number to
-program (from 0 to 10) and the string to program it with.
-Function key numbers out of this range may program undefined keys in
-a terminal dependent manner.
-The difference between the capabilities is that
-.B pfkey
-causes pressing the given key to be the same as the user typing the
-given string;
-.B pfloc
-causes the string to be executed by the terminal in local; and
-.B pfx
-causes the string to be transmitted to the computer.
-.PP
-The capabilities \fBnlab\fP, \fBlw\fP and \fBlh\fP
-define the number of programmable
-screen labels and their width and height.
-If there are commands to turn the labels on and off,
-give them in \fBsmln\fP and \fBrmln\fP.
-\fBsmln\fP is normally output after one or more pln
-sequences to make sure that the change becomes visible.
-.PP
-.SS Tabs and Initialization
-.PP
-If the terminal has hardware tabs, the command to advance to the next
-tab stop can be given as
-.B ht
-(usually control I).
-A \*(``back-tab\*('' command which moves leftward to the preceding tab stop can
-be given as
-.BR cbt .
-By convention, if the teletype modes indicate that tabs are being
-expanded by the computer rather than being sent to the terminal,
-programs should not use
-.B ht
-or
-.B cbt
-even if they are present, since the user may not have the tab stops
-properly set.
-If the terminal has hardware tabs which are initially set every
-.I n
-spaces when the terminal is powered up,
-the numeric parameter
-.B it
-is given, showing the number of spaces the tabs are set to.
-This is normally used by the
-.IR @TSET@
-command to determine whether to set the mode for hardware tab expansion,
-and whether to set the tab stops.
-If the terminal has tab stops that can be saved in non-volatile memory,
-the terminfo description can assume that they are properly set.
-.PP
-Other capabilities
-include
-.BR is1 ,
-.BR is2 ,
-and
-.BR is3 ,
-initialization strings for the terminal,
-.BR iprog ,
-the path name of a program to be run to initialize the terminal,
-and \fBif\fR, the name of a file containing long initialization strings.
-These strings are expected to set the terminal into modes consistent
-with the rest of the terminfo description.
-They are normally sent to the terminal, by the
-.I init
-option of the
-.IR @TPUT@
-program, each time the user logs in.
-They will be printed in the following order:
-.RS
-.TP
-run the program
-.BR iprog
-.TP
-output
-.BR is1
-.BR is2
-.TP
-set the margins using
-.BR mgc ,
-.BR smgl
-and
-.BR smgr
-.TP
-set tabs using
-.B tbc
-and
-.BR hts
-.TP
-print the file
-.BR if
-.TP
-and finally
-output
-.BR is3 .
-.RE
-.PP
-Most initialization is done with
-.BR is2 .
-Special terminal modes can be set up without duplicating strings
-by putting the common sequences in
-.B is2
-and special cases in
-.B is1
-and
-.BR is3 .
-.PP
-A set of sequences that does a harder reset from a totally unknown state
-can be given as
-.BR rs1 ,
-.BR rs2 ,
-.BR rf
-and
-.BR rs3 ,
-analogous to
-.B is1 ,
-.B is2 ,
-.B if
-and
-.BR is3
-respectively.
-These strings are output by the
-.IR reset
-program, which is used when the terminal gets into a wedged state.
-Commands are normally placed in
-.BR rs1 ,
-.BR rs2
-.B rs3
-and
-.B rf
-only if they produce annoying effects on the screen and are not
-necessary when logging in.
-For example, the command to set the vt100 into 80-column mode would
-normally be part of
-.BR is2 ,
-but it causes an annoying glitch of the screen and is not normally
-needed since the terminal is usually already in 80 column mode.
-.PP
-The
-.IR reset
-program writes strings
-including
-.BR iprog ,
-etc., in the same order as the
-.IR init
-program, using
-.BR rs1 ,
-etc., instead of
-.BR is1 ,
-etc.
-If any of
-.BR rs1 ,
-.BR rs2 ,
-.BR rs3 ,
-or
-.BR rf
-reset capability strings are missing, the
-.IR reset
-program falls back upon the corresponding initialization capability string.
-.PP
-If there are commands to set and clear tab stops, they can be given as
-.B tbc
-(clear all tab stops)
-and
-.B hts
-(set a tab stop in the current column of every row).
-If a more complex sequence is needed to set the tabs than can be
-described by this, the sequence can be placed in
-.B is2
-or
-.BR if .
-.SS Delays and Padding
-.PP
-Many older and slower terminals do not support either XON/XOFF or DTR
-handshaking, including hard copy terminals and some very archaic CRTs
-(including, for example, DEC VT100s).
-These may require padding characters
-after certain cursor motions and screen changes.
-.PP
-If the terminal uses xon/xoff handshaking for flow control (that is,
-it automatically emits ^S back to the host when its input buffers are
-close to full), set
-.BR xon .
-This capability suppresses the emission of padding.
-You can also set it
-for memory-mapped console devices effectively that do not have a speed limit.
-Padding information should still be included so that routines can
-make better decisions about relative costs, but actual pad characters will
-not be transmitted.
-.PP
-If \fBpb\fR (padding baud rate) is given, padding is suppressed at baud rates
-below the value of \fBpb\fR.
-If the entry has no padding baud rate, then
-whether padding is emitted or not is completely controlled by \fBxon\fR.
-.PP
-If the terminal requires other than a null (zero) character as a pad,
-then this can be given as \fBpad\fR.
-Only the first character of the
-.B pad
-string is used.
-.PP
-.SS Status Lines
-Some terminals have an extra \*(``status line\*('' which is not normally used by
-software (and thus not counted in the terminal's \fBlines\fR capability).
-.PP
-The simplest case is a status line which is cursor-addressable but not
-part of the main scrolling region on the screen; the Heathkit H19 has
-a status line of this kind, as would a 24-line VT100 with a 23-line
-scrolling region set up on initialization.
-This situation is indicated
-by the \fBhs\fR capability.
-.PP
-Some terminals with status lines need special sequences to access the
-status line.
-These may be expressed as a string with single parameter
-\fBtsl\fR which takes the cursor to a given zero-origin column on the
-status line.
-The capability \fBfsl\fR must return to the main-screen
-cursor positions before the last \fBtsl\fR.
-You may need to embed the
-string values of \fBsc\fR (save cursor) and \fBrc\fR (restore cursor)
-in \fBtsl\fR and \fBfsl\fR to accomplish this.
-.PP
-The status line is normally assumed to be the same width as the width
-of the terminal.
-If this is untrue, you can specify it with the numeric
-capability \fBwsl\fR.
-.PP
-A command to erase or blank the status line may be specified as \fBdsl\fR.
-.PP
-The boolean capability \fBeslok\fR specifies that escape sequences, tabs,
-etc., work ordinarily in the status line.
-.PP
-The \fBncurses\fR implementation does not yet use any of these capabilities.
-They are documented here in case they ever become important.
-.PP
-.SS Line Graphics
-.PP
-Many terminals have alternate character sets useful for forms-drawing.
-Terminfo and \fBcurses\fR build in support for the drawing characters
-supported by the VT100, with some characters from the AT&T 4410v1 added.
-This alternate character set may be specified by the \fBacsc\fR capability.
-.PP
-.TS H
-center expand;
-l l l l
-l l l l
-lw25 lw10 lw6 lw6.
-.\".TH
-\fBGlyph ACS Ascii VT100\fR
-\fBName Name Default Name\fR
-UK pound sign ACS_STERLING f }
-arrow pointing down ACS_DARROW v .
-arrow pointing left ACS_LARROW < ,
-arrow pointing right ACS_RARROW > +
-arrow pointing up ACS_UARROW ^ \-
-board of squares ACS_BOARD # h
-bullet ACS_BULLET o ~
-checker board (stipple) ACS_CKBOARD : a
-degree symbol ACS_DEGREE \e f
-diamond ACS_DIAMOND + `
-greater-than-or-equal-to ACS_GEQUAL > z
-greek pi ACS_PI * {
-horizontal line ACS_HLINE \- q
-lantern symbol ACS_LANTERN # i
-large plus or crossover ACS_PLUS + n
-less-than-or-equal-to ACS_LEQUAL < y
-lower left corner ACS_LLCORNER + m
-lower right corner ACS_LRCORNER + j
-not-equal ACS_NEQUAL ! |
-plus/minus ACS_PLMINUS # g
-scan line 1 ACS_S1 ~ o
-scan line 3 ACS_S3 \- p
-scan line 7 ACS_S7 \- r
-scan line 9 ACS_S9 \&_ s
-solid square block ACS_BLOCK # 0
-tee pointing down ACS_TTEE + w
-tee pointing left ACS_RTEE + u
-tee pointing right ACS_LTEE + t
-tee pointing up ACS_BTEE + v
-upper left corner ACS_ULCORNER + l
-upper right corner ACS_URCORNER + k
-vertical line ACS_VLINE | x
-.TE
-.PP
-The best way to define a new device's graphics set is to add a column
-to a copy of this table for your terminal, giving the character which
-(when emitted between \fBsmacs\fR/\fBrmacs\fR switches) will be rendered
-as the corresponding graphic.
-Then read off the VT100/your terminal
-character pairs right to left in sequence; these become the ACSC string.
-.PP
-.SS Color Handling
-.PP
-Most color terminals are either \*(``Tektronix-like\*('' or \*(``HP-like\*(''.
-Tektronix-like
-terminals have a predefined set of N colors (where N usually 8), and can set
-character-cell foreground and background characters independently, mixing them
-into N\ *\ N color-pairs.
-On HP-like terminals, the use must set each color
-pair up separately (foreground and background are not independently settable).
-Up to M color-pairs may be set up from 2*M different colors.
-ANSI-compatible
-terminals are Tektronix-like.
-.PP
-Some basic color capabilities are independent of the color method.
-The numeric
-capabilities \fBcolors\fR and \fBpairs\fR specify the maximum numbers of colors
-and color-pairs that can be displayed simultaneously.
-The \fBop\fR (original
-pair) string resets foreground and background colors to their default values
-for the terminal.
-The \fBoc\fR string resets all colors or color-pairs to
-their default values for the terminal.
-Some terminals (including many PC
-terminal emulators) erase screen areas with the current background color rather
-than the power-up default background; these should have the boolean capability
-\fBbce\fR.
-.PP
-To change the current foreground or background color on a Tektronix-type
-terminal, use \fBsetaf\fR (set ANSI foreground) and \fBsetab\fR (set ANSI
-background) or \fBsetf\fR (set foreground) and \fBsetb\fR (set background).
-These take one parameter, the color number.
-The SVr4 documentation describes
-only \fBsetaf\fR/\fBsetab\fR; the XPG4 draft says that "If the terminal
-supports ANSI escape sequences to set background and foreground, they should
-be coded as \fBsetaf\fR and \fBsetab\fR, respectively.
-If the terminal
-supports other escape sequences to set background and foreground, they should
-be coded as \fBsetf\fR and \fBsetb\fR, respectively.
-The \fIvidputs()\fR
-function and the refresh functions use \fBsetaf\fR and \fBsetab\fR if they are
-defined."
-.PP
-The \fBsetaf\fR/\fBsetab\fR and \fBsetf\fR/\fBsetb\fR capabilities take a
-single numeric argument each.
-Argument values 0-7 of \fBsetaf\fR/\fBsetab\fR are portably defined as
-follows (the middle column is the symbolic #define available in the header for
-the \fBcurses\fR or \fBncurses\fR libraries).
-The terminal hardware is free to
-map these as it likes, but the RGB values indicate normal locations in color
-space.
-.PP
-.TS H
-center;
-l c c c
-l l n l.
-\fBColor #define Value RGB\fR
-black \fBCOLOR_BLACK\fR 0 0, 0, 0
-red \fBCOLOR_RED\ \fR 1 max,0,0
-green \fBCOLOR_GREEN\fR 2 0,max,0
-yellow \fBCOLOR_YELLOW\fR 3 max,max,0
-blue \fBCOLOR_BLUE\fR 4 0,0,max
-magenta \fBCOLOR_MAGENTA\fR 5 max,0,max
-cyan \fBCOLOR_CYAN\fR 6 0,max,max
-white \fBCOLOR_WHITE\fR 7 max,max,max
-.TE
-.PP
-The argument values of \fBsetf\fR/\fBsetb\fR historically correspond to
-a different mapping, i.e.,
-.TS H
-center;
-l c c c
-l l n l.
-\fBColor #define Value RGB\fR
-black \fBCOLOR_BLACK\fR 0 0, 0, 0
-blue \fBCOLOR_BLUE\fR 1 0,0,max
-green \fBCOLOR_GREEN\fR 2 0,max,0
-cyan \fBCOLOR_CYAN\fR 3 0,max,max
-red \fBCOLOR_RED\ \fR 4 max,0,0
-magenta \fBCOLOR_MAGENTA\fR 5 max,0,max
-yellow \fBCOLOR_YELLOW\fR 6 max,max,0
-white \fBCOLOR_WHITE\fR 7 max,max,max
-.TE
-.PP
-It is important to not confuse the two sets of color capabilities;
-otherwise red/blue will be interchanged on the display.
-.PP
-On an HP-like terminal, use \fBscp\fR with a color-pair number parameter to set
-which color pair is current.
-.PP
-On a Tektronix-like terminal, the capability \fBccc\fR may be present to
-indicate that colors can be modified.
-If so, the \fBinitc\fR capability will
-take a color number (0 to \fBcolors\fR \- 1)and three more parameters which
-describe the color.
-These three parameters default to being interpreted as RGB
-(Red, Green, Blue) values.
-If the boolean capability \fBhls\fR is present,
-they are instead as HLS (Hue, Lightness, Saturation) indices.
-The ranges are
-terminal-dependent.
-.PP
-On an HP-like terminal, \fBinitp\fR may give a capability for changing a
-color-pair value.
-It will take seven parameters; a color-pair number (0 to
-\fBmax_pairs\fR \- 1), and two triples describing first background and then
-foreground colors.
-These parameters must be (Red, Green, Blue) or
-(Hue, Lightness, Saturation) depending on \fBhls\fR.
-.PP
-On some color terminals, colors collide with highlights.
-You can register
-these collisions with the \fBncv\fR capability.
-This is a bit-mask of
-attributes not to be used when colors are enabled.
-The correspondence with the
-attributes understood by \fBcurses\fR is as follows:
-.PP
-.TS
-center;
-l l l l
-lw20 lw2 lw10 lw10.
-\fBAttribute Bit Decimal Set by\fR
-A_STANDOUT 0 1 sgr
-A_UNDERLINE 1 2 sgr
-A_REVERSE 2 4 sgr
-A_BLINK 3 8 sgr
-A_DIM 4 16 sgr
-A_BOLD 5 32 sgr
-A_INVIS 6 64 sgr
-A_PROTECT 7 128 sgr
-A_ALTCHARSET 8 256 sgr
-A_HORIZONTAL 9 512 sgr1
-A_LEFT 10 1024 sgr1
-A_LOW 11 2048 sgr1
-A_RIGHT 12 4096 sgr1
-A_TOP 13 8192 sgr1
-A_VERTICAL 14 16384 sgr1
-A_ITALIC 15 32768 sitm
-.TE
-.PP
-For example, on many IBM PC consoles, the underline attribute collides with the
-foreground color blue and is not available in color mode.
-These should have
-an \fBncv\fR capability of 2.
-.PP
-SVr4 curses does nothing with \fBncv\fR, ncurses recognizes it and optimizes
-the output in favor of colors.
-.PP
-.SS Miscellaneous
-If the terminal requires other than a null (zero) character as a pad, then this
-can be given as pad.
-Only the first character of the pad string is used.
-If the terminal does not have a pad character, specify npc.
-Note that ncurses implements the termcap-compatible \fBPC\fR variable;
-though the application may set this value to something other than
-a null, ncurses will test \fBnpc\fR first and use napms if the terminal
-has no pad character.
-.PP
-If the terminal can move up or down half a line,
-this can be indicated with
-.B hu
-(half-line up)
-and
-.B hd
-(half-line down).
-This is primarily useful for superscripts and subscripts on hard-copy terminals.
-If a hard-copy terminal can eject to the next page (form feed), give this as
-.B ff
-(usually control L).
-.PP
-If there is a command to repeat a given character a given number of
-times (to save time transmitting a large number of identical characters)
-this can be indicated with the parameterized string
-.BR rep .
-The first parameter is the character to be repeated and the second
-is the number of times to repeat it.
-Thus, tparm(repeat_char, 'x', 10) is the same as \*(``xxxxxxxxxx\*(''.
-.PP
-If the terminal has a settable command character, such as the \s-1TEKTRONIX\s+1 4025,
-this can be indicated with
-.BR cmdch .
-A prototype command character is chosen which is used in all capabilities.
-This character is given in the
-.B cmdch
-capability to identify it.
-The following convention is supported on some UNIX systems:
-The environment is to be searched for a
-.B CC
-variable, and if found, all
-occurrences of the prototype character are replaced with the character
-in the environment variable.
-.PP
-Terminal descriptions that do not represent a specific kind of known
-terminal, such as
-.IR switch ,
-.IR dialup ,
-.IR patch ,
-and
-.IR network ,
-should include the
-.B gn
-(generic) capability so that programs can complain that they do not know
-how to talk to the terminal.
-(This capability does not apply to
-.I virtual
-terminal descriptions for which the escape sequences are known.)
-.PP
-If the terminal has a \*(``meta key\*('' which acts as a shift key,
-setting the 8th bit of any character transmitted, this fact can
-be indicated with
-.BR km .
-Otherwise, software will assume that the 8th bit is parity and it
-will usually be cleared.
-If strings exist to turn this \*(``meta mode\*('' on and off, they
-can be given as
-.B smm
-and
-.BR rmm .
-.PP
-If the terminal has more lines of memory than will fit on the screen
-at once, the number of lines of memory can be indicated with
-.BR lm .
-A value of
-.BR lm #0
-indicates that the number of lines is not fixed,
-but that there is still more memory than fits on the screen.
-.PP
-If the terminal is one of those supported by the \s-1UNIX\s+1 virtual
-terminal protocol, the terminal number can be given as
-.BR vt .
-.PP
-Media copy
-strings which control an auxiliary printer connected to the terminal
-can be given as
-.BR mc0 :
-print the contents of the screen,
-.BR mc4 :
-turn off the printer, and
-.BR mc5 :
-turn on the printer.
-When the printer is on, all text sent to the terminal will be sent
-to the printer.
-It is undefined whether the text is also displayed on the terminal screen
-when the printer is on.
-A variation
-.B mc5p
-takes one parameter, and leaves the printer on for as many characters
-as the value of the parameter, then turns the printer off.
-The parameter should not exceed 255.
-All text, including
-.BR mc4 ,
-is transparently passed to the printer while an
-.B mc5p
-is in effect.
-.PP
-.SS Glitches and Braindamage
-.PP
-Hazeltine terminals, which do not allow \*(``~\*('' characters to be displayed should
-indicate \fBhz\fR.
-.PP
-Terminals which ignore a line-feed immediately after an \fBam\fR wrap,
-such as the Concept and vt100,
-should indicate \fBxenl\fR.
-.PP
-If
-.B el
-is required to get rid of standout
-(instead of merely writing normal text on top of it),
-\fBxhp\fP should be given.
-.PP
-Teleray terminals, where tabs turn all characters moved over to blanks,
-should indicate \fBxt\fR (destructive tabs).
-Note: the variable indicating this is now \*(``dest_tabs_magic_smso\*(''; in
-older versions, it was teleray_glitch.
-This glitch is also taken to mean that it is not possible to position
-the cursor on top of a \*(``magic cookie\*('',
-that to erase standout mode it is instead necessary to use
-delete and insert line.
-The ncurses implementation ignores this glitch.
-.PP
-The Beehive Superbee, which is unable to correctly transmit the escape
-or control C characters, has
-.BR xsb ,
-indicating that the f1 key is used for escape and f2 for control C.
-(Only certain Superbees have this problem, depending on the ROM.)
-Note that in older terminfo versions, this capability was called
-\*(``beehive_glitch\*(''; it is now \*(``no_esc_ctl_c\*(''.
-.PP
-Other specific terminal problems may be corrected by adding more
-capabilities of the form \fBx\fR\fIx\fR.
-.PP
-.SS Similar Terminals
-.PP
-If there are two very similar terminals, one (the variant) can be defined as
-being just like the other (the base) with certain exceptions.
-In the
-definition of the variant, the string capability \fBuse\fR can be given with
-the name of the base terminal.
-The capabilities given before
-.B use
-override those in the base type named by
-.BR use .
-If there are multiple \fBuse\fR capabilities, they are merged in reverse order.
-That is, the rightmost \fBuse\fR reference is processed first, then the one to
-its left, and so forth.
-Capabilities given explicitly in the entry override
-those brought in by \fBuse\fR references.
-.PP
-A capability can be canceled by placing \fBxx@\fR to the left of the
-use reference that imports it, where \fIxx\fP is the capability.
-For example, the entry
-.RS
-.PP
-2621\-nl, smkx@, rmkx@, use=2621,
-.RE
-.PP
-defines a 2621\-nl that does not have the \fBsmkx\fR or \fBrmkx\fR capabilities,
-and hence does not turn on the function key labels when in visual mode.
-This is useful for different modes for a terminal, or for different
-user preferences.
-.PP
-.SS Pitfalls of Long Entries
-.PP
-Long terminfo entries are unlikely to be a problem; to date, no entry has even
-approached terminfo's 4096-byte string-table maximum.
-Unfortunately, the termcap
-translations are much more strictly limited (to 1023 bytes), thus termcap translations
-of long terminfo entries can cause problems.
-.PP
-The man pages for 4.3BSD and older versions of \fBtgetent()\fP instruct the user to
-allocate a 1024-byte buffer for the termcap entry.
-The entry gets null-terminated by
-the termcap library, so that makes the maximum safe length for a termcap entry
-1k\-1 (1023) bytes.
-Depending on what the application and the termcap library
-being used does, and where in the termcap file the terminal type that \fBtgetent()\fP
-is searching for is, several bad things can happen.
-.PP
-Some termcap libraries print a warning message or exit if they find an
-entry that's longer than 1023 bytes; others do not; others truncate the
-entries to 1023 bytes.
-Some application programs allocate more than
-the recommended 1K for the termcap entry; others do not.
-.PP
-Each termcap entry has two important sizes associated with it: before
-"tc" expansion, and after "tc" expansion.
-"tc" is the capability that
-tacks on another termcap entry to the end of the current one, to add
-on its capabilities.
-If a termcap entry does not use the "tc"
-capability, then of course the two lengths are the same.
-.PP
-The "before tc expansion" length is the most important one, because it
-affects more than just users of that particular terminal.
-This is the
-length of the entry as it exists in /etc/termcap, minus the
-backslash-newline pairs, which \fBtgetent()\fP strips out while reading it.
-Some termcap libraries strip off the final newline, too (GNU termcap does not).
-Now suppose:
-.bP
-a termcap entry before expansion is more than 1023 bytes long,
-.bP
-and the application has only allocated a 1k buffer,
-.bP
-and the termcap library (like the one in BSD/OS 1.1 and GNU) reads
-the whole entry into the buffer, no matter what its length, to see
-if it is the entry it wants,
-.bP
-and \fBtgetent()\fP is searching for a terminal type that either is the
-long entry, appears in the termcap file after the long entry, or
-does not appear in the file at all (so that \fBtgetent()\fP has to search
-the whole termcap file).
-.PP
-Then \fBtgetent()\fP will overwrite memory, perhaps its stack, and probably core dump
-the program.
-Programs like telnet are particularly vulnerable; modern telnets
-pass along values like the terminal type automatically.
-The results are almost
-as undesirable with a termcap library, like SunOS 4.1.3 and Ultrix 4.4, that
-prints warning messages when it reads an overly long termcap entry.
-If a
-termcap library truncates long entries, like OSF/1 3.0, it is immune to dying
-here but will return incorrect data for the terminal.
-.PP
-The "after tc expansion" length will have a similar effect to the
-above, but only for people who actually set TERM to that terminal
-type, since \fBtgetent()\fP only does "tc" expansion once it is found the
-terminal type it was looking for, not while searching.
-.PP
-In summary, a termcap entry that is longer than 1023 bytes can cause,
-on various combinations of termcap libraries and applications, a core
-dump, warnings, or incorrect operation.
-If it is too long even before
-"tc" expansion, it will have this effect even for users of some other
-terminal types and users whose TERM variable does not have a termcap
-entry.
-.PP
-When in \-C (translate to termcap) mode, the \fBncurses\fR implementation of
-\fB@TIC@\fR(1M) issues warning messages when the pre-tc length of a termcap
-translation is too long.
-The \-c (check) option also checks resolved (after tc
-expansion) lengths.
-.SS Binary Compatibility
-It is not wise to count on portability of binary terminfo entries between
-commercial UNIX versions.
-The problem is that there are at least two versions
-of terminfo (under HP\-UX and AIX) which diverged from System V terminfo after
-SVr1, and have added extension capabilities to the string table that (in the
-binary format) collide with System V and XSI Curses extensions.
-.SH EXTENSIONS
-.PP
-Searching for terminal descriptions in
-\fB$HOME/.terminfo\fR and TERMINFO_DIRS
-is not supported by older implementations.
-.PP
-Some SVr4 \fBcurses\fR implementations, and all previous to SVr4, do not
-interpret the %A and %O operators in parameter strings.
-.PP
-SVr4/XPG4 do not specify whether \fBmsgr\fR licenses movement while in
-an alternate-character-set mode (such modes may, among other things, map
-CR and NL to characters that do not trigger local motions).
-The \fBncurses\fR implementation ignores \fBmsgr\fR in \fBALTCHARSET\fR
-mode.
-This raises the possibility that an XPG4
-implementation making the opposite interpretation may need terminfo
-entries made for \fBncurses\fR to have \fBmsgr\fR turned off.
-.PP
-The \fBncurses\fR library handles insert-character and insert-character modes
-in a slightly non-standard way to get better update efficiency.
-See
-the \fBInsert/Delete Character\fR subsection above.
-.PP
-The parameter substitutions for \fBset_clock\fR and \fBdisplay_clock\fR are
-not documented in SVr4 or the XSI Curses standard.
-They are deduced from the
-documentation for the AT&T 505 terminal.
-.PP
-Be careful assigning the \fBkmous\fR capability.
-The \fBncurses\fR wants to
-interpret it as \fBKEY_MOUSE\fR, for use by terminals and emulators like xterm
-that can return mouse-tracking information in the keyboard-input stream.
-.PP
-X/Open Curses does not mention italics.
-Portable applications must assume that numeric capabilities are
-signed 16-bit values.
-This includes the \fIno_color_video\fP (ncv) capability.
-The 32768 mask value used for italics with ncv can be confused with
-an absent or cancelled ncv.
-If italics should work with colors,
-then the ncv value must be specified, even if it is zero.
-.PP
-Different commercial ports of terminfo and curses support different subsets of
-the XSI Curses standard and (in some cases) different extension sets.
-Here
-is a summary, accurate as of October 1995:
-.PP
-\fBSVR4, Solaris, ncurses\fR \-\-
-These support all SVr4 capabilities.
-.PP
-\fBSGI\fR \-\-
-Supports the SVr4 set, adds one undocumented extended string
-capability (\fBset_pglen\fR).
-.PP
-\fBSVr1, Ultrix\fR \-\-
-These support a restricted subset of terminfo capabilities.
-The booleans end with \fBxon_xoff\fR;
-the numerics with \fBwidth_status_line\fR;
-and the strings with \fBprtr_non\fR.
-.PP
-\fBHP/UX\fR \-\-
-Supports the SVr1 subset, plus the SVr[234] numerics \fBnum_labels\fR,
-\fBlabel_height\fR, \fBlabel_width\fR, plus function keys 11 through 63, plus
-\fBplab_norm\fR, \fBlabel_on\fR, and \fBlabel_off\fR, plus some incompatible
-extensions in the string table.
-.PP
-\fBAIX\fR \-\-
-Supports the SVr1 subset, plus function keys 11 through 63, plus a number
-of incompatible string table extensions.
-.PP
-\fBOSF\fR \-\-
-Supports both the SVr4 set and the AIX extensions.
-.SH FILES
-.TP 25
-\*d/?/*
-files containing terminal descriptions
-.SH SEE ALSO
-\fB@TIC@\fR(1M),
-\fB@INFOCMP@\fR(1M),
-\fBcurses\fR(3X),
-\fBprintf\fR(3),
-\fBterm\fR(\*n).
-\fBterm_variables\fR(3X).
-.SH AUTHORS
-Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
-Based on pcurses by Pavel Curtis.
diff --git a/man/terminfo.head b/man/terminfo.head
index c4cc072..717f849 100644
--- a/man/terminfo.head
+++ b/man/terminfo.head
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2012,2013 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -26,58 +27,105 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: terminfo.head,v 1.21 2013/03/09 22:11:36 tom Exp $
-.TH terminfo 5 "" "" "File Formats"
-.ds n 5
-.ds d @TERMINFO@
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: terminfo.head,v 1.65 2024/04/20 21:14:00 tom Exp $
+.TH terminfo 5 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.ds ' \(aq
+.ds ^ \(ha
+.ds ~ \(ti
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.ds ' '
+.ds ^ ^
+.ds ~ ~
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
+.
+.ds d @TERMINFO@
.SH NAME
-terminfo \- terminal capability data base
+\fB\%terminfo\fP \-
+terminal capability database
.SH SYNOPSIS
\*d/*/*
.SH DESCRIPTION
.I Terminfo
-is a data base describing terminals, used by screen-oriented programs such as
-\fBnvi\fR(1),
-\fBrogue\fR(1)
-and libraries such as
-\fBcurses\fR(3X).
+is a database describing terminals,
+used by screen-oriented programs such as
+\fBnvi\fP(1),
+\fBlynx\fP(1),
+\fBmutt\fP(1),
+and other curses applications,
+using high-level calls to libraries such as \fBcurses\fP(3X).
+It is also used via low-level calls by non-curses applications
+which may be screen-oriented (such as \fB@CLEAR@\fP(1))
+or non-screen (such as \fB@TABS@\fP(1)).
+.PP
.I Terminfo
describes terminals by giving a set of capabilities which they
have, by specifying how to perform screen operations, and by
specifying padding requirements and initialization sequences.
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.PP
+This document describes
+.I \%ncurses
+version @NCURSES_MAJOR@.@NCURSES_MINOR@
+(patch @NCURSES_PATCH@).
+.SS "\fIterminfo\fP Entry Syntax"
Entries in
.I terminfo
-consist of a sequence of `,' separated fields (embedded commas may be
-escaped with a backslash or notated as \\054).
-White space after the `,' separator is ignored.
-The first entry for each terminal gives the names which are known for the
-terminal, separated by `|' characters.
-The first name given is the most common abbreviation for the terminal,
-the last name given should be a long name fully identifying the terminal,
-and all others are understood as synonyms for the terminal name.
-All names but the last should be in lower case and contain no blanks;
+consist of a sequence of fields:
+.bP
+Each field ends with a comma \*(``,\*(''
+(embedded commas may be
+escaped with a backslash or written as \*(``\e054\*('').
+.bP
+White space between fields is ignored.
+.bP
+The first field in a \fIterminfo\fP entry begins in the first column.
+.bP
+Newlines and leading whitespace (spaces or tabs)
+may be used for formatting entries for readability.
+These are removed from parsed entries.
+.IP
+The \fB@INFOCMP@\fP \fB\-f\fP and \fB\-W\fP options rely on this to
+format if-then-else expressions,
+or to enforce maximum line-width.
+The resulting formatted terminal description can be read by \fB@TIC@\fP.
+.bP
+The first field for each terminal gives the names which are known for the
+terminal, separated by \*(``|\*('' characters.
+.IP
+The first name given is the most common abbreviation for the terminal
+(its primary name),
+the last name given should be a long name fully identifying the terminal
+(see \fBlongname\fP(3X)),
+and all others are treated as synonyms (aliases) for the primary terminal name.
+.IP
+X/Open Curses advises that all names but the last should be in lower case
+and contain no blanks;
the last name may well contain upper case and blanks for readability.
-.PP
-Lines beginning with a `#' in the first column are treated as comments.
-While comment lines are legal at any point, the output of \fB@CAPTOINFO@\fP
+.IP
+This implementation is not so strict;
+it allows mixed case in the primary name and aliases.
+If the last name has no embedded blanks,
+it allows that to be both an alias and a verbose name
+(but will warn about this ambiguity).
+.bP
+Lines beginning with a \*(``#\*('' in the first column are treated as comments.
+.IP
+While comment lines are valid at any point, the output of \fB@CAPTOINFO@\fP
and \fB@INFOTOCAP@\fP (aliases for \fB@TIC@\fP)
will move comments so they occur only between entries.
.PP
-Newlines and leading tabs may be used for formatting entries for readability.
-These are removed from parsed entries.
-The \fB@INFOCMP@\ \-f\fP option relies on this to format if-then-else expressions:
-the result can be read by \fB@TIC@\fP.
-.PP
Terminal names (except for the last, verbose entry) should
be chosen using the following conventions.
The particular piece of hardware making up the terminal should
@@ -85,30 +133,95 @@
This name should not contain hyphens.
Modes that the hardware can be in, or user preferences, should
be indicated by appending a hyphen and a mode suffix.
-Thus, a vt100 in 132 column mode would be vt100\-w.
+Thus, a vt100 in 132-column mode would be vt100\-w.
The following suffixes should be used where possible:
.PP
.TS
-center ;
-l c l
-l l l.
-\fBSuffix Meaning Example\fP
-\-\fInn\fP Number of lines on the screen aaa\-60
-\-\fIn\fPp Number of pages of memory c100\-4p
-\-am With automargins (usually the default) vt100\-am
-\-m Mono mode; suppress color ansi\-m
-\-mc Magic cookie; spaces when highlighting wy30\-mc
-\-na No arrow keys (leave them in local) c100\-na
-\-nam Without automatic margins vt100\-nam
-\-nl No status line att4415\-nl
-\-ns No status line hp2626\-ns
-\-rv Reverse video c100\-rv
-\-s Enable status line vt100\-s
-\-vb Use visible bell instead of beep wy370\-vb
-\-w Wide mode (> 80 columns, usually 132) vt100\-w
+center;
+Lb Lb Lb
+L L Lx.
+Suffix Example Meaning
+_
+\-\fInn\fP aaa\-60 Number of lines on the screen
+\-\fIn\fPp c100\-4p Number of pages of memory
+\-am vt100\-am With automargins (usually the default)
+\-m ansi\-m Mono mode; suppress color
+\-mc wy30\-mc Magic cookie; spaces when highlighting
+\-na c100\-na No arrow keys (leave them in local)
+\-nam vt100\-nam Without automatic margins
+\-nl hp2621\-nl No status line
+\-ns hp2626\-ns No status line
+\-rv c100\-rv Reverse video
+\-s vt100\-s Enable status line
+\-vb wy370\-vb Use visible bell instead of beep
+\-w vt100\-w Wide mode (> 80 columns, usually 132)
.TE
.PP
-For more on terminal naming conventions, see the \fBterm(7)\fR manual page.
-.SS Predefined Capabilities
+For more on terminal naming conventions, see the \fBterm\fP(7) manual page.
+.SS "\fIterminfo\fP Capabilities Syntax"
+The terminfo entry consists of several \fIcapabilities\fP,
+i.e., features that the terminal has,
+or methods for exercising the terminal's features.
+.PP
+After the first field (giving the name(s) of the terminal entry),
+there should be one or more \fIcapability\fP fields.
+These are Boolean, numeric or string names with corresponding values:
+.bP
+Boolean capabilities are true when present, false when absent.
+There is no explicit value for Boolean capabilities.
+.bP
+Numeric capabilities have a \*(``#\*('' following the name,
+then an unsigned decimal integer value.
+.bP
+String capabilities have a \*(``=\*('' following the name,
+then an string of characters making up the capability value.
+.IP
+String capabilities can be split into multiple lines,
+just as the fields comprising a terminal entry can be
+split into multiple lines.
+While blanks between fields are ignored,
+blanks embedded within a string value are retained,
+except for leading blanks on a line.
+.PP
+Any capability can be \fIcanceled\fP,
+i.e., suppressed from the terminal entry,
+by following its name with \*(``@\*(''
+rather than a capability value.
+.SS "Similar Terminals"
+If there are two very similar terminals, one (the variant) can be defined as
+being just like the other (the base) with certain exceptions.
+In the
+definition of the variant, the string capability \fBuse\fP can be given with
+the name of the base terminal:
+.bP
+The capabilities given before
+.B use
+override those in the base type named by
+.BR use .
+.bP
+If there are multiple \fBuse\fP capabilities, they are merged in reverse order.
+That is, the rightmost \fBuse\fP reference is processed first, then the one to
+its left, and so forth.
+.bP
+Capabilities given explicitly in the entry override
+those brought in by \fBuse\fP references.
+.PP
+A capability can be canceled by placing \fBxx@\fP to the left of the
+use reference that imports it, where \fIxx\fP is the capability.
+For example, the entry
+.RS
+.PP
+2621\-nl, smkx@, rmkx@, use=2621,
+.RE
+.PP
+defines a 2621\-nl that does not have the \fBsmkx\fP or \fBrmkx\fP capabilities,
+and hence does not turn on the function key labels when in visual mode.
+This is useful for different modes for a terminal, or for different
+user preferences.
+.PP
+An entry included via \fBuse\fP can contain canceled capabilities,
+which have the same effect as if those cancels were inline in the
+using terminal entry.
+.SS "Predefined Capabilities"
.\" Head of terminfo man page ends here
.ps -1
diff --git a/man/terminfo.tail b/man/terminfo.tail
index bd8568f..4d6daa3 100644
--- a/man/terminfo.tail
+++ b/man/terminfo.tail
@@ -1,9 +1,35 @@
-.\" $Id: terminfo.tail,v 1.69 2015/04/26 14:47:23 tom Exp $
-.\" Beginning of terminfo.tail file
-.\" This file is part of ncurses.
-.\" See "terminfo.head" for copyright.
+.\"***************************************************************************
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
+.\" "Software"), to deal in the Software without restriction, including *
+.\" without limitation the rights to use, copy, modify, merge, publish, *
+.\" distribute, distribute with modifications, sublicense, and/or sell *
+.\" copies of the Software, and to permit persons to whom the Software is *
+.\" furnished to do so, subject to the following conditions: *
+.\" *
+.\" The above copyright notice and this permission notice shall be included *
+.\" in all copies or substantial portions of the Software. *
+.\" *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
+.\" *
+.\" Except as contained in this notice, the name(s) of the above copyright *
+.\" holders shall not be used in advertising or otherwise to promote the *
+.\" sale, use or other dealings in this Software without prior written *
+.\" authorization. *
+.\"***************************************************************************
+.\"
+.\" $Id: terminfo.tail,v 1.148 2024/04/20 21:24:19 tom Exp $
.ps +1
-.SS User-Defined Capabilities
+.SS "User-Defined Capabilities"
.
The preceding section listed the \fIpredefined\fP capabilities.
They deal with some special features for terminals no longer
@@ -12,24 +38,25 @@
are awkward or impossible to represent by reusing the predefined
capabilities.
.PP
-\fBncurses\fP addresses this limitation by allowing user-defined capabilities.
+\fI\%ncurses\fP addresses this limitation by allowing user-defined
+capabilities.
The \fB@TIC@\fP and \fB@INFOCMP@\fP programs provide
the \fB\-x\fP option for this purpose.
When \fB\-x\fP is set,
\fB@TIC@\fP treats unknown capabilities as user-defined.
That is, if \fB@TIC@\fP encounters a capability name
which it does not recognize,
-it infers its type (boolean, number or string) from the syntax
+it infers its type (Boolean, number or string) from the syntax
and makes an extended table entry for that capability.
-The \fBuse_extended_names\fP function makes this information
+The \fBuse_extended_names\fP(3X) function makes this information
conditionally available to applications.
-The ncurses library provides the data leaving most of the behavior
-to applications:
+The \fI\%ncurses\fP library provides the data leaving most of the
+behavior to applications:
.bP
User-defined capability strings whose name begins
with \*(``k\*('' are treated as function keys.
.bP
-The types (boolean, number, string) determined by \fB@TIC@\fP
+The types (Boolean, number, string) determined by \fB@TIC@\fP
can be inferred by successful calls on \fBtigetflag\fP, etc.
.bP
If the capability name happens to be two characters,
@@ -41,51 +68,56 @@
terminfo implementations.
As a rule,
user-defined capabilities intended for use by termcap applications should
-be limited to booleans and numbers to avoid running past the 1023 byte
+be limited to Booleans and numbers to avoid running past the 1023 byte
limit assumed by termcap implementations and their applications.
In particular, providing extended sets of function keys (past the 60
numbered keys and the handful of special named keys) is best done using
the longer names available using terminfo.
+.PP
+The \fI\%ncurses\fP library uses a few of these user-defined
+capabilities,
+as described in \fBuser_caps\fR(5).
+Other user-defined capabilities (including function keys) are
+described in the terminal database, in the section on
+.I "NCURSES USER-DEFINABLE CAPABILITIES"
.
-.SS A Sample Entry
+.SS "A Sample Entry"
.
The following entry, describing an ANSI-standard terminal, is representative
-of what a \fBterminfo\fR entry for a modern terminal typically looks like.
+of what a \fBterminfo\fP entry for a modern terminal typically looks like.
.PP
-.nf
-.ft CW
-\s-2ansi|ansi/pc-term compatible with color,
+.EX
+\s-2ansi|ansi/pc\-term compatible with color,
am, mc5i, mir, msgr,
colors#8, cols#80, it#8, lines#24, ncv#3, pairs#64,
- acsc=+\\020\\,\\021-\\030.^Y0\\333`\\004a\\261f\\370g\\361h\\260
- j\\331k\\277l\\332m\\300n\\305o~p\\304q\\304r\\304s_t\\303
- u\\264v\\301w\\302x\\263y\\363z\\362{\\343|\\330}\\234~\\376,
- bel=^G, blink=\\E[5m, bold=\\E[1m, cbt=\\E[Z, clear=\\E[H\\E[J,
- cr=^M, cub=\\E[%p1%dD, cub1=\\E[D, cud=\\E[%p1%dB, cud1=\\E[B,
- cuf=\\E[%p1%dC, cuf1=\\E[C, cup=\\E[%i%p1%d;%p2%dH,
- cuu=\\E[%p1%dA, cuu1=\\E[A, dch=\\E[%p1%dP, dch1=\\E[P,
- dl=\\E[%p1%dM, dl1=\\E[M, ech=\\E[%p1%dX, ed=\\E[J, el=\\E[K,
- el1=\\E[1K, home=\\E[H, hpa=\\E[%i%p1%dG, ht=\\E[I, hts=\\EH,
- ich=\\E[%p1%d@, il=\\E[%p1%dL, il1=\\E[L, ind=^J,
- indn=\\E[%p1%dS, invis=\\E[8m, kbs=^H, kcbt=\\E[Z, kcub1=\\E[D,
- kcud1=\\E[B, kcuf1=\\E[C, kcuu1=\\E[A, khome=\\E[H, kich1=\\E[L,
- mc4=\\E[4i, mc5=\\E[5i, nel=\\r\\E[S, op=\\E[39;49m,
- rep=%p1%c\\E[%p2%{1}%-%db, rev=\\E[7m, rin=\\E[%p1%dT,
- rmacs=\\E[10m, rmpch=\\E[10m, rmso=\\E[m, rmul=\\E[m,
- s0ds=\\E(B, s1ds=\\E)B, s2ds=\\E*B, s3ds=\\E+B,
- setab=\\E[4%p1%dm, setaf=\\E[3%p1%dm,
- sgr=\\E[0;10%?%p1%t;7%;
+ acsc=+\e020\e,\e021\-\e030.\*^Y0\e333\(ga\e004a\e261f\e370g\e361h\e260
+ j\e331k\e277l\e332m\e300n\e305o\*~p\e304q\e304r\e304s_t\e303
+ u\e264v\e301w\e302x\e263y\e363z\e362{\e343|\e330}\e234\*~\e376,
+ bel=\*^G, blink=\eE[5m, bold=\eE[1m, cbt=\eE[Z, clear=\eE[H\eE[J,
+ cr=\*^M, cub=\eE[%p1%dD, cub1=\eE[D, cud=\eE[%p1%dB, cud1=\eE[B,
+ cuf=\eE[%p1%dC, cuf1=\eE[C, cup=\eE[%i%p1%d;%p2%dH,
+ cuu=\eE[%p1%dA, cuu1=\eE[A, dch=\eE[%p1%dP, dch1=\eE[P,
+ dl=\eE[%p1%dM, dl1=\eE[M, ech=\eE[%p1%dX, ed=\eE[J, el=\eE[K,
+ el1=\eE[1K, home=\eE[H, hpa=\eE[%i%p1%dG, ht=\eE[I, hts=\eEH,
+ ich=\eE[%p1%d@, il=\eE[%p1%dL, il1=\eE[L, ind=\*^J,
+ indn=\eE[%p1%dS, invis=\eE[8m, kbs=\*^H, kcbt=\eE[Z, kcub1=\eE[D,
+ kcud1=\eE[B, kcuf1=\eE[C, kcuu1=\eE[A, khome=\eE[H, kich1=\eE[L,
+ mc4=\eE[4i, mc5=\eE[5i, nel=\er\eE[S, op=\eE[39;49m,
+ rep=%p1%c\eE[%p2%{1}%\-%db, rev=\eE[7m, rin=\eE[%p1%dT,
+ rmacs=\eE[10m, rmpch=\eE[10m, rmso=\eE[m, rmul=\eE[m,
+ s0ds=\eE(B, s1ds=\eE)B, s2ds=\eE*B, s3ds=\eE+B,
+ setab=\eE[4%p1%dm, setaf=\eE[3%p1%dm,
+ sgr=\eE[0;10%?%p1%t;7%;
%?%p2%t;4%;
%?%p3%t;7%;
%?%p4%t;5%;
%?%p6%t;1%;
%?%p7%t;8%;
%?%p9%t;11%;m,
- sgr0=\\E[0;10m, smacs=\\E[11m, smpch=\\E[11m, smso=\\E[7m,
- smul=\\E[4m, tbc=\\E[3g, u6=\\E[%i%d;%dR, u7=\\E[6n,
- u8=\\E[?%[;0123456789]c, u9=\\E[c, vpa=\\E[%i%p1%dd,
-.fi
-.ft R
+ sgr0=\eE[0;10m, smacs=\eE[11m, smpch=\eE[11m, smso=\eE[7m,
+ smul=\eE[4m, tbc=\eE[3g, u6=\eE[%i%d;%dR, u7=\eE[6n,
+ u8=\eE[?%[;0123456789]c, u9=\eE[c, vpa=\eE[%i%p1%dd,
+.EE
.PP
Entries may continue onto multiple lines by placing white space at
the beginning of each line except the first.
@@ -103,76 +135,107 @@
string
capabilities, which give a sequence which can be used to perform particular
terminal operations.
-.PP
-.SS Types of Capabilities
-.PP
+.SS "Types of Capabilities"
All capabilities have names.
For instance, the fact that
ANSI-standard terminals have
.I "automatic margins"
(i.e., an automatic return and line-feed
-when the end of a line is reached) is indicated by the capability \fBam\fR.
-Hence the description of ansi includes \fBam\fR.
-Numeric capabilities are followed by the character \*(``#\*('' and then a positive value.
-Thus \fBcols\fR, which indicates the number of columns the terminal has,
+when the end of a line is reached) is indicated by the capability \fBam\fP.
+Hence the description of ansi includes \fBam\fP.
+Numeric capabilities are followed by the character \*(``#\*(''
+and then a positive value.
+Thus \fBcols\fP, which indicates the number of columns the terminal has,
gives the value \*(``80\*('' for ansi.
-Values for numeric capabilities may be specified in decimal, octal or hexadecimal,
-using the C programming language conventions (e.g., 255, 0377 and 0xff or 0xFF).
+Values for numeric capabilities may be specified in
+decimal,
+octal, or
+hexadecimal,
+using the C programming language conventions
+(e.g., 255, 0377 and 0xff or 0xFF).
.PP
-Finally, string valued capabilities, such as \fBel\fR (clear to end of line
-sequence) are given by the two-character code, an \*(``=\*('', and then a string
-ending at the next following \*(``,\*(''.
+Finally, string valued capabilities,
+such as \fBel\fP (clear to end of line sequence)
+are given by the two-character code,
+an \*(``=\*('', and then
+a string ending at the next following \*(``,\*(''.
.PP
A number of escape sequences are provided in the string valued capabilities
-for easy encoding of characters there.
-Both \fB\eE\fR and \fB\ee\fR
+for easy encoding of characters there:
+.bP
+Both \fB\eE\fP and \fB\ee\fP
map to an \s-1ESCAPE\s0 character,
-\fB^x\fR maps to a control-x for any appropriate x, and the sequences
-\fB\en \el \er \et \eb \ef \es\fR give
-a newline, line-feed, return, tab, backspace, form-feed, and space.
+.bP
+\fB\*^\f(BIx\fR maps to a control-\fIx\fP for any appropriate \fIx\fP,
+and
+.bP
+the sequences
+.RS 6
+.PP
+\fB\en\fP, \fB\el\fP, \fB\er\fP, \fB\et\fP, \fB\eb\fP, \fB\ef\fP, and \fB\es\fP
+.RE
+.IP
+produce
+.RS 6
+.PP
+\fInewline\fP, \fIline-feed\fP, \fIreturn\fP, \fItab\fP, \fIbackspace\fP, \fIform-feed\fP, and \fIspace\fP,
+.RE
+.IP
+respectively.
+.PP
+X/Open Curses does not say what \*(``appropriate \fIx\fP\*('' might be.
+In practice, that is a printable ASCII graphic character.
+The special case \*(``\*^?\*('' is interpreted as DEL (127).
+In all other cases, the character value is AND'd with 0x1f,
+mapping to ASCII control codes in the range 0 through 31.
+.PP
Other escapes include
.bP
-\fB\e^\fR for \fB^\fR,
+\fB\e\*^\fP for \fB\*^\fP,
.bP
-\fB\e\e\fR for \fB\e\fR,
+\fB\e\e\fP for \fB\e\fP,
.bP
-\fB\e\fR, for comma,
+\fB\e\fP, for comma,
.bP
-\fB\e:\fR for \fB:\fR,
+\fB\e:\fP for \fB:\fP,
.bP
-and \fB\e0\fR for null.
+and \fB\e0\fP for null.
.IP
-\fB\e0\fR will produce \e200, which does not terminate a string but behaves
+\fB\e0\fP will produce \e200, which does not terminate a string but behaves
as a null character on most terminals, providing CS7 is specified.
-See stty(1).
+See \fBstty\fP(1).
.IP
The reason for this quirk is to maintain binary compatibility of the
compiled terminfo files with other implementations,
e.g., the SVr4 systems, which document this.
Compiled terminfo files use null-terminated strings, with no lengths.
-Modifying this would require a new binary format,
+Modifying this would require a new binary format,
which would not work with other implementations.
.PP
-Finally, characters may be given as three octal digits after a \fB\e\fR.
+Finally, characters may be given as three octal digits after a \fB\e\fP.
.PP
A delay in milliseconds may appear anywhere in a string capability, enclosed in
-$<..> brackets, as in \fBel\fP=\eEK$<5>, and padding characters are supplied by
-.I tputs
+$<..> brackets, as in \fBel\fP=\eEK$<5>,
+and padding characters are supplied by \fBtputs\fP(3X)
to provide this delay.
+.bP
The delay must be a number with at most one decimal
-place of precision; it may be followed by suffixes \*(``*\*('' or \*(``/\*('' or both.
+place of precision;
+it may be followed by suffixes \*(``*\*('' or \*(``/\*('' or both.
+.bP
A \*(``*\*(''
indicates that the padding required is proportional to the number of lines
affected by the operation, and the amount given is the per-affected-unit
padding required.
(In the case of insert character, the factor is still the
-number of
-.IR lines
-affected.) Normally, padding is advisory if the device has the \fBxon\fR
+number of \fIlines\fP affected.)
+.IP
+Normally, padding is advisory if the device has the \fBxon\fP
capability; it is used for cost computation but does not trigger delays.
+.bP
A \*(``/\*(''
suffix indicates that the padding is mandatory and forces a delay of the given
-number of milliseconds even on devices for which \fBxon\fR is present to
+number of milliseconds even on devices for which \fBxon\fP is present to
indicate flow control.
.PP
Sometimes individual capabilities must be commented out.
@@ -182,41 +245,68 @@
in the example above.
.br
.ne 5
+.SS "Fetching Compiled Descriptions"
+Terminal descriptions in \fI\%ncurses\fP are stored in terminal
+databases.
+These databases, which are found by their pathname,
+may be configured either as directory trees or hashed databases
+(see \fBterm\fR(5)),
.PP
-.SS Fetching Compiled Descriptions
-.PP
-The \fBncurses\fP library searches for terminal descriptions in several places.
-It uses only the first description found.
-The library has a compiled-in list of places to search
+The library uses a compiled-in list of pathnames,
which can be overridden by environment variables.
Before starting to search,
-\fBncurses\fP eliminates duplicates in its search list.
+\fI\%ncurses\fP checks the search list,
+eliminating duplicates and pathnames where no terminal database is found.
+The \fI\%ncurses\fP library reads the first description
+which passes its consistency checks.
.bP
-If the environment variable TERMINFO is set, it is interpreted as the pathname
-of a directory containing the compiled description you are working on.
-Only that directory is searched.
+The environment variable \fBTERMINFO\fR is checked first, for
+a terminal database containing the terminal description.
.bP
-If TERMINFO is not set,
-\fBncurses\fR will instead look in the directory \fB$HOME/.terminfo\fR
+Next,
+\fI\%ncurses\fP looks in \fI$HOME/.terminfo\fP
for a compiled description.
-.bP
-Next, if the environment variable TERMINFO_DIRS is set,
-\fBncurses\fR will interpret the contents of that variable
-as a list of colon-separated directories (or database files) to be searched.
.IP
-An empty directory name (i.e., if the variable begins or ends
-with a colon, or contains adjacent colons)
-is interpreted as the system location \fI\*d\fR.
+This is an optional feature which may be omitted entirely from
+the library, or limited to prevent accidental use by privileged applications.
.bP
-Finally, \fBncurses\fP searches these compiled-in locations:
+Next,
+if the environment variable \fI\%TERMINFO_DIRS\fP is set,
+\fI\%ncurses\fP interprets the contents of that variable
+as a list of colon-separated pathnames of terminal databases to be searched.
+.IP
+An empty pathname (i.e., if the variable begins or ends
+with a colon, or contains adjacent colons)
+is interpreted as the system location \fI\*d\fP.
+.bP
+Finally, \fI\%ncurses\fP searches these compiled-in locations:
.RS
.bP
a list of directories (@TERMINFO_DIRS@), and
.bP
-the system terminfo directory, \fI\*d\fR (the compiled-in default).
+the system terminfo directory, \fI\*d\fP
.RE
-.SS Preparing Descriptions
.PP
+The \fBTERMINFO\fP variable can contain a terminal description instead
+of the pathname of a terminal database.
+If this variable begins with \*(``hex:\*('' or \*(``b64:\*(''
+then \fI\%ncurses\fP reads a terminal description from
+hexadecimal- or base64-encoded data,
+and if that description matches the name sought, will use that.
+This encoded data can be set using the \*(``\-Q\*('' option of
+\fB@TIC@\fR or \fB@INFOCMP@\fR.
+.PP
+The preceding addresses the usual configuration of \fI\%ncurses\fP,
+which uses terminal descriptions prepared in \fIterminfo\fP format.
+While \fItermcap\fP is less expressive,
+\fI\%ncurses\fP can also be configured to read \fItermcap\fP
+descriptions.
+In that configuration,
+it checks the \fI\%TERMCAP\fP and \fI\%TERMPATH\fP variables
+(for content and search path,
+respectively)
+after the system terminal database.
+.SS "Preparing Descriptions"
We now outline how to prepare descriptions of terminals.
The most effective way to prepare a terminal description is by imitating
the description of a similar terminal in
@@ -237,20 +327,18 @@
key several times quickly.
If the terminal messes up, more padding is usually needed.
A similar test can be used for insert character.
-.PP
-.SS Basic Capabilities
-.PP
+.SS "Basic Capabilities"
The number of columns on each line for the terminal is given by the
-\fBcols\fR numeric capability.
+\fBcols\fP numeric capability.
If the terminal is a \s-1CRT\s0, then the
-number of lines on the screen is given by the \fBlines\fR capability.
+number of lines on the screen is given by the \fBlines\fP capability.
If the terminal wraps around to the beginning of the next line when
-it reaches the right margin, then it should have the \fBam\fR capability.
+it reaches the right margin, then it should have the \fBam\fP capability.
If the terminal can clear its screen, leaving the cursor in the home
-position, then this is given by the \fBclear\fR string capability.
+position, then this is given by the \fBclear\fP string capability.
If the terminal overstrikes
(rather than clearing a position when a character is struck over)
-then it should have the \fBos\fR capability.
+then it should have the \fBos\fP capability.
If the terminal is a printing terminal, with no soft copy unit,
give it both
.B hc
@@ -262,7 +350,7 @@
If there is a code to move the cursor to the left edge of the current
row, give this as
.BR cr .
-(Normally this will be carriage return, control M.)
+(Normally this will be carriage return, control/M.)
If there is a code to produce an audible signal (bell, beep, etc)
give this as
.BR bel .
@@ -315,7 +403,7 @@
except that they take one parameter, and scroll that many lines.
They are also undefined except at the appropriate edge of the screen.
.PP
-The \fBam\fR capability tells whether the cursor sticks at the right
+The \fBam\fP capability tells whether the cursor sticks at the right
edge of the screen when text is output, but this does not necessarily
apply to a
.B cuf1
@@ -332,7 +420,7 @@
If the terminal has switch selectable automatic margins,
the
.I terminfo
-file usually assumes that this is on; i.e., \fBam\fR.
+file usually assumes that this is on; i.e., \fBam\fP.
If the terminal has a command which moves to the first column of the next
line, that command can be given as
.B nel
@@ -346,38 +434,31 @@
.B nel
out of one or both of them.
.PP
-These capabilities suffice to describe hard-copy and \*(lqglass-tty\*(rq terminals.
+These capabilities suffice to describe
+hard-copy and \*(``glass-tty\*('' terminals.
Thus the model 33 teletype is described as
.PP
-.DT
-.nf
-.ft CW
+.EX
.\".in -2
\s-133\||\|tty33\||\|tty\||\|model 33 teletype,
- bel=^G, cols#72, cr=^M, cud1=^J, hc, ind=^J, os,\s+1
+ bel=\*^G, cols#72, cr=\*^M, cud1=\*^J, hc, ind=\*^J, os,\s+1
.\".in +2
-.ft R
-.fi
+.EE
.PP
while the Lear Siegler \s-1ADM-3\s0 is described as
.PP
-.DT
-.nf
-.ft CW
+.EX
.\".in -2
\s-1adm3\||\|3\||\|lsi adm3,
- am, bel=^G, clear=^Z, cols#80, cr=^M, cub1=^H, cud1=^J,
- ind=^J, lines#24,\s+1
+ am, bel=\*^G, clear=\*^Z, cols#80, cr=\*^M, cub1=\*^H, cud1=\*^J,
+ ind=\*^J, lines#24,\s+1
.\".in +2
-.ft R
-.fi
-.PP
-.SS Parameterized Strings
-.PP
+.EE
+.SS "Parameterized Strings"
Cursor addressing and other strings requiring parameters
in the terminal are described by a
parameterized string capability,
-with \fIprintf\fP-like escapes such as \fI%x\fR in it.
+with \fIprintf\fP-like escapes such as \fI%x\fP in it.
For example, to address the cursor, the
.B cup
capability is given, using two parameters:
@@ -392,62 +473,102 @@
to manipulate it.
Typically a sequence will push one of the
parameters onto the stack and then print it in some format.
-Print (e.g., "%d") is a special case.
-Other operations, including "%t" pop their operand from the stack.
+Print (e.g., \*(``%d\*('') is a special case.
+Other operations, including \*(``%t\*('' pop their operand from the stack.
It is noted that more complex operations are often necessary,
e.g., in the \fBsgr\fP string.
.PP
-The \fB%\fR encodings have the following meanings:
-.PP
+The \fB%\fP encodings have the following meanings:
.TP 5
\fB%%\fP
outputs \*(``%\*(''
.TP
-\fB%\fP\fI[[\fP:\fI]flags][width[.precision]][\fP\fBdoxXs\fP\fI]\fP
-as in \fBprintf\fP, flags are \fI[\-+#]\fP and \fIspace\fP.
+\fB%\fI[[\fR:\fI]flags][width[.precision]][\fBdoxXs\fI]\fR
+as in \fBprintf\fP(3), flags are \fI[\-+#]\fP and \fIspace\fP.
Use a \*(``:\*('' to allow the next character to be a \*(``\-\*('' flag,
-avoiding interpreting "%\-" as an operator.
+avoiding interpreting \*(``%\-\*('' as an operator.
.TP
-\f(CW%c\fP
-print pop() like %c in \fBprintf\fP
+\fB%c\fP
+print \fIpop()\fP like %c in \fBprintf\fP
.TP
\fB%s\fP
-print pop() like %s in \fBprintf\fP
+print \fIpop()\fP like %s in \fBprintf\fP
.TP
-\fB%p\fP\fI[1\-9]\fP
+\fB%p\fI[1\-9]\fR
push \fIi\fP'th parameter
.TP
-\fB%P\fP\fI[a\-z]\fP
-set dynamic variable \fI[a\-z]\fP to pop()
+\fB%P\fI[a\-z]\fR
+set dynamic variable \fI[a\-z]\fP to \fIpop()\fP
.TP
-\fB%g\fP\fI[a\-z]/\fP
+\fB%g\fI[a\-z]\fR
get dynamic variable \fI[a\-z]\fP and push it
.TP
-\fB%P\fP\fI[A\-Z]\fP
+\fB%P\fI[A\-Z]\fR
set static variable \fI[a\-z]\fP to \fIpop()\fP
.TP
-\fB%g\fP\fI[A\-Z]\fP
+\fB%g\fI[A\-Z]\fR
get static variable \fI[a\-z]\fP and push it
.IP
-The terms "static" and "dynamic" are misleading.
+The terms \*(``static\*('' and \*(``dynamic\*('' are misleading.
Historically, these are simply two different sets of variables,
-whose values are not reset between calls to \fBtparm\fP.
+whose values are not reset between calls to \fBtparm\fP(3X).
However, that fact is not documented in other implementations.
-Relying on it will adversely impact portability to other implementations.
+Relying on it will adversely impact portability to other implementations:
+.RS
+.bP
+SVr2 curses supported \fIdynamic\fP variables.
+Those are set only by a \fB%P\fP operator.
+A \fB%g\fP for a given variable without first setting it with \fB%P\fP
+will give unpredictable results, because dynamic variables are
+an uninitialized local array on the stack in the \fBtparm\fP function.
+.bP
+SVr3.2 curses supported \fIstatic\fP variables.
+Those are an array in the \fI\%TERMINAL\fP
+structure (declared in \fBterm.h\fP),
+and are zeroed automatically when the \fBsetupterm\fP function
+allocates the data.
+.bP
+SVr4 curses made no further improvements
+to the \fIdynamic/static\fP variable feature.
+.bP
+Solaris XPG4 curses does not distinguish between \fIdynamic\fP and
+\fIstatic\fP variables.
+They are the same.
+Like SVr4 curses, XPG4 curses does not initialize these explicitly.
+.bP
+Before version 6.3,
+\fI\%ncurses\fP stores both \fIdynamic\fP and \fIstatic\fP
+variables in persistent storage, initialized to zeros.
+.bP
+Beginning with version 6.3,
+\fI\%ncurses\fP stores \fIstatic\fP and \fIdynamic\fP
+variables in the same manner as SVr4.
+.RS
+.bP
+Unlike other implementations, \fI\%ncurses\fP zeros dynamic variables
+before the first \fB%g\fP or \fB%P\fP operator.
+.bP
+Like SVr2,
+the scope of dynamic variables in \fI\%ncurses\fP
+is within the current call to
+\fBtparm\fP.
+Use static variables if persistent storage is needed.
+.RE
+.RE
.TP
-\fB%'\fP\fIc\fP\fB'\fP
+\fB%\*'\fIc\fB\*'\fR
char constant \fIc\fP
.TP
-\fB%{\fP\fInn\fP\fB}\fP
+\fB%{\fInn\fB}\fR
integer constant \fInn\fP
.TP
\fB%l\fP
push strlen(pop)
.TP
\fB%+\fP, \fB%\-\fP, \fB%*\fP, \fB%/\fP, \fB%m\fP
-arithmetic (%m is mod): \fIpush(pop() op pop())\fP
+arithmetic (%m is \fImod\fP): \fIpush(pop() op pop())\fP
.TP
-\fB%&\fP, \fB%|\fP, \fB%^\fP
+\fB%&\fP, \fB%|\fP, \fB%\*^\fP
bit operations (AND, OR and exclusive-OR): \fIpush(pop() op pop())\fP
.TP
\fB%=\fP, \fB%>\fP, \fB%<\fP
@@ -456,8 +577,8 @@
\fB%A\fP, \fB%O\fP
logical AND and OR operations (for conditionals)
.TP
-\fB%!\fP, \fB%~\fP
-unary operations (logical and bit complement): push(op pop())
+\fB%!\fP, \fB%\*~\fP
+unary operations (logical and bit complement): \fIpush(op pop())\fP
.TP
\fB%i\fP
add 1 to first two parameters (for ANSI terminals)
@@ -483,45 +604,52 @@
The \fB\-f\fP option splits the string into lines with the parts indented.
.PP
Binary operations are in postfix form with the operands in the usual order.
-That is, to get x\-5 one would use "%gx%{5}%-".
+That is, to get x\-5 one would use \*(``%gx%{5}%\-\*(''.
\fB%P\fP and \fB%g\fP variables are
persistent across escape-string evaluations.
.PP
Consider the HP2645, which, to get to row 3 and column 12, needs
to be sent \eE&a12c03Y padded for 6 milliseconds.
-Note that the order
-of the rows and columns is inverted here, and that the row and column
-are printed as two digits.
-Thus its \fBcup\fR capability is \*(lqcup=6\eE&%p2%2dc%p1%2dY\*(rq.
+The order of the rows and columns is inverted here,
+and the row and column are printed as two digits.
+The corresponding terminal description is expressed thus:
+.RS
+cup=\eE&a%p2%dc%p1%dY$<6>,
+.RE
.PP
The Microterm \s-1ACT-IV\s0 needs the current row and column sent
-preceded by a \fB^T\fR, with the row and column simply encoded in binary,
-\*(lqcup=^T%p1%c%p2%c\*(rq.
-Terminals which use \*(lq%c\*(rq need to be able to
-backspace the cursor (\fBcub1\fR),
-and to move the cursor up one line on the screen (\fBcuu1\fR).
-This is necessary because it is not always safe to transmit \fB\en\fR
-\fB^D\fR and \fB\er\fR, as the system may change or discard them.
+preceded by a \fB\*^T\fP, with the row and column simply encoded in binary,
+.RS
+cup=\*^T%p1%c%p2%c
+.RE
+.PP
+Terminals which use \*(``%c\*('' need to be able to
+backspace the cursor (\fBcub1\fP),
+and to move the cursor up one line on the screen (\fBcuu1\fP).
+This is necessary because it is not always safe to transmit \fB\en\fP
+\fB\*^D\fP and \fB\er\fP, as the system may change or discard them.
(The library routines dealing with terminfo set tty modes so that
tabs are never expanded, so \et is safe to send.
This turns out to be essential for the Ann Arbor 4080.)
.PP
A final example is the \s-1LSI ADM\s0-3a, which uses row and column
-offset by a blank character, thus \*(lqcup=\eE=%p1%' '%+%c%p2%' '%+%c\*(rq.
+offset by a blank character, thus
+.RS
+cup=\eE=%p1%\*' \*'%+%c%p2%\*' \*'%+%c
+.RE
+.PP
After sending \*(``\eE=\*('', this pushes the first parameter, pushes the
ASCII value for a space (32), adds them (pushing the sum on the stack
in place of the two previous values) and outputs that value as a character.
Then the same is done for the second parameter.
More complex arithmetic is possible using the stack.
-.PP
-.SS Cursor Motions
-.PP
+.SS "Cursor Motions"
If the terminal has a fast way to home the cursor
(to very upper left corner of screen) then this can be given as
-\fBhome\fR; similarly a fast way of getting to the lower left-hand corner
-can be given as \fBll\fR; this may involve going up with \fBcuu1\fR
+\fBhome\fP; similarly a fast way of getting to the lower left-hand corner
+can be given as \fBll\fP; this may involve going up with \fBcuu1\fP
from the home position,
-but a program should never do this itself (unless \fBll\fR does) because it
+but a program should never do this itself (unless \fBll\fP does) because it
can make no assumption about the effect of moving up from the home position.
Note that the home position is the same as addressing to (0,0):
to the top left corner of the screen, not of memory.
@@ -545,7 +673,7 @@
.BR cub ,
.BR cuf ,
and
-.BR cuu
+.B cuu
with a single parameter indicating how many spaces to move.
These are primarily useful if the terminal does not have
.BR cup ,
@@ -553,7 +681,8 @@
.PP
If the terminal needs to be in a special mode when running
a program that uses these capabilities,
-the codes to enter and exit this mode can be given as \fBsmcup\fR and \fBrmcup\fR.
+the codes to enter and exit this mode can be given
+as \fBsmcup\fP and \fBrmcup\fP.
This arises, for example, from terminals like the Concept with more than
one page of memory.
If the terminal has only memory relative cursor addressing and not screen
@@ -566,30 +695,152 @@
If the \fBsmcup\fP sequence will not restore the screen after an
\fBrmcup\fP sequence is output (to the state prior to outputting
\fBrmcup\fP), specify \fBnrrmc\fP.
+.SS Margins
+SVr4 (and X/Open Curses)
+list several string capabilities for setting margins.
+Two were intended for use with terminals,
+and another six were intended for use with printers.
+.bP
+The two terminal capabilities assume that the terminal may have
+the capability of setting the left and/or right margin at the current
+cursor column position.
+.bP
+The printer capabilities assume that the printer may have
+two types of capability:
+.RS
+.bP
+the ability to set a top and/or bottom margin using the current
+line position, and
+.bP
+parameterized capabilities for setting the top, bottom, left, right margins
+given the number of rows or columns.
+.RE
.PP
-.SS Area Clears
+In practice, the categorization into \*(``terminal\*('' and \*(``printer\*(''
+is not suitable:
+.bP
+The AT&T SVr4 terminal database uses \fBsmgl\fP four times,
+for AT&T hardware.
+.IP
+Three of the four are printers.
+They lack the ability to set left/right margins by specifying the column.
+.bP
+Other (non-AT&T) terminals may support margins
+but using different assumptions from AT&T.
+.IP
+For instance, the DEC VT420 supports left/right margins,
+but only using a column parameter.
+As an added complication, the VT420 uses two settings to fully enable
+left/right margins (left/right margin mode, and origin mode).
+The former enables the margins, which causes printed text
+to wrap within margins, but the latter is needed to prevent
+cursor-addressing outside those margins.
+.bP
+Both DEC VT420 left/right margins are set with a single control sequence.
+If either is omitted, the corresponding margin is set to the left or
+right edge of the display (rather than leaving the margin unmodified).
.PP
+These are the margin-related capabilities:
+.PP
+.TS
+center;
+lb lb
+lb l .
+Name Description
+_
+smgl Set left margin at current column
+smgr Set right margin at current column
+smgb Set bottom margin at current line
+smgt Set top margin at current line
+smgbp Set bottom margin at line \fIN\fP
+smglp Set left margin at column \fIN\fP
+smgrp Set right margin at column \fIN\fP
+smgtp Set top margin at line \fIN\fP
+smglr Set both left and right margins to \fIL\fP and \fIR\fP
+smgtb Set both top and bottom margins to \fIT\fP and \fIB\fP
+.TE
+.PP
+When writing an application that
+uses these string capabilities,
+the pairs should be first checked to see
+if each capability in the pair is set or only one is set:
+.bP
+If both \fBsmglp\fP and \fBsmgrp\fP are set,
+each is used with a single argument, \fIN\fP,
+that gives the column number of the left and right margin, respectively.
+.bP
+If both \fBsmgtp\fP and \fBsmgbp\fP are set,
+each is used to set the top and bottom margin,
+respectively:
+.RS 4
+.bP
+\fBsmgtp\fP is used with a single argument, \fIN\fP,
+the line number of the top margin.
+.bP
+\fBsmgbp\fP is used with two arguments, \fIN\fP and \fIM\fP,
+that give the line number of the bottom margin,
+the first counting from the top of the
+page and the second counting from the bottom.
+This accommodates the two styles of specifying
+the bottom margin in different manufacturers' printers.
+.RE
+.IP
+When designing a terminfo entry for a
+printer that has a settable bottom margin,
+only the first or second argument should be used, depending on the printer.
+When developing an application that uses \fBsmgbp\fP to set the bottom margin,
+both arguments must be given.
+.PP
+Conversely, when only one capability in the pair is set:
+.bP
+If only one of \fBsmglp\fP and \fBsmgrp\fP is set,
+then it is used with two arguments,
+the column number of the left and right margins, in that order.
+.bP
+Likewise, if only one of \fBsmgtp\fP and \fBsmgbp\fP is set, then it
+is used with two arguments that give the top and bottom margins,
+in that order, counting from the top of the page.
+.IP
+When designing a terminfo entry for a printer that requires setting both
+left and right or top and bottom margins simultaneously,
+only one capability in the pairs
+\fBsmglp\fP and \fBsmgrp\fP or
+\fBsmgtp\fP and \fBsmgbp\fP should be defined,
+leaving the other unset.
+.PP
+Except for very old terminal descriptions, e.g., those developed for SVr4,
+the scheme just described should be considered obsolete.
+An improved set of capabilities was added late in the SVr4 releases
+(\fBsmglr\fP and \fBsmgtb\fP),
+which explicitly use two parameters for setting the left/right or top/bottom
+margins.
+.PP
+When setting margins, the line- and column-values are zero-based.
+.PP
+The \fBmgc\fP string capability should be defined.
+Applications such as \fBtabs\fP(1) rely upon this to reset all margins.
+.\"
+.SS "Area Clears"
If the terminal can clear from the current position to the end of the
-line, leaving the cursor where it is, this should be given as \fBel\fR.
+line, leaving the cursor where it is, this should be given as \fBel\fP.
If the terminal can clear from the beginning of the line to the current
position inclusive, leaving
the cursor where it is, this should be given as \fBel1\fP.
If the terminal can clear from the current position to the end of the
-display, then this should be given as \fBed\fR.
-\fBEd\fR is only defined from the first column of a line.
+display, then this should be given as \fBed\fP.
+\fBEd\fP is only defined from the first column of a line.
(Thus, it can be simulated by a request to delete a large number of lines,
if a true
.B ed
is not available.)
-.PP
-.SS Insert/delete line and vertical motions
-.PP
+.\"
+.SS "Insert/Delete Line and Vertical Motions"
If the terminal can open a new blank line before the line where the cursor
-is, this should be given as \fBil1\fR; this is done only from the first
+is, this should be given as \fBil1\fP; this is done only from the first
position of a line.
The cursor must then appear on the newly blank line.
If the terminal can delete the line which the cursor is on, then this
-should be given as \fBdl1\fR; this is done only from the first position on
+should be given as \fBdl1\fP; this is done only from the first position on
the line to be deleted.
Versions of
.B il1
@@ -616,12 +867,12 @@
.B rc
(save and restore cursor) commands may be useful for ensuring that
your synthesized insert/delete string does not move the cursor.
-(Note that the \fBncurses\fR(3X) library does this synthesis
+(Note that the \fB\%ncurses\fP(3X) library does this synthesis
automatically, so you need not compose insert/delete strings for
-an entry with \fBcsr\fR).
+an entry with \fBcsr\fP).
.PP
Yet another way to construct insert and delete might be to use a combination of
-index with the memory-lock feature found on some terminals (like the HP\-700/90
+index with the memory-lock feature found on some terminals (like the HP-700/90
series, which however also has insert/delete).
.PP
Inserting lines at the top or bottom of the screen can also be
@@ -632,20 +883,20 @@
on many terminals without a true insert/delete line,
and is often faster even on terminals with those features.
.PP
-The boolean \fBnon_dest_scroll_region\fR should be set if each scrolling
+The Boolean \fBnon_dest_scroll_region\fP should be set if each scrolling
window is effectively a view port on a screen-sized canvas.
To test for
this capability, create a scrolling region in the middle of the screen,
write something to the bottom line, move the cursor to the top of the region,
-and do \fBri\fR followed by \fBdl1\fR or \fBind\fR.
+and do \fBri\fP followed by \fBdl1\fP or \fBind\fP.
If the data scrolled
-off the bottom of the region by the \fBri\fR re-appears, then scrolling
+off the bottom of the region by the \fBri\fP re-appears, then scrolling
is non-destructive.
-System V and XSI Curses expect that \fBind\fR, \fBri\fR,
-\fBindn\fR, and \fBrin\fR will simulate destructive scrolling; their
-documentation cautions you not to define \fBcsr\fR unless this is true.
-This \fBcurses\fR implementation is more liberal and will do explicit erases
-after scrolling if \fBndstr\fR is defined.
+System V and X/Open Curses expect that \fBind\fP, \fBri\fP,
+\fBindn\fP, and \fBrin\fP will simulate destructive scrolling; their
+documentation cautions you not to define \fBcsr\fP unless this is true.
+This \fBcurses\fP implementation is more liberal and will do explicit erases
+after scrolling if \fBndsrc\fP is defined.
.PP
If the terminal has the ability to define a window as part of
memory, which all commands affect,
@@ -655,17 +906,15 @@
and the starting and ending columns in memory, in that order.
.PP
If the terminal can retain display memory above, then the
-\fBda\fR capability should be given; if display memory can be retained
-below, then \fBdb\fR should be given.
+\fBda\fP capability should be given; if display memory can be retained
+below, then \fBdb\fP should be given.
These indicate
that deleting a line or scrolling may bring non-blank lines up from below
-or that scrolling back with \fBri\fR may bring down non-blank lines.
-.PP
-.SS Insert/Delete Character
-.PP
+or that scrolling back with \fBri\fP may bring down non-blank lines.
+.SS "Insert/Delete Character"
There are two basic kinds of intelligent terminals with respect to
insert/delete character which can be described using
-.I terminfo.
+.IR terminfo .
The most common insert/delete character operations affect only the characters
on the current line and shift characters off the end of the line rigidly.
Other terminals, such as the Concept 100 and the Perkin Elmer Owl, make
@@ -676,18 +925,18 @@
You can determine the
kind of terminal you have by clearing the screen and then typing
text separated by cursor motions.
-Type \*(lqabc\ \ \ \ def\*(rq using local
-cursor motions (not spaces) between the \*(lqabc\*(rq and the \*(lqdef\*(rq.
-Then position the cursor before the \*(lqabc\*(rq and put the terminal in insert
+Type \*(``abc\ \ \ \ def\*('' using local
+cursor motions (not spaces) between the \*(``abc\*('' and the \*(``def\*(''.
+Then position the cursor before the \*(``abc\*('' and put the terminal in insert
mode.
If typing characters causes the rest of the line to shift
rigidly and characters to fall off the end, then your terminal does
not distinguish between blanks and untyped positions.
-If the \*(lqabc\*(rq
-shifts over to the \*(lqdef\*(rq which then move together around the end of the
+If the \*(``abc\*(''
+shifts over to the \*(``def\*('' which then move together around the end of the
current line and onto the next as you insert, you have the second type of
-terminal, and should give the capability \fBin\fR, which stands for
-\*(lqinsert null\*(rq.
+terminal, and should give the capability \fBin\fP, which stands for
+\*(``insert null\*(''.
.PP
While these are two logically separate attributes (one line versus multi-line
insert mode, and special treatment of untyped spaces) we have seen no
@@ -695,34 +944,34 @@
.PP
Terminfo can describe both terminals which have an insert mode, and terminals
which send a simple sequence to open a blank position on the current line.
-Give as \fBsmir\fR the sequence to get into insert mode.
-Give as \fBrmir\fR the sequence to leave insert mode.
-Now give as \fBich1\fR any sequence needed to be sent just before sending
+Give as \fBsmir\fP the sequence to get into insert mode.
+Give as \fBrmir\fP the sequence to leave insert mode.
+Now give as \fBich1\fP any sequence needed to be sent just before sending
the character to be inserted.
Most terminals with a true insert mode
-will not give \fBich1\fR; terminals which send a sequence to open a screen
+will not give \fBich1\fP; terminals which send a sequence to open a screen
position should give it here.
.PP
-If your terminal has both, insert mode is usually preferable to \fBich1\fR.
+If your terminal has both, insert mode is usually preferable to \fBich1\fP.
Technically, you should not give both unless the terminal actually requires
both to be used in combination.
Accordingly, some non-curses applications get
confused if both are present; the symptom is doubled characters in an update
using insert.
-This requirement is now rare; most \fBich\fR sequences do not
-require previous smir, and most smir insert modes do not require \fBich1\fR
+This requirement is now rare; most \fBich\fP sequences do not
+require previous smir, and most smir insert modes do not require \fBich1\fP
before each character.
-Therefore, the new \fBcurses\fR actually assumes this
-is the case and uses either \fBrmir\fR/\fBsmir\fR or \fBich\fR/\fBich1\fR as
+Therefore, the new \fBcurses\fP actually assumes this
+is the case and uses either \fBrmir\fP/\fBsmir\fP or \fBich\fP/\fBich1\fP as
appropriate (but not both).
If you have to write an entry to be used under
new curses for a terminal old enough to need both, include the
-\fBrmir\fR/\fBsmir\fR sequences in \fBich1\fR.
+\fBrmir\fP/\fBsmir\fP sequences in \fBich1\fP.
.PP
If post insert padding is needed, give this as a number of milliseconds
-in \fBip\fR (a string option).
+in \fBip\fP (a string option).
Any other sequence which may need to be
-sent after an insert of a single character may also be given in \fBip\fR.
+sent after an insert of a single character may also be given in \fBip\fP.
If your terminal needs both to be placed into an \*(``insert mode\*('' and
a special code to precede each inserted character, then both
.BR smir / rmir
@@ -745,11 +994,11 @@
to delete characters on the same line (e.g., if there is a tab after
the insertion position).
If your terminal allows motion while in
-insert mode you can give the capability \fBmir\fR to speed up inserting
+insert mode you can give the capability \fBmir\fP to speed up inserting
in this case.
-Omitting \fBmir\fR will affect only speed.
+Omitting \fBmir\fP will affect only speed.
Some terminals
-(notably Datamedia's) must not have \fBmir\fR because of the way their
+(notably Datamedia's) must not have \fBmir\fP because of the way their
insert mode works.
.PP
Finally, you can specify
@@ -759,8 +1008,8 @@
with one parameter,
.IR n ,
to delete
-.I n characters,
-and delete mode by giving \fBsmdc\fR and \fBrmdc\fR
+.IR n "characters,"
+and delete mode by giving \fBsmdc\fP and \fBrmdc\fP
to enter and exit delete mode (any mode the terminal needs to be placed
in for
.B dch1
@@ -774,30 +1023,28 @@
can be given as
.B ech
with one parameter.
-.PP
.SS "Highlighting, Underlining, and Visible Bells"
-.PP
If your terminal has one or more kinds of display attributes,
these can be represented in a number of different ways.
You should choose one display form as
-\f2standout mode\fR,
+\f2standout mode\fP,
representing a good, high contrast, easy-on-the-eyes,
format for highlighting error messages and other attention getters.
(If you have a choice, reverse video plus half-bright is good,
or reverse video alone.)
The sequences to enter and exit standout mode
-are given as \fBsmso\fR and \fBrmso\fR, respectively.
+are given as \fBsmso\fP and \fBrmso\fP, respectively.
If the code to change into or out of standout
mode leaves one or even two blank spaces on the screen,
as the TVI 912 and Teleray 1061 do,
-then \fBxmc\fR should be given to tell how many spaces are left.
+then \fBxmc\fP should be given to tell how many spaces are left.
.PP
-Codes to begin underlining and end underlining can be given as \fBsmul\fR
-and \fBrmul\fR respectively.
+Codes to begin underlining and end underlining can be given as \fBsmul\fP
+and \fBrmul\fP respectively.
If the terminal has a code to underline the current character and move
the cursor one space to the right,
such as the Microterm Mime,
-this can be given as \fBuc\fR.
+this can be given as \fBuc\fP.
.PP
Other capabilities to enter various highlighting modes include
.B blink
@@ -828,7 +1075,8 @@
.B sgr
(set attributes),
taking 9 parameters.
-Each parameter is either 0 or nonzero, as the corresponding attribute is on or off.
+Each parameter is either zero (0) or nonzero,
+as the corresponding attribute is on or off.
The 9 parameters are, in order:
standout, underline, reverse, blink, dim, bold, blank, protect, alternate
character set.
@@ -840,21 +1088,20 @@
.PP
.TS
center;
-l l l
-l l l
-lw18 lw14 lw18.
-\fBtparm parameter attribute escape sequence\fP
-
-none none \\E[0m
-p1 standout \\E[0;1;7m
-p2 underline \\E[0;4m
-p3 reverse \\E[0;7m
-p4 blink \\E[0;5m
+lb lb lb
+l l l .
+tparm Parameter Attribute Escape Sequence
+_
+none none \eE[0m
+p1 standout \eE[0;1;7m
+p2 underline \eE[0;4m
+p3 reverse \eE[0;7m
+p4 blink \eE[0;5m
p5 dim not available
-p6 bold \\E[0;1m
-p7 invis \\E[0;8m
+p6 bold \eE[0;1m
+p7 invis \eE[0;8m
p8 protect not used
-p9 altcharset ^O (off) ^N (on)
+p9 altcharset \*^O (off) \*^N (on)
.TE
.PP
We begin each escape sequence by turning off any existing modes, since
@@ -863,9 +1110,9 @@
The vt220 terminal has a protect mode,
though it is not commonly used in sgr
because it protects characters on the screen from the host's erasures.
-The altcharset mode also is different in that it is either ^O or ^N,
+The altcharset mode also is different in that it is either \*^O or \*^N,
depending on whether it is off or on.
-If all modes are turned on, the resulting sequence is \\E[0;1;4;5;7;8m^N.
+If all modes are turned on, the resulting sequence is \eE[0;1;4;5;7;8m\*^N.
.PP
Some sequences are common to different modes.
For example, ;7 is output when either p1 or p3 is true, that is, if
@@ -876,31 +1123,26 @@
.ne 11
.TS
center;
-l l l
-l l l
-lw18 lw14 lw18.
-\fBsequence when to output terminfo translation\fP
-
-.ft CW
-\\E[0 always \\E[0
+lb lb lb
+l l l .
+Sequence When to Output terminfo Translation
+_
+\eE[0 always \eE[0
;1 if p1 or p6 %?%p1%p6%|%t;1%;
;4 if p2 %?%p2%|%t;4%;
;5 if p4 %?%p4%|%t;5%;
;7 if p1 or p3 %?%p1%p3%|%t;7%;
;8 if p7 %?%p7%|%t;8%;
m always m
-^N or ^O if p9 ^N, else ^O %?%p9%t^N%e^O%;
-.ft R
+\*^N or \*^O if p9 \*^N, else \*^O %?%p9%t\*^N%e\*^O%;
.TE
.PP
Putting this all together into the sgr sequence gives:
.PP
-.ft CW
-.nf
- sgr=\\E[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p4%t;5%;
- %?%p1%p3%|%t;7%;%?%p7%t;8%;m%?%p9%t\\016%e\\017%;,
-.fi
-.ft R
+.EX
+ sgr=\eE[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p4%t;5%;
+ %?%p1%p3%|%t;7%;%?%p7%t;8%;m%?%p9%t\e016%e\e017%;,
+.EE
.PP
Remember that if you specify sgr, you must also specify sgr0.
Also, some implementations rely on sgr being given if sgr0 is,
@@ -925,7 +1167,7 @@
.PP
If the terminal has
a way of flashing the screen to indicate an error quietly (a bell replacement)
-then this can be given as \fBflash\fR; it must not move the cursor.
+then this can be given as \fBflash\fP; it must not move the cursor.
.PP
If the cursor needs to be made more visible than normal when it is
not on the bottom line (to make, for example, a non-blinking underline into an
@@ -935,36 +1177,34 @@
If there is a way to make the cursor completely invisible, give that as
.BR civis .
The capability
-.BR cnorm
+.B cnorm
should be given which undoes the effects of both of these modes.
.PP
If your terminal correctly generates underlined characters
(with no special codes needed)
even though it does not overstrike,
-then you should give the capability \fBul\fR.
+then you should give the capability \fBul\fP.
If a character overstriking another leaves both characters on the screen,
specify the capability \fBos\fP.
If overstrikes are erasable with a blank,
-then this should be indicated by giving \fBeo\fR.
-.PP
-.SS Keypad and Function Keys
-.PP
+then this should be indicated by giving \fBeo\fP.
+.SS "Keypad and Function Keys"
If the terminal has a keypad that transmits codes when the keys are pressed,
this information can be given.
Note that it is not possible to handle
terminals where the keypad only works in local (this applies, for example,
to the unshifted HP 2621 keys).
If the keypad can be set to transmit or not transmit,
-give these codes as \fBsmkx\fR and \fBrmkx\fR.
+give these codes as \fBsmkx\fP and \fBrmkx\fP.
Otherwise the keypad is assumed to always transmit.
.PP
The codes sent by the left arrow, right arrow, up arrow, down arrow,
and home keys can be given as
-\fBkcub1, kcuf1, kcuu1, kcud1, \fRand\fB khome\fR respectively.
+\fBkcub1, kcuf1, kcuu1, kcud1, \fRand\fB khome\fP respectively.
If there are function keys such as f0, f1, ..., f10, the codes they send
-can be given as \fBkf0, kf1, ..., kf10\fR.
+can be given as \fBkf0, kf1, ..., kf10\fP.
If these keys have labels other than the default f0 through f10, the labels
-can be given as \fBlf0, lf1, ..., lf10\fR.
+can be given as \fBlf0, lf1, ..., lf10\fP.
.PP
The codes transmitted by certain other special keys can be given:
.bP
@@ -1055,16 +1295,18 @@
give them in \fBsmln\fP and \fBrmln\fP.
\fBsmln\fP is normally output after one or more pln
sequences to make sure that the change becomes visible.
-.PP
-.SS Tabs and Initialization
-.PP
+.SS "Tabs and Initialization"
+A few capabilities are used only for tabs:
+.bP
If the terminal has hardware tabs, the command to advance to the next
tab stop can be given as
.B ht
-(usually control I).
+(usually control/I).
+.bP
A \*(``back-tab\*('' command which moves leftward to the preceding tab stop can
be given as
.BR cbt .
+.IP
By convention, if the teletype modes indicate that tabs are being
expanded by the computer rather than being sent to the terminal,
programs should not use
@@ -1073,14 +1315,15 @@
.B cbt
even if they are present, since the user may not have the tab stops
properly set.
+.bP
If the terminal has hardware tabs which are initially set every
.I n
spaces when the terminal is powered up,
the numeric parameter
.B it
is given, showing the number of spaces the tabs are set to.
-This is normally used by the
-.IR @TSET@
+.IP
+The \fBit\fP capability is normally used by the \fB@TSET@\fP
command to determine whether to set the mode for hardware tab expansion,
and whether to set the tab stops.
If the terminal has tab stops that can be saved in non-volatile memory,
@@ -1088,48 +1331,52 @@
.PP
Other capabilities
include
+.bP
.BR is1 ,
.BR is2 ,
and
.BR is3 ,
initialization strings for the terminal,
+.bP
.BR iprog ,
the path name of a program to be run to initialize the terminal,
-and \fBif\fR, the name of a file containing long initialization strings.
+.bP
+and \fBif\fP, the name of a file containing long initialization strings.
+.PP
These strings are expected to set the terminal into modes consistent
with the rest of the terminfo description.
They are normally sent to the terminal, by the
.I init
-option of the
-.IR @TPUT@
-program, each time the user logs in.
+option of the \fB@TPUT@\fP program, each time the user logs in.
They will be printed in the following order:
.RS
.TP
run the program
-.BR iprog
+.B iprog
.TP
output
-.BR is1
-.BR is2
+.br
+\fBis1\fP and
+.br
+\fBis2\fP
.TP
set the margins using
-.BR mgc ,
-.BR smgl
-and
-.BR smgr
+\fBmgc\fP or
+.br
+\fBsmglp\fP and \fBsmgrp\fP or
+.br
+\fBsmgl\fP and \fBsmgr\fP
.TP
set tabs using
.B tbc
and
-.BR hts
+.B hts
.TP
print the file
-.BR if
+\fBif\fP
.TP
-and finally
-output
-.BR is3 .
+and finally output
+\fBis3\fP.
.RE
.PP
Most initialization is done with
@@ -1146,7 +1393,7 @@
can be given as
.BR rs1 ,
.BR rs2 ,
-.BR rf
+.B rf
and
.BR rs3 ,
analogous to
@@ -1154,14 +1401,16 @@
.B is2 ,
.B if
and
-.BR is3
+.B is3
respectively.
-These strings are output by the
-.IR reset
-program, which is used when the terminal gets into a wedged state.
+These strings are output
+by \fIreset\fP option of \fB@TPUT@\fP,
+or by the \fB@RESET@\fP program
+(an alias of \fB@TSET@\fP),
+which is used when the terminal gets into a wedged state.
Commands are normally placed in
.BR rs1 ,
-.BR rs2
+.B rs2
.B rs3
and
.B rf
@@ -1171,16 +1420,13 @@
normally be part of
.BR is2 ,
but it causes an annoying glitch of the screen and is not normally
-needed since the terminal is usually already in 80 column mode.
+needed since the terminal is usually already in 80-column mode.
.PP
-The
-.IR reset
-program writes strings
-including
+The \fB@RESET@\fP program writes strings including
.BR iprog ,
etc., in the same order as the
-.IR init
-program, using
+.I init
+program, using
.BR rs1 ,
etc., instead of
.BR is1 ,
@@ -1190,10 +1436,10 @@
.BR rs2 ,
.BR rs3 ,
or
-.BR rf
-reset capability strings are missing, the
-.IR reset
-program falls back upon the corresponding initialization capability string.
+.B rf
+reset capability strings are missing,
+the \fB@RESET@\fP program
+falls back upon the corresponding initialization capability string.
.PP
If there are commands to set and clear tab stops, they can be given as
.B tbc
@@ -1206,8 +1452,34 @@
.B is2
or
.BR if .
-.SS Delays and Padding
.PP
+The \fB@TPUT@ reset\fP command uses the same capability strings
+as the \fB@RESET@\fP command,
+although the two programs (\fB@TPUT@\fP and \fB@RESET@\fP)
+provide different command-line options.
+.PP
+In practice, these terminfo capabilities are not often used in
+initialization of tabs
+(though they are required for the \fB@TABS@\fP program):
+.bP
+Almost all hardware terminals (at least those which supported tabs)
+initialized those to every \fIeight\fP columns:
+.IP
+The only exception was the AT&T 2300 series,
+which set tabs to every \fIfive\fP columns.
+.bP
+In particular, developers of the hardware terminals which are commonly used
+as models for modern terminal emulators provided documentation demonstrating
+that \fIeight\fP columns were the standard.
+.bP
+Because of this, the terminal initialization programs
+\fB@TPUT@\fP and \fB@TSET@\fP
+use the
+\fBtbc\fP (\fBclear_all_tabs\fP) and
+\fBhts\fP (\fBset_tab\fP) capabilities directly
+only when the \fBit\fP (\fBinit_tabs\fP) capability
+is set to a value other than \fIeight\fP.
+.SS "Delays and Padding"
Many older and slower terminals do not support either XON/XOFF or DTR
handshaking, including hard copy terminals and some very archaic CRTs
(including, for example, DEC VT100s).
@@ -1215,7 +1487,7 @@
after certain cursor motions and screen changes.
.PP
If the terminal uses xon/xoff handshaking for flow control (that is,
-it automatically emits ^S back to the host when its input buffers are
+it automatically emits \*^S back to the host when its input buffers are
close to full), set
.BR xon .
This capability suppresses the emission of padding.
@@ -1225,237 +1497,275 @@
make better decisions about relative costs, but actual pad characters will
not be transmitted.
.PP
-If \fBpb\fR (padding baud rate) is given, padding is suppressed at baud rates
-below the value of \fBpb\fR.
+If \fBpb\fP (padding baud rate) is given, padding is suppressed at baud rates
+below the value of \fBpb\fP.
If the entry has no padding baud rate, then
-whether padding is emitted or not is completely controlled by \fBxon\fR.
+whether padding is emitted or not is completely controlled by \fBxon\fP.
.PP
If the terminal requires other than a null (zero) character as a pad,
-then this can be given as \fBpad\fR.
+then this can be given as \fBpad\fP.
Only the first character of the
.B pad
string is used.
-.PP
-.SS Status Lines
+.SS "Status Lines"
Some terminals have an extra \*(``status line\*('' which is not normally used by
-software (and thus not counted in the terminal's \fBlines\fR capability).
+software (and thus not counted in the terminal's \fBlines\fP capability).
.PP
The simplest case is a status line which is cursor-addressable but not
part of the main scrolling region on the screen; the Heathkit H19 has
a status line of this kind, as would a 24-line VT100 with a 23-line
scrolling region set up on initialization.
This situation is indicated
-by the \fBhs\fR capability.
+by the \fBhs\fP capability.
.PP
Some terminals with status lines need special sequences to access the
status line.
These may be expressed as a string with single parameter
-\fBtsl\fR which takes the cursor to a given zero-origin column on the
+\fBtsl\fP which takes the cursor to a given zero-origin column on the
status line.
-The capability \fBfsl\fR must return to the main-screen
-cursor positions before the last \fBtsl\fR.
+The capability \fBfsl\fP must return to the main-screen
+cursor positions before the last \fBtsl\fP.
You may need to embed the
-string values of \fBsc\fR (save cursor) and \fBrc\fR (restore cursor)
-in \fBtsl\fR and \fBfsl\fR to accomplish this.
+string values of \fBsc\fP (save cursor) and \fBrc\fP (restore cursor)
+in \fBtsl\fP and \fBfsl\fP to accomplish this.
.PP
The status line is normally assumed to be the same width as the width
of the terminal.
If this is untrue, you can specify it with the numeric
-capability \fBwsl\fR.
+capability \fBwsl\fP.
.PP
-A command to erase or blank the status line may be specified as \fBdsl\fR.
+A command to erase or blank the status line may be specified as \fBdsl\fP.
.PP
-The boolean capability \fBeslok\fR specifies that escape sequences, tabs,
+The Boolean capability \fBeslok\fP specifies that escape sequences, tabs,
etc., work ordinarily in the status line.
.PP
-The \fBncurses\fR implementation does not yet use any of these capabilities.
+The \fI\%ncurses\fP implementation does not yet use any of these
+capabilities.
They are documented here in case they ever become important.
-.PP
-.SS Line Graphics
-.PP
+.SS "Line Graphics"
Many terminals have alternate character sets useful for forms-drawing.
-Terminfo and \fBcurses\fR build in support for the drawing characters
+Terminfo and \fBcurses\fP have built-in support
+for most of the drawing characters
supported by the VT100, with some characters from the AT&T 4410v1 added.
-This alternate character set may be specified by the \fBacsc\fR capability.
+This alternate character set may be specified by the \fBacsc\fP capability.
.PP
-.TS H
-center expand;
-l l l l
-l l l l
-lw25 lw10 lw6 lw6.
-.\".TH
-\fBGlyph ACS Ascii VT100\fR
-\fBName Name Default Name\fR
-UK pound sign ACS_STERLING f }
-arrow pointing down ACS_DARROW v .
-arrow pointing left ACS_LARROW < ,
-arrow pointing right ACS_RARROW > +
-arrow pointing up ACS_UARROW ^ \-
-board of squares ACS_BOARD # h
-bullet ACS_BULLET o ~
-checker board (stipple) ACS_CKBOARD : a
-degree symbol ACS_DEGREE \e f
-diamond ACS_DIAMOND + `
-greater-than-or-equal-to ACS_GEQUAL > z
-greek pi ACS_PI * {
-horizontal line ACS_HLINE \- q
-lantern symbol ACS_LANTERN # i
-large plus or crossover ACS_PLUS + n
-less-than-or-equal-to ACS_LEQUAL < y
-lower left corner ACS_LLCORNER + m
-lower right corner ACS_LRCORNER + j
-not-equal ACS_NEQUAL ! |
-plus/minus ACS_PLMINUS # g
-scan line 1 ACS_S1 ~ o
-scan line 3 ACS_S3 \- p
-scan line 7 ACS_S7 \- r
-scan line 9 ACS_S9 \&_ s
-solid square block ACS_BLOCK # 0
-tee pointing down ACS_TTEE + w
-tee pointing left ACS_RTEE + u
-tee pointing right ACS_LTEE + t
-tee pointing up ACS_BTEE + v
-upper left corner ACS_ULCORNER + l
-upper right corner ACS_URCORNER + k
-vertical line ACS_VLINE | x
+.TS
+center;
+Lb Cb S L Lb
+Lb2 Lb2 Lb Lb1 S
+Lb L C Lb Lx.
+\& acsc \& \&
+ACS Name Value Symbol ASCII Fallback / Glyph Name
+_
+ACS_RARROW 0x2b + > arrow pointing right
+ACS_LARROW 0x2c , < arrow pointing left
+ACS_UARROW 0x2d \- \*^ arrow pointing up
+ACS_DARROW 0x2e . v arrow pointing down
+ACS_BLOCK 0x30 0 # solid square block
+ACS_DIAMOND 0x60 \(ga + diamond
+ACS_CKBOARD 0x61 a : checker board (stipple)
+ACS_DEGREE 0x66 f \e degree symbol
+ACS_PLMINUS 0x67 g # plus/minus
+ACS_BOARD 0x68 h # board of squares
+ACS_LANTERN 0x69 i # lantern symbol
+ACS_LRCORNER 0x6a j + lower right corner
+ACS_URCORNER 0x6b k + upper right corner
+ACS_ULCORNER 0x6c l + upper left corner
+ACS_LLCORNER 0x6d m + lower left corner
+ACS_PLUS 0x6e n + large plus or crossover
+ACS_S1 0x6f o \*~ scan line 1
+ACS_S3 0x70 p \- scan line 3
+ACS_HLINE 0x71 q \- horizontal line
+ACS_S7 0x72 r \- scan line 7
+ACS_S9 0x73 s \&_ scan line 9
+ACS_LTEE 0x74 t + tee pointing right
+ACS_RTEE 0x75 u + tee pointing left
+ACS_BTEE 0x76 v + tee pointing up
+ACS_TTEE 0x77 w + tee pointing down
+ACS_VLINE 0x78 x | vertical line
+ACS_LEQUAL 0x79 y < less-than-or-equal-to
+ACS_GEQUAL 0x7a z > greater-than-or-equal-to
+ACS_PI 0x7b { * greek pi
+ACS_NEQUAL 0x7c | ! not-equal
+ACS_STERLING 0x7d } f UK pound sign
+ACS_BULLET 0x7e \*~ o bullet
.TE
.PP
+A few notes apply to the table itself:
+.bP
+X/Open Curses incorrectly states that the mapping for \fIlantern\fP is
+uppercase \*(``I\*('' although Unix implementations use the
+lowercase \*(``i\*('' mapping.
+.bP
+The DEC VT100 implemented graphics using the alternate character set
+feature, temporarily switching \fImodes\fP and sending characters
+in the range 0x60 (96) to 0x7e (126)
+(the \fBacsc Value\fP column in the table).
+.bP
+The AT&T terminal added graphics characters outside that range.
+.IP
+Some of the characters within the range do not match the VT100;
+presumably they were used in the AT&T terminal:
+\fIboard of squares\fP replaces the VT100 \fInewline\fP symbol, while
+\fIlantern symbol\fP replaces the VT100 \fIvertical tab\fP symbol.
+The other VT100 symbols for control characters (\fIhorizontal tab\fP,
+\fIcarriage return\fP and \fIline-feed\fP) are not (re)used in curses.
+.PP
The best way to define a new device's graphics set is to add a column
to a copy of this table for your terminal, giving the character which
-(when emitted between \fBsmacs\fR/\fBrmacs\fR switches) will be rendered
+(when emitted between \fBsmacs\fP/\fBrmacs\fP switches) will be rendered
as the corresponding graphic.
Then read off the VT100/your terminal
character pairs right to left in sequence; these become the ACSC string.
+.SS "Color Handling"
+The curses library functions \fBinit_pair\fP and \fBinit_color\fP
+manipulate the \fIcolor pairs\fP and \fIcolor values\fP discussed in this
+section
+(see \fBcurs_color\fP(3X) for details on these and related functions).
.PP
-.SS Color Handling
-.PP
-Most color terminals are either \*(``Tektronix-like\*('' or \*(``HP-like\*(''.
+Most color terminals are either \*(``Tektronix-like\*('' or \*(``HP-like\*('':
+.bP
Tektronix-like
-terminals have a predefined set of N colors (where N usually 8), and can set
+terminals have a predefined set of \fIN\fP colors
+(where \fIN\fP is usually 8),
+and can set
character-cell foreground and background characters independently, mixing them
-into N\ *\ N color-pairs.
-On HP-like terminals, the use must set each color
+into \fIN\fP\ *\ \fIN\fP color pairs.
+.bP
+On HP-like terminals, the user must set each color
pair up separately (foreground and background are not independently settable).
-Up to M color-pairs may be set up from 2*M different colors.
-ANSI-compatible
-terminals are Tektronix-like.
+Up to \fIM\fP color pairs may be set up from 2*\fIM\fP different colors.
+ANSI-compatible terminals are Tektronix-like.
.PP
Some basic color capabilities are independent of the color method.
The numeric
-capabilities \fBcolors\fR and \fBpairs\fR specify the maximum numbers of colors
-and color-pairs that can be displayed simultaneously.
-The \fBop\fR (original
+capabilities \fBcolors\fP and \fBpairs\fP specify the maximum numbers of colors
+and color pairs that can be displayed simultaneously.
+The \fBop\fP (original
pair) string resets foreground and background colors to their default values
for the terminal.
-The \fBoc\fR string resets all colors or color-pairs to
+The \fBoc\fP string resets all colors or color pairs to
their default values for the terminal.
Some terminals (including many PC
terminal emulators) erase screen areas with the current background color rather
-than the power-up default background; these should have the boolean capability
-\fBbce\fR.
+than the power-up default background; these should have the Boolean capability
+\fBbce\fP.
.PP
+While the curses library works with \fIcolor pairs\fP
+(reflecting the inability of some devices to set foreground
+and background colors independently),
+there are separate capabilities for setting these features:
+.bP
To change the current foreground or background color on a Tektronix-type
-terminal, use \fBsetaf\fR (set ANSI foreground) and \fBsetab\fR (set ANSI
-background) or \fBsetf\fR (set foreground) and \fBsetb\fR (set background).
+terminal, use \fBsetaf\fP (set ANSI foreground) and \fBsetab\fP (set ANSI
+background) or \fBsetf\fP (set foreground) and \fBsetb\fP (set background).
These take one parameter, the color number.
The SVr4 documentation describes
-only \fBsetaf\fR/\fBsetab\fR; the XPG4 draft says that "If the terminal
+only \fBsetaf\fP/\fBsetab\fP; the XPG4 draft says that "If the terminal
supports ANSI escape sequences to set background and foreground, they should
-be coded as \fBsetaf\fR and \fBsetab\fR, respectively.
+be coded as \fBsetaf\fP and \fBsetab\fP, respectively.
+.bP
If the terminal
supports other escape sequences to set background and foreground, they should
-be coded as \fBsetf\fR and \fBsetb\fR, respectively.
-The \fIvidputs()\fR
-function and the refresh functions use \fBsetaf\fR and \fBsetab\fR if they are
-defined."
+be coded as \fBsetf\fP and \fBsetb\fP, respectively.
+The \fBvidputs\fP and the \fBrefresh\fP(3X) functions
+use the \fBsetaf\fP and \fBsetab\fP capabilities if they are defined.
.PP
-The \fBsetaf\fR/\fBsetab\fR and \fBsetf\fR/\fBsetb\fR capabilities take a
+The \fBsetaf\fP/\fBsetab\fP and \fBsetf\fP/\fBsetb\fP capabilities take a
single numeric argument each.
-Argument values 0-7 of \fBsetaf\fR/\fBsetab\fR are portably defined as
+Argument values 0-7 of \fBsetaf\fP/\fBsetab\fP are portably defined as
follows (the middle column is the symbolic #define available in the header for
-the \fBcurses\fR or \fBncurses\fR libraries).
+the \fBcurses\fP or \fI\%ncurses\fP libraries).
The terminal hardware is free to
map these as it likes, but the RGB values indicate normal locations in color
space.
.PP
-.TS H
+.TS
center;
-l c c c
-l l n l.
-\fBColor #define Value RGB\fR
-black \fBCOLOR_BLACK\fR 0 0, 0, 0
-red \fBCOLOR_RED\ \fR 1 max,0,0
-green \fBCOLOR_GREEN\fR 2 0,max,0
-yellow \fBCOLOR_YELLOW\fR 3 max,max,0
-blue \fBCOLOR_BLUE\fR 4 0,0,max
-magenta \fBCOLOR_MAGENTA\fR 5 max,0,max
-cyan \fBCOLOR_CYAN\fR 6 0,max,max
-white \fBCOLOR_WHITE\fR 7 max,max,max
+cb cb cb cb s s
+l lb c l1 l1 l .
+Color #define Value RGB
+_
+black COLOR_BLACK 0 0, 0, 0
+red COLOR_RED 1 max, 0, 0
+green COLOR_GREEN 2 0, max, 0
+yellow COLOR_YELLOW 3 max, max, 0
+blue COLOR_BLUE 4 0, 0, max
+magenta COLOR_MAGENTA 5 max, 0, max
+cyan COLOR_CYAN 6 0, max, max
+white COLOR_WHITE 7 max, max, max
.TE
+.br
+.if t .ne 6v
.PP
-The argument values of \fBsetf\fR/\fBsetb\fR historically correspond to
+The argument values of \fBsetf\fP/\fBsetb\fP historically correspond to
a different mapping, i.e.,
-.TS H
+.PP
+.TS
center;
-l c c c
-l l n l.
-\fBColor #define Value RGB\fR
-black \fBCOLOR_BLACK\fR 0 0, 0, 0
-blue \fBCOLOR_BLUE\fR 1 0,0,max
-green \fBCOLOR_GREEN\fR 2 0,max,0
-cyan \fBCOLOR_CYAN\fR 3 0,max,max
-red \fBCOLOR_RED\ \fR 4 max,0,0
-magenta \fBCOLOR_MAGENTA\fR 5 max,0,max
-yellow \fBCOLOR_YELLOW\fR 6 max,max,0
-white \fBCOLOR_WHITE\fR 7 max,max,max
+cb cb cb cb s s
+l lb c l1 l1 l .
+Color #define Value RGB
+_
+black COLOR_BLACK 0 0, 0, 0
+blue COLOR_BLUE 1 0, 0, max
+green COLOR_GREEN 2 0, max, 0
+cyan COLOR_CYAN 3 0, max, max
+red COLOR_RED 4 max, 0, 0
+magenta COLOR_MAGENTA 5 max, 0, max
+yellow COLOR_YELLOW 6 max, max, 0
+white COLOR_WHITE 7 max, max, max
.TE
.PP
It is important to not confuse the two sets of color capabilities;
otherwise red/blue will be interchanged on the display.
.PP
-On an HP-like terminal, use \fBscp\fR with a color-pair number parameter to set
+On an HP-like terminal, use \fBscp\fP with a color pair number parameter to set
which color pair is current.
.PP
-On a Tektronix-like terminal, the capability \fBccc\fR may be present to
+Some terminals allow the \fIcolor values\fP to be modified:
+.bP
+On a Tektronix-like terminal, the capability \fBccc\fP may be present to
indicate that colors can be modified.
-If so, the \fBinitc\fR capability will
-take a color number (0 to \fBcolors\fR \- 1)and three more parameters which
+If so, the \fBinitc\fP capability will
+take a color number (0 to \fBcolors\fP \- 1)and three more parameters which
describe the color.
These three parameters default to being interpreted as RGB
(Red, Green, Blue) values.
-If the boolean capability \fBhls\fR is present,
+If the Boolean capability \fBhls\fP is present,
they are instead as HLS (Hue, Lightness, Saturation) indices.
The ranges are
terminal-dependent.
-.PP
-On an HP-like terminal, \fBinitp\fR may give a capability for changing a
-color-pair value.
-It will take seven parameters; a color-pair number (0 to
-\fBmax_pairs\fR \- 1), and two triples describing first background and then
+.bP
+On an HP-like terminal, \fBinitp\fP may give a capability for changing a
+color pair value.
+It will take seven parameters; a color pair number (0 to
+\fBmax_pairs\fP \- 1), and two triples describing first background and then
foreground colors.
These parameters must be (Red, Green, Blue) or
-(Hue, Lightness, Saturation) depending on \fBhls\fR.
+(Hue, Lightness, Saturation) depending on \fBhls\fP.
.PP
On some color terminals, colors collide with highlights.
You can register
-these collisions with the \fBncv\fR capability.
-This is a bit-mask of
+these collisions with the \fBncv\fP capability.
+This is a bit mask of
attributes not to be used when colors are enabled.
The correspondence with the
-attributes understood by \fBcurses\fR is as follows:
+attributes understood by \fBcurses\fP is as follows:
.PP
.TS
center;
-l l l l
-lw20 lw2 lw10 lw10.
-\fBAttribute Bit Decimal Set by\fR
+cb cb cb cb
+lb n n lb.
+Attribute Bit Decimal Set by
+_
A_STANDOUT 0 1 sgr
A_UNDERLINE 1 2 sgr
A_REVERSE 2 4 sgr
-A_BLINK 3 8 sgr
-A_DIM 4 16 sgr
-A_BOLD 5 32 sgr
-A_INVIS 6 64 sgr
+A_BLINK 3 8 sgr
+A_DIM 4 16 sgr
+A_BOLD 5 32 sgr
+A_INVIS 6 64 sgr
A_PROTECT 7 128 sgr
A_ALTCHARSET 8 256 sgr
A_HORIZONTAL 9 512 sgr1
@@ -1470,19 +1780,21 @@
For example, on many IBM PC consoles, the underline attribute collides with the
foreground color blue and is not available in color mode.
These should have
-an \fBncv\fR capability of 2.
+an \fBncv\fP capability of 2.
.PP
-SVr4 curses does nothing with \fBncv\fR, ncurses recognizes it and optimizes
+SVr4 curses does nothing with \fBncv\fP,
+\fI\%ncurses\fP recognizes it and optimizes
the output in favor of colors.
-.PP
.SS Miscellaneous
If the terminal requires other than a null (zero) character as a pad, then this
can be given as pad.
Only the first character of the pad string is used.
If the terminal does not have a pad character, specify npc.
-Note that ncurses implements the termcap-compatible \fBPC\fR variable;
+Note that \fI\%ncurses\fP implements the termcap-compatible \fBPC\fP
+variable;
though the application may set this value to something other than
-a null, ncurses will test \fBnpc\fR first and use napms if the terminal
+a null,
+\fI\%ncurses\fP will test \fBnpc\fP first and use napms if the terminal
has no pad character.
.PP
If the terminal can move up or down half a line,
@@ -1495,7 +1807,7 @@
This is primarily useful for superscripts and subscripts on hard-copy terminals.
If a hard-copy terminal can eject to the next page (form feed), give this as
.B ff
-(usually control L).
+(usually control/L).
.PP
If there is a command to repeat a given character a given number of
times (to save time transmitting a large number of identical characters)
@@ -1503,16 +1815,17 @@
.BR rep .
The first parameter is the character to be repeated and the second
is the number of times to repeat it.
-Thus, tparm(repeat_char, 'x', 10) is the same as \*(``xxxxxxxxxx\*(''.
+Thus, tparm(repeat_char, \*'x\*', 10) is the same as \*(``xxxxxxxxxx\*(''.
.PP
-If the terminal has a settable command character, such as the \s-1TEKTRONIX\s+1 4025,
+If the terminal has a settable command character,
+such as the \s-1TEKTRONIX\s+1 4025,
this can be indicated with
.BR cmdch .
A prototype command character is chosen which is used in all capabilities.
This character is given in the
.B cmdch
capability to identify it.
-The following convention is supported on some UNIX systems:
+The following convention is supported on some Unix systems:
The environment is to be searched for a
.B CC
variable, and if found, all
@@ -1554,7 +1867,7 @@
indicates that the number of lines is not fixed,
but that there is still more memory than fits on the screen.
.PP
-If the terminal is one of those supported by the \s-1UNIX\s+1 virtual
+If the terminal is one of those supported by the Unix virtual
terminal protocol, the terminal number can be given as
.BR vt .
.PP
@@ -1581,15 +1894,14 @@
is transparently passed to the printer while an
.B mc5p
is in effect.
+.SS "Glitches and Brain Damage"
+Hazeltine terminals,
+which do not allow \*(``\*~\*('' characters to be displayed should
+indicate \fBhz\fP.
.PP
-.SS Glitches and Braindamage
-.PP
-Hazeltine terminals, which do not allow \*(``~\*('' characters to be displayed should
-indicate \fBhz\fR.
-.PP
-Terminals which ignore a line-feed immediately after an \fBam\fR wrap,
+Terminals which ignore a line-feed immediately after an \fBam\fP wrap,
such as the Concept and vt100,
-should indicate \fBxenl\fR.
+should indicate \fBxenl\fP.
.PP
If
.B el
@@ -1598,92 +1910,66 @@
\fBxhp\fP should be given.
.PP
Teleray terminals, where tabs turn all characters moved over to blanks,
-should indicate \fBxt\fR (destructive tabs).
+should indicate \fBxt\fP (destructive tabs).
Note: the variable indicating this is now \*(``dest_tabs_magic_smso\*(''; in
older versions, it was teleray_glitch.
This glitch is also taken to mean that it is not possible to position
the cursor on top of a \*(``magic cookie\*('',
that to erase standout mode it is instead necessary to use
delete and insert line.
-The ncurses implementation ignores this glitch.
+The \fI\%ncurses\fP implementation ignores this glitch.
.PP
The Beehive Superbee, which is unable to correctly transmit the escape
-or control C characters, has
+or control/C characters, has
.BR xsb ,
-indicating that the f1 key is used for escape and f2 for control C.
+indicating that the f1 key is used for escape and f2 for control/C.
(Only certain Superbees have this problem, depending on the ROM.)
Note that in older terminfo versions, this capability was called
\*(``beehive_glitch\*(''; it is now \*(``no_esc_ctl_c\*(''.
.PP
Other specific terminal problems may be corrected by adding more
-capabilities of the form \fBx\fR\fIx\fR.
-.PP
-.SS Similar Terminals
-.PP
-If there are two very similar terminals, one (the variant) can be defined as
-being just like the other (the base) with certain exceptions.
-In the
-definition of the variant, the string capability \fBuse\fR can be given with
-the name of the base terminal.
-The capabilities given before
-.B use
-override those in the base type named by
-.BR use .
-If there are multiple \fBuse\fR capabilities, they are merged in reverse order.
-That is, the rightmost \fBuse\fR reference is processed first, then the one to
-its left, and so forth.
-Capabilities given explicitly in the entry override
-those brought in by \fBuse\fR references.
-.PP
-A capability can be canceled by placing \fBxx@\fR to the left of the
-use reference that imports it, where \fIxx\fP is the capability.
-For example, the entry
-.RS
-.PP
-2621\-nl, smkx@, rmkx@, use=2621,
-.RE
-.PP
-defines a 2621\-nl that does not have the \fBsmkx\fR or \fBrmkx\fR capabilities,
-and hence does not turn on the function key labels when in visual mode.
-This is useful for different modes for a terminal, or for different
-user preferences.
-.PP
-.SS Pitfalls of Long Entries
-.PP
+capabilities of the form \fBx\fIx\fR.
+.SS "Pitfalls of Long Entries"
Long terminfo entries are unlikely to be a problem; to date, no entry has even
approached terminfo's 4096-byte string-table maximum.
Unfortunately, the termcap
-translations are much more strictly limited (to 1023 bytes), thus termcap translations
-of long terminfo entries can cause problems.
+translations are much more strictly limited (to 1023 bytes),
+thus termcap translations of long terminfo entries can cause problems.
.PP
-The man pages for 4.3BSD and older versions of \fBtgetent()\fP instruct the user to
+The man pages for 4.3BSD
+and older versions of \fBtgetent\fP instruct the user to
allocate a 1024-byte buffer for the termcap entry.
The entry gets null-terminated by
the termcap library, so that makes the maximum safe length for a termcap entry
1k\-1 (1023) bytes.
-Depending on what the application and the termcap library
-being used does, and where in the termcap file the terminal type that \fBtgetent()\fP
-is searching for is, several bad things can happen.
+Depending on what the application and the termcap library being used does,
+and where in the termcap file the terminal type that \fBtgetent\fP
+is searching for is, several bad things can happen:
+.bP
+some termcap libraries print a warning message,
+.bP
+some exit if they find an entry that's longer than 1023 bytes,
+.bP
+some neither exit nor warn, doing nothing useful, and
+.bP
+some simply truncate the entries to 1023 bytes.
.PP
-Some termcap libraries print a warning message or exit if they find an
-entry that's longer than 1023 bytes; others do not; others truncate the
-entries to 1023 bytes.
Some application programs allocate more than
the recommended 1K for the termcap entry; others do not.
.PP
Each termcap entry has two important sizes associated with it: before
-"tc" expansion, and after "tc" expansion.
-"tc" is the capability that
+\*(``tc\*('' expansion, and after \*(``tc\*('' expansion.
+\*(``tc\*('' is the capability that
tacks on another termcap entry to the end of the current one, to add
on its capabilities.
-If a termcap entry does not use the "tc"
+If a termcap entry does not use the \*(``tc\*(''
capability, then of course the two lengths are the same.
.PP
-The "before tc expansion" length is the most important one, because it
+The \*(``before tc expansion\*('' length is the most important one, because it
affects more than just users of that particular terminal.
This is the
length of the entry as it exists in /etc/termcap, minus the
-backslash-newline pairs, which \fBtgetent()\fP strips out while reading it.
+backslash-newline pairs, which \fBtgetent\fP strips out while reading it.
Some termcap libraries strip off the final newline, too (GNU termcap does not).
Now suppose:
.bP
@@ -1695,13 +1981,14 @@
the whole entry into the buffer, no matter what its length, to see
if it is the entry it wants,
.bP
-and \fBtgetent()\fP is searching for a terminal type that either is the
+and \fBtgetent\fP is searching for a terminal type that either is the
long entry, appears in the termcap file after the long entry, or
-does not appear in the file at all (so that \fBtgetent()\fP has to search
+does not appear in the file at all (so that \fBtgetent\fP has to search
the whole termcap file).
.PP
-Then \fBtgetent()\fP will overwrite memory, perhaps its stack, and probably core dump
-the program.
+Then \fBtgetent\fP will overwrite memory,
+perhaps its stack,
+and probably core dump the program.
Programs like telnet are particularly vulnerable; modern telnets
pass along values like the terminal type automatically.
The results are almost
@@ -1711,114 +1998,131 @@
termcap library truncates long entries, like OSF/1 3.0, it is immune to dying
here but will return incorrect data for the terminal.
.PP
-The "after tc expansion" length will have a similar effect to the
-above, but only for people who actually set TERM to that terminal
-type, since \fBtgetent()\fP only does "tc" expansion once it is found the
+The \*(``after tc expansion\*('' length will have a similar effect to the
+above, but only for people who actually set \fITERM\fP to that terminal
+type, since \fBtgetent\fP only does \*(``tc\*('' expansion once it is found the
terminal type it was looking for, not while searching.
.PP
In summary, a termcap entry that is longer than 1023 bytes can cause,
on various combinations of termcap libraries and applications, a core
dump, warnings, or incorrect operation.
If it is too long even before
-"tc" expansion, it will have this effect even for users of some other
-terminal types and users whose TERM variable does not have a termcap
+\*(``tc\*('' expansion, it will have this effect even for users of some other
+terminal types and users whose \fITERM\fP variable does not have a termcap
entry.
.PP
-When in \-C (translate to termcap) mode, the \fBncurses\fR implementation of
-\fB@TIC@\fR(1M) issues warning messages when the pre-tc length of a termcap
+When in \-C (translate to termcap) mode,
+the \fI\%ncurses\fP implementation of
+\fB@TIC@\fP(1M) issues warning messages when the pre-tc length of a termcap
translation is too long.
The \-c (check) option also checks resolved (after tc
expansion) lengths.
-.SS Binary Compatibility
-It is not wise to count on portability of binary terminfo entries between
-commercial UNIX versions.
-The problem is that there are at least two versions
-of terminfo (under HP\-UX and AIX) which diverged from System V terminfo after
-SVr1, and have added extension capabilities to the string table that (in the
-binary format) collide with System V and XSI Curses extensions.
+.SH FILES
+.TP
+.I \*d
+compiled terminal description database directory
.SH EXTENSIONS
-.PP
Searching for terminal descriptions in
-\fB$HOME/.terminfo\fR and TERMINFO_DIRS
+\fI$HOME/.terminfo\fP and \fI\%TERMINFO_DIRS\fP
is not supported by older implementations.
.PP
-Some SVr4 \fBcurses\fR implementations, and all previous to SVr4, do not
+Some SVr4 \fBcurses\fP implementations, and all previous to SVr4, do not
interpret the %A and %O operators in parameter strings.
.PP
-SVr4/XPG4 do not specify whether \fBmsgr\fR licenses movement while in
+SVr4/XPG4 do not specify whether \fBmsgr\fP licenses movement while in
an alternate-character-set mode (such modes may, among other things, map
CR and NL to characters that do not trigger local motions).
-The \fBncurses\fR implementation ignores \fBmsgr\fR in \fBALTCHARSET\fR
-mode.
+The \fI\%ncurses\fP implementation ignores \fBmsgr\fP in
+\fBALTCHARSET\fP mode.
This raises the possibility that an XPG4
implementation making the opposite interpretation may need terminfo
-entries made for \fBncurses\fR to have \fBmsgr\fR turned off.
+entries made for \fI\%ncurses\fP to have \fBmsgr\fP turned off.
.PP
-The \fBncurses\fR library handles insert-character and insert-character modes
-in a slightly non-standard way to get better update efficiency.
+The \fI\%ncurses\fP library handles insert-character and
+insert-character modes in a slightly non-standard way to get better
+update efficiency.
See
-the \fBInsert/Delete Character\fR subsection above.
+the \fBInsert/Delete Character\fP subsection above.
.PP
-The parameter substitutions for \fBset_clock\fR and \fBdisplay_clock\fR are
-not documented in SVr4 or the XSI Curses standard.
+The parameter substitutions for \fBset_clock\fP and \fBdisplay_clock\fP are
+not documented in SVr4 or X/Open Curses.
They are deduced from the
documentation for the AT&T 505 terminal.
.PP
-Be careful assigning the \fBkmous\fR capability.
-The \fBncurses\fR wants to
-interpret it as \fBKEY_MOUSE\fR, for use by terminals and emulators like xterm
+Be careful assigning the \fBkmous\fP capability.
+The \fI\%ncurses\fP library wants to interpret it as \fBKEY_MOUSE\fP,
+for use by terminals and emulators like xterm
that can return mouse-tracking information in the keyboard-input stream.
.PP
X/Open Curses does not mention italics.
Portable applications must assume that numeric capabilities are
signed 16-bit values.
-This includes the \fIno_color_video\fP (ncv) capability.
-The 32768 mask value used for italics with ncv can be confused with
-an absent or cancelled ncv.
+This includes the \fIno_color_video\fP (\fBncv\fP) capability.
+The 32768 mask value used for italics with \fBncv\fP can be confused with
+an absent or cancelled \fBncv\fP.
If italics should work with colors,
-then the ncv value must be specified, even if it is zero.
+then the \fBncv\fP value must be specified, even if it is zero.
.PP
-Different commercial ports of terminfo and curses support different subsets of
-the XSI Curses standard and (in some cases) different extension sets.
-Here
-is a summary, accurate as of October 1995:
-.PP
-\fBSVR4, Solaris, ncurses\fR \-\-
-These support all SVr4 capabilities.
-.PP
-\fBSGI\fR \-\-
-Supports the SVr4 set, adds one undocumented extended string
-capability (\fBset_pglen\fR).
-.PP
-\fBSVr1, Ultrix\fR \-\-
-These support a restricted subset of terminfo capabilities.
-The booleans end with \fBxon_xoff\fR;
-the numerics with \fBwidth_status_line\fR;
-and the strings with \fBprtr_non\fR.
-.PP
-\fBHP/UX\fR \-\-
-Supports the SVr1 subset, plus the SVr[234] numerics \fBnum_labels\fR,
-\fBlabel_height\fR, \fBlabel_width\fR, plus function keys 11 through 63, plus
-\fBplab_norm\fR, \fBlabel_on\fR, and \fBlabel_off\fR, plus some incompatible
-extensions in the string table.
-.PP
-\fBAIX\fR \-\-
-Supports the SVr1 subset, plus function keys 11 through 63, plus a number
-of incompatible string table extensions.
-.PP
-\fBOSF\fR \-\-
-Supports both the SVr4 set and the AIX extensions.
-.SH FILES
-.TP 25
-\*d/?/*
-files containing terminal descriptions
-.SH SEE ALSO
-\fB@TIC@\fR(1M),
-\fB@INFOCMP@\fR(1M),
-\fBcurses\fR(3X),
-\fBprintf\fR(3),
-\fBterm\fR(\*n).
-\fBterm_variables\fR(3X).
+Different commercial ports of \fI\%terminfo\fP and \fIcurses\fP support
+different subsets of X/Open Curses and
+(in some cases)
+different extensions.
+Here is a summary,
+accurate as of October 1995,
+after which the commercial Unix market contracted and lost diversity.
+.bP
+SVr4,
+Solaris,
+and \fI\%ncurses\fP support all SVr4 capabilities.
+.bP
+IRIX supports the SVr4 set and adds one undocumented extended string
+capability (\fB\%set_pglen\fP).
+.bP
+SVr1 and Ultrix support a restricted subset of \fI\%terminfo\fP
+capabilities.
+The Booleans end with \fB\%xon_xoff\fP;
+the numerics with \fB\%width_status_line\fP;
+and the strings with \fB\%prtr_non\fP.
+.bP
+HP/UX supports the SVr1 subset,
+plus the SVr[234] numerics
+\fB\%num_labels\fP,
+\fB\%label_height\fP,
+\fB\%label_width\fP,
+plus function keys 11 through 63,
+plus
+\fB\%plab_norm\fP,
+\fB\%label_on\fP,
+and
+\fB\%label_off\fP,
+plus a number of incompatible string table extensions.
+.bP
+AIX supports the SVr1 subset,
+plus function keys 11 through 63,
+plus a number of incompatible string table extensions.
+.bP
+OSF/1 supports both the SVr4 set and the AIX extensions.
+.SH PORTABILITY
+Do not count on compiled (binary) \fI\%terminfo\fP entries being
+portable between commercial Unix systems.
+At least two implementations of \fI\%terminfo\fP
+(those of HP-UX and AIX)
+diverged from those of other System V Unices after SVr1,
+adding extension capabilities to the string table that
+(in the binary format)
+collide with subsequent System V and X/Open Curses extensions.
.SH AUTHORS
Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
-Based on pcurses by Pavel Curtis.
+Based on \fIpcurses\fP by Pavel Curtis.
+.SH SEE ALSO
+\fB\%@INFOCMP@\fP(1M),
+\fB\%@TABS@\fP(1),
+\fB\%@TIC@\fP(1M),
+\fB\%curses\fP(3X),
+\fB\%curs_color\fP(3X),
+\fB\%curs_terminfo\fP(3X),
+\fB\%curs_variables\fP(3X),
+\fB\%printf\fP(3),
+\fB\%term_variables\fP(3X),
+\fB\%term\fP(5),
+\fB\%user_caps\fP(5)
diff --git a/man/tic.1m b/man/tic.1m
index 878e213..9c3181e 100644
--- a/man/tic.1m
+++ b/man/tic.1m
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2013,2014 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -26,59 +27,70 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tic.1m,v 1.60 2014/05/24 22:00:11 tom Exp $
-.TH @TIC@ 1M ""
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
-.ds n 5
-.ds d @TERMINFO@
+.\" $Id: tic.1m,v 1.110 2024/04/27 17:57:06 tom Exp $
+.TH @TIC@ 1M 2024-04-27 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
+.
+.ds d @TERMINFO@
.SH NAME
-\fB@TIC@\fR \- the \fIterminfo\fR entry-description compiler
+\fB\%@TIC@\fP \-
+compile terminal descriptions for \fIterminfo\fR or \fItermcap\fR
.SH SYNOPSIS
-\fB@TIC@\fR
+\fB@TIC@\fP
[\fB\-\
0\
1\
+a\
+c\
C\
D\
+f\
+g\
G\
I\
K\
L\
N\
-T\
-U\
-V\
-a\
-c\
-f\
-g\
+q\
r\
s\
t\
+T\
+U\
+V\
+W\
x\
-\fR]
-[\fB\-e\fR \fInames\fR]
-[\fB\-o\fR \fIdir\fR]
-[\fB\-R\fR \fIsubset\fR]
-[\fB\-v\fR[\fIn\fR]]
-[\fB\-w\fR[\fIn\fR]]
-\fIfile\fR
-.br
+\fP]
+[\fB\-e\fP \fIterminal-type-list\fP]
+[\fB\-o\fP \fIdir\fP]
+[\fB\-Q\fP[\fIn\fP]]
+[\fB\-R\fP \fIsubset\fP]
+[\fB\-v\fP[\fIn\fP]]
+[\fB\-w\fP[\fIn\fP]]
+\fIfile\fP
.SH DESCRIPTION
-The \fB@TIC@\fR command translates a \fBterminfo\fR file from source
+The \fB@TIC@\fP command translates a \fBterminfo\fP file from source
format into compiled format.
The compiled format is necessary for use with
-the library routines in \fBncurses\fR(3X).
+the library routines in \fB\%ncurses\fP(3X).
.PP
-As described in \fBterm\fR(\*n), the database may be either a directory
+As described in \fBterm\fP(5), the database may be either a directory
tree (one file per terminal entry) or a hashed database (one record per entry).
-The \fB@TIC@\fR command writes only one type of entry,
+The \fB@TIC@\fP command writes only one type of entry,
depending on how it was built:
.bP
For directory trees, the top-level directory, e.g., /usr/share/terminfo,
@@ -94,66 +106,76 @@
.PP
In either case (directory or hashed database),
\fB@TIC@\fP will create the container if it does not exist.
-For a directory, this would be the "terminfo" leaf,
+For a directory, this would be the \*(``terminfo\*('' leaf,
versus a "terminfo.db" file.
.PP
-The results are normally placed in the system terminfo database \fB\*d\fR.
+The results are normally placed in the system terminfo database \fB\*d\fP.
The compiled terminal description can be placed
in a different terminfo database.
There are two ways to achieve this:
.bP
First, you may override the system default either by
using the \fB\-o\fP option,
-or by setting the variable \fBTERMINFO\fR
+or by setting the variable \fI\%TERMINFO\fP
in your shell environment to a valid database location.
.bP
-Secondly, if \fB@TIC@\fR cannot write in \fI\*d\fR
-or the location specified using your TERMINFO variable,
-it looks for the directory \fI$HOME/.terminfo\fR
-(or hashed database \fI$HOME/.terminfo.db)\fR;
+Secondly, if \fB@TIC@\fP cannot write in \fI\*d\fP
+or the location specified using your \fI\%TERMINFO\fP variable,
+it looks for the directory \fI$HOME/.terminfo\fP
+(or hashed database \fI$HOME/.terminfo.db)\fP;
if that location exists, the entry is placed there.
.PP
Libraries that read terminfo entries are expected to check in succession
.bP
-a location specified with the TERMINFO environment variable,
+a location specified with the \fI\%TERMINFO\fP environment variable,
.bP
-\fI$HOME/.terminfo\fR,
+\fI$HOME/.terminfo\fP,
.bP
-directories listed in the TERMINFO_DIRS environment variable,
+directories listed in the \fI\%TERMINFO_DIRS\fP environment variable,
.bP
a compiled-in list of directories (@TERMINFO_DIRS@), and
.bP
-the system terminfo database (\fI\*d\fR).
-.SS OPTIONS
+the system terminfo database (\fI\*d\fP).
+.PP
+The \fIFetching Compiled Descriptions\fP section in the \fBterminfo\fR(5)
+manual goes into further detail.
+.SS Aliases
+This is the same program as @INFOTOCAP@ and @CAPTOINFO@;
+usually those are linked to, or copied from this program:
+.bP
+When invoked as @INFOTOCAP@, @TIC@ sets the \fB\-I\fP option.
+.bP
+When invoked as @CAPTOINFO@, @TIC@ sets the \fB\-C\fP option.
+.SH OPTIONS
.TP
-\fB\-0\fR
+\fB\-0\fP
restricts the output to a single line
.TP
-\fB\-1\fR
+\fB\-1\fP
restricts the output to a single column
.TP
-\fB\-a\fR
+\fB\-a\fP
tells \fB@TIC@\fP to retain commented-out capabilities rather than discarding
them.
Capabilities are commented by prefixing them with a period.
-This sets the \fB\-x\fR option, because it treats the commented-out
+This sets the \fB\-x\fP option, because it treats the commented-out
entries as user-defined names.
If the source is termcap, accept the 2-character names required by version 6.
Otherwise these are ignored.
.TP
-\fB\-C\fR
+\fB\-C\fP
Force source translation to termcap format.
-Note: this differs from the \fB\-C\fR
-option of \fB@INFOCMP@\fR(1M) in that it does not merely translate capability
+Note: this differs from the \fB\-C\fP
+option of \fB@INFOCMP@\fP(1M) in that it does not merely translate capability
names, but also translates terminfo strings to termcap format.
Capabilities
that are not translatable are left in the entry under their terminfo names
but commented out with two preceding dots.
The actual format used incorporates some improvements for escaped characters
from terminfo format.
-For a stricter BSD-compatible translation, add the \fB\-K\fR option.
+For a stricter BSD-compatible translation, add the \fB\-K\fP option.
.IP
-If this is combined with \fB\-c\fR, \fB@TIC@\fR makes additional checks
+If this is combined with \fB\-c\fP, \fB@TIC@\fP makes additional checks
to report cases where the terminfo values do not have an exact equivalent
in termcap form.
For example:
@@ -167,10 +189,10 @@
the string will not convert completely.
.RE
.TP
-\fB\-c\fR
-tells \fB@TIC@\fP to only check \fIfile\fR for errors, including syntax problems and
-bad use links.
-If you specify \fB\-C\fR (\fB\-I\fR) with this option, the code
+\fB\-c\fP
+tells \fB@TIC@\fP to only check \fIfile\fP for errors,
+including syntax problems and bad use-links.
+If you specify \fB\-C\fP (\fB\-I\fP) with this option, the code
will print warnings about entries which, after use resolution, are more than
1023 (4096) bytes long.
Due to a fixed buffer length in older termcap libraries,
@@ -184,7 +206,7 @@
It does this check only for the predefined string capabilities;
those which are defined with the \fB\-x\fP option are ignored.
.TP
-\fB\-D\fR
+\fB\-D\fP
tells \fB@TIC@\fP to print the database locations that it knows about, and exit.
The first location shown is the one to which it would write compiled
terminal descriptions.
@@ -193,66 +215,95 @@
it will print a diagnostic and exit with an error rather than
printing a list of database locations.
.TP
-\fB\-e \fR\fInames\fR
-Limit writes and translations to the following comma-separated list of
-terminals.
+\fB\-e \fIlist\fR
+Limit writes and translations to the comma-separated \fIlist\fP of
+terminal types.
If any name or alias of a terminal matches one of the names in
the list, the entry will be written or translated as normal.
Otherwise no output will be generated for it.
The option value is interpreted as a file containing the list if it
contains a '/'.
-(Note: depending on how tic was compiled, this option may require \fB\-I\fR or \fB\-C\fR.)
+(Note: depending on how @TIC@ was compiled,
+this option may require \fB\-I\fP or \fB\-C\fP.)
.TP
-\fB\-f\fR
+\fB\-f\fP
Display complex terminfo strings which contain if/then/else/endif expressions
indented for readability.
.TP
-\fB\-G\fR
+\fB\-G\fP
Display constant literals in decimal form
rather than their character equivalents.
.TP
-\fB\-g\fR
+\fB\-g\fP
Display constant character literals in quoted form
rather than their decimal equivalents.
.TP
-\fB\-I\fR
+\fB\-I\fP
Force source translation to terminfo format.
.TP
-\fB\-K\fR
-Suppress some longstanding ncurses extensions to termcap format,
-e.g., "\\s" for space.
+\fB\-K\fP
+Suppress some longstanding \fI\%ncurses\fP extensions to termcap format,
+e.g., "\es" for space.
.TP
-\fB\-L\fR
+\fB\-L\fP
Force source translation to terminfo format
-using the long C variable names listed in <\fBterm.h\fR>
+using the long C variable names listed in <\fBterm.h\fP>
.TP
-\fB\-N\fR
+\fB\-N\fP
Disable smart defaults.
Normally, when translating from termcap to terminfo, the compiler makes
a number of assumptions about the defaults of string capabilities
-\fBreset1_string\fR, \fBcarriage_return\fR, \fBcursor_left\fR,
-\fBcursor_down\fR, \fBscroll_forward\fR, \fBtab\fR, \fBnewline\fR,
-\fBkey_backspace\fR, \fBkey_left\fR, and \fBkey_down\fR, then attempts
+\fBreset1_string\fP, \fBcarriage_return\fP, \fBcursor_left\fP,
+\fBcursor_down\fP, \fBscroll_forward\fP, \fBtab\fP, \fBnewline\fP,
+\fBkey_backspace\fP, \fBkey_left\fP, and \fBkey_down\fP, then attempts
to use obsolete termcap capabilities to deduce correct values.
It also
-normally suppresses output of obsolete termcap capabilities such as \fBbs\fR.
+normally suppresses output of obsolete termcap capabilities such as \fBbs\fP.
This option forces a more literal translation that also preserves the
obsolete capabilities.
.TP
-\fB\-o\fR\fIdir\fR
+\fB\-o\fIdir\fR
Write compiled entries to given database location.
-Overrides the TERMINFO environment variable.
+Overrides the \fI\%TERMINFO\fP environment variable.
.TP
-\fB\-R\fR\fIsubset\fR
+\fB\-Q\fIn\fR
+Rather than show source in terminfo (text) format,
+print the compiled (binary) format in hexadecimal or base64 form,
+depending on the option's value:
+.RS 8
+.TP 3
+1
+hexadecimal
+.TP 3
+2
+base64
+.TP 3
+3
+hexadecimal and base64
+.RE
+.TP
+\fB\-q\fP
+Suppress comments and blank lines when showing translated source.
+.TP
+\fB\-R\fIsubset\fR
Restrict output to a given subset.
This option is for use with archaic
-versions of terminfo like those on SVr1, Ultrix, or HP/UX that do not support
+versions of terminfo like those on SVr1, Ultrix, or HP-UX that do not support
the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX 3.x
that have their own extensions incompatible with SVr4/XSI.
-Available subsets
-are "SVr1", "Ultrix", "HP", "BSD" and "AIX"; see \fBterminfo\fR(\*n) for details.
+.IP
+Available subsets are
+.RS
+\*(``SVr1\*('',
+\*(``Ultrix\*('',
+\*(``HP\*('',
+\*(``BSD\*('', and
+\*(``AIX\*(''
+.RE
+.IP
+See \fBterminfo\fP(5) for details.
.TP
-\fB\-r\fR
+\fB\-r\fP
Force entry resolution (so there are no remaining tc capabilities) even
when doing translation to termcap format.
This may be needed if you are
@@ -260,40 +311,50 @@
version 1.3 or BSD termcap through 4.3BSD) that does not handle multiple
tc capabilities per entry.
.TP
-\fB\-s\fR
+\fB\-s\fP
Summarize the compile by showing the database location into which entries
are written, and the number of entries which are compiled.
.TP
-\fB\-T\fR
+\fB\-T\fP
eliminates size-restrictions on the generated text.
This is mainly useful for testing and analysis, since the compiled
descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
.TP
-\fB\-t\fR
+\fB\-t\fP
tells \fB@TIC@\fP to discard commented-out capabilities.
Normally when translating from terminfo to termcap,
untranslatable capabilities are commented-out.
-.TP 5
-\fB\-U\fR
+.TP
+\fB\-U\fP
tells \fB@TIC@\fP to not post-process the data after parsing the source file.
Normally, it infers data which is commonly missing in older terminfo data,
or in termcaps.
.TP
-\fB\-V\fR
-reports the version of ncurses which was used in this program, and exits.
+\fB\-V\fP
+reports the version of \fI\%ncurses\fP which was used in this program,
+and exits.
.TP
-\fB\-v\fR\fIn\fR
+\fB\-v\fIn\fR
specifies that (verbose) output be written to standard error trace
-information showing \fB@TIC@\fR's progress.
-The optional parameter \fIn\fR is a number from 1 to 10, inclusive,
+information showing \fB@TIC@\fP's progress.
+.IP
+The optional parameter \fIn\fP is a number from 1 to 9, inclusive,
indicating the desired level of detail of information.
-If \fIn\fR is omitted, the default level is 1.
-If \fIn\fR is specified and greater than 1, the level of
-detail is increased.
+.RS
+.bP
+If \fI\%ncurses\fP is built without tracing support,
+the optional parameter is ignored.
+.bP
+If \fIn\fP is omitted, the default level is 1.
+.bP
+If \fIn\fP is specified and greater than 1, the level of
+detail is increased, and the output is written (with tracing information)
+to the \*(``trace\*('' file.
+.RE
.RS
.PP
The debug flag levels are as follows:
-.TP
+.TP 4
1
Names of files created and linked
.TP
@@ -303,8 +364,14 @@
3
Statistics from the hashing algorithm
.TP
+4
+Details of extended capabilities
+.TP
5
-String-table memory allocations
+(unused)
+.TP
+6
+(unused)
.TP
7
Entries into the string-table
@@ -314,129 +381,242 @@
.TP
9
All values computed in construction of the hash table
-.LP
-If the debug level \fIn\fR is not given, it is taken to be one.
.RE
.TP
-\fB\-w\fR\fIn\fR
+\fB\-W\fP
+By itself, the \fB\-w\fP option will not force long strings to be wrapped.
+Use the \fB\-W\fP option to do this.
+.IP
+If you specify both \fB\-f\fP and \fB\-W\fP options,
+the latter is ignored when \fB\-f\fP has already split the line.
+.TP
+\fB\-w\fIn\fR
specifies the width of the output.
The parameter is optional.
If it is omitted, it defaults to 60.
.TP
-\fB\-x\fR
-Treat unknown capabilities as user-defined.
+\fB\-x\fP
+Treat unknown capabilities as user-defined (see \fBuser_caps\fP(5)).
That is, if you supply a capability name which \fB@TIC@\fP does not recognize,
-it will infer its type (boolean, number or string) from the syntax and
+it will infer its type (Boolean, number or string) from the syntax and
make an extended table entry for that.
User-defined capability strings
whose name begins with \*(``k\*('' are treated as function keys.
-.SS PARAMETERS
+.SS Parameters
.TP
-\fIfile\fR
-contains one or more \fBterminfo\fR terminal descriptions in source
-format [see \fBterminfo\fR(\*n)].
+\fIfile\fP
+contains one or more \fBterminfo\fP terminal descriptions in source
+format [see \fBterminfo\fP(5)].
Each description in the file
describes the capabilities of a particular terminal.
.IP
-If \fIfile\fR is \*(``-\*('', then the data is read from the standard input.
-The \fIfile\fR parameter may also be the path of a character-device.
-.SS PROCESSING
+If \fIfile\fP is \*(``-\*('', then the data is read from the standard input.
+The \fIfile\fP parameter may also be the path of a character-device.
+.SS Processing
+All but one of the capabilities recognized by \fB@TIC@\fP are documented
+in \fBterminfo\fP(5).
+The exception is the \fBuse\fP capability.
.PP
-All but one of the capabilities recognized by \fB@TIC@\fR are documented
-in \fBterminfo\fR(\*n).
-The exception is the \fBuse\fR capability.
-.PP
-When a \fBuse\fR=\fIentry\fR\-\fIname\fR field is discovered in a
-terminal entry currently being compiled, \fB@TIC@\fR reads in the binary
-from \fB\*d\fR to complete the entry.
+When a \fBuse\fP=\fIentry\fP\-\fIname\fP field is discovered in a
+terminal entry currently being compiled, \fB@TIC@\fP reads in the binary
+from \fB\*d\fP to complete the entry.
(Entries created from
-\fIfile\fR will be used first.
-\fB@TIC@\fR duplicates the capabilities in
-\fIentry\fR\-\fIname\fR for the current entry, with the exception of
+\fIfile\fP will be used first.
+\fB@TIC@\fP duplicates the capabilities in
+\fIentry\fP\-\fIname\fP for the current entry, with the exception of
those capabilities that explicitly are defined in the current entry.
.PP
-When an entry, e.g., \fBentry_name_1\fR, contains a
-\fBuse=\fR\fIentry\fR_\fIname\fR_\fI2\fR field, any canceled
-capabilities in \fIentry\fR_\fIname\fR_\fI2\fR must also appear in
-\fBentry_name_1\fR before \fBuse=\fR for these capabilities to be
-canceled in \fBentry_name_1\fR.
+When an entry, e.g., \fBentry_name_1\fP, contains a
+\fBuse=\fIentry\fR_\fIname\fR_\fI2\fR field, any canceled
+capabilities in \fIentry\fR_\fIname\fR_\fI2\fP must also appear in
+\fBentry_name_1\fP before \fBuse=\fP for these capabilities to be
+canceled in \fBentry_name_1\fP.
.PP
-Total compiled entries cannot exceed 4096 bytes.
+Total compiled entries cannot exceed
+4096 bytes in the legacy storage format, or
+32768 using the extended number format.
The name field cannot
exceed 512 bytes.
Terminal names exceeding the maximum alias length
(32 characters on systems with long filenames, 14 characters otherwise)
-will be truncated to the maximum alias length and a warning message will be printed.
-.SH COMPATIBILITY
-There is some evidence that historic \fB@TIC@\fR implementations treated
+will be truncated to the maximum alias length
+and a warning message will be printed.
+.SH FILES
+.TP
+.I \*d
+compiled terminal description database
+.SH NOTES
+There is some evidence that historic \fB@TIC@\fP implementations treated
description fields with no whitespace in them as additional aliases or
short names.
-This \fB@TIC@\fR does not do that, but it does warn when
+This \fB@TIC@\fP does not do that, but it does warn when
description fields may be treated that way and check them for dangerous
characters.
.SH EXTENSIONS
-Unlike the SVr4 \fB@TIC@\fR command, this implementation can actually
+Unlike the SVr4 \fB@TIC@\fP command, this implementation can actually
compile termcap sources.
In fact, entries in terminfo and termcap syntax can
be mixed in a single source file.
-See \fBterminfo\fR(\*n) for the list of
+See \fBterminfo\fP(5) for the list of
termcap names taken to be equivalent to terminfo names.
.PP
-The SVr4 manual pages are not clear on the resolution rules for \fBuse\fR
+The SVr4 manual pages are not clear on the resolution rules for \fBuse\fP
capabilities.
-This implementation of \fB@TIC@\fR will find \fBuse\fR targets anywhere
-in the source file, or anywhere in the file tree rooted at \fBTERMINFO\fR (if
-\fBTERMINFO\fR is defined),
-or in the user's \fI$HOME/.terminfo\fR database
+This implementation of \fB@TIC@\fP will find \fBuse\fP targets anywhere
+in the source file,
+or anywhere in the file tree rooted at
+\fI\%TERMINFO\fP
+(if
+\fI\%TERMINFO\fP is defined),
+or in the user's \fI$HOME/.terminfo\fP database
(if it exists),
or (finally) anywhere in the system's file tree of
compiled entries.
.PP
-The error messages from this \fB@TIC@\fR have the same format as GNU C
+The error messages from this \fB@TIC@\fP have the same format as GNU C
error messages, and can be parsed by GNU Emacs's compile facility.
.PP
-The
-\fB\-0\fR,
-\fB\-1\fR,
-\fB\-C\fR,
-\fB\-G\fR,
-\fB\-I\fR,
-\fB\-N\fR,
-\fB\-R\fR,
-\fB\-T\fR,
-\fB\-V\fR,
-\fB\-a\fR,
-\fB\-e\fR,
-\fB\-f\fR,
-\fB\-g\fR,
-\fB\-o\fR,
-\fB\-r\fR,
-\fB\-s\fR,
-\fB\-t\fR and
-\fB\-x\fR
-options
-are not supported under SVr4.
-The SVr4 \fB\-c\fR mode does not report bad use links.
+Aside from \fB\-c\fP and \fB\-v\fP, options are not portable:
+.bP
+Most of @TIC@'s options
+are not supported by SVr4 \fBtic\fP:
+.sp
+.RS
+\fB\-0\fP
+\fB\-1\fP
+\fB\-C\fP
+\fB\-G\fP
+\fB\-I\fP
+\fB\-N\fP
+\fB\-R\fP
+\fB\-T\fP
+\fB\-V\fP
+\fB\-a\fP
+\fB\-e\fP
+\fB\-f\fP
+\fB\-g\fP
+\fB\-o\fP
+\fB\-r\fP
+\fB\-s\fP
+\fB\-t\fP
+\fB\-x\fP
+.RE
+.bP
+The NetBSD \fBtic\fP supports a few of the \fI\%ncurses\fP options
+.sp
+.RS
+\fB\-a\fP
+\fB\-o\fP
+\fB\-x\fP
+.RE
+.IP
+and adds \fB\-S\fP
+(a feature which does the same thing
+as @INFOCMP@'s \fB\-e\fP and \fB\-E\fP options).
+.PP
+The SVr4 \fB\-c\fP mode does not report bad \*(``use=\*('' links.
.PP
System V does not compile entries to or read entries from your
-\fI$HOME/.terminfo\fR database unless TERMINFO is explicitly set to it.
-.SH FILES
-.TP 5
-\fB\*d/?/*\fR
-Compiled terminal description database.
-.SH SEE ALSO
-\fB@INFOCMP@\fR(1M),
-\fB@CAPTOINFO@\fR(1M),
-\fB@INFOTOCAP@\fR(1M),
-\fB@TOE@\fR(1M),
-\fBcurses\fR(3X),
-\fBterm\fR(\*n).
-\fBterminfo\fR(\*n).
+\fI$HOME/.terminfo\fP database unless \fI\%TERMINFO\fP is explicitly set
+to it.
+.SH PORTABILITY
+X/Open Curses, Issue 7 (2009) provides a brief description of \fBtic\fP.
+It lists one option: \fB\-c\fP.
+The omission of \fB\-v\fP is unexpected.
+The change history states that the description is derived from Tru64.
+According to its manual pages, that system also supported the \fB\-v\fP option.
.PP
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
-.SH AUTHOR
+Shortly after Issue 7 was released, Tru64 was discontinued.
+As of 2019, the surviving implementations of \fBtic\fP
+are SVr4 (AIX, HP-UX and Solaris),
+\fI\%ncurses\fP
+and NetBSD curses.
+The SVr4 \fBtic\fP programs all support the \fB\-v\fP option.
+The NetBSD \fBtic\fP program follows X/Open's documentation,
+omitting the \fB\-v\fP option.
+.PP
+The X/Open rationale states that some implementations of \fBtic\fP
+read terminal descriptions from the standard input if the \fIfile\fP
+parameter is omitted.
+None of these implementations do that.
+Further, it comments that some may choose to read from \*(''./terminfo.src\*(''
+but that is obsolescent behavior from SVr2,
+and is not (for example) a documented feature of SVr3.
+.SH HISTORY
+System V Release 2 provided a \fBtic\fP utility.
+It accepted a single option: \fB\-v\fP (optionally followed by a number).
+According to Ross Ridge's comment in \fImytinfo\fP,
+this version of \fBtic\fP was
+unable to represent cancelled capabilities.
+.PP
+System V Release 3 provided a different \fBtic\fP utility,
+written by Pavel Curtis,
+(originally named \*(``compile\*('' in \fIpcurses\fP).
+This added an option \fB\-c\fP to check the file for
+errors, with the caveat that errors in \*(``use=\*('' links
+would not be reported.
+System V Release 3 documented a few warning messages which
+did not appear in \fIpcurses\fP.
+While the program itself was changed little as development
+continued with System V Release 4,
+the table of capabilities grew from 180 (\fIpcurses\fP) to 464 (Solaris).
+.PP
+In early development of \fI\%ncurses\fP (1993),
+Zeyd Ben-Halim used the table from \fImytinfo\fP to
+extend the \fIpcurses\fP table to 469 capabilities
+(456 matched SVr4, 8 were only in SVr4, 13 were not in SVr4).
+Of those 13, 11 were ultimately discarded
+(perhaps to match the draft of X/Open Curses).
+The exceptions were
+\fB\%memory_lock_above\fP and
+\fB\%memory_unlock\fP (see \fB\%user_caps\fP(5)).
+.PP
+Eric Raymond incorporated parts of \fImytinfo\fP into \fI\%ncurses\fP
+to implement the termcap-to-terminfo source conversion,
+and extended that to begin development of
+the corresponding terminfo-to-termcap source conversion,
+Thomas Dickey completed that development over the course of several years.
+.PP
+In 1999, Thomas Dickey added the \fB\-x\fP option
+to support user-defined capabilities.
+.PP
+In 2010, Roy Marples provided a \fBtic\fP program
+and terminfo library for NetBSD.
+That implementation adapts several features from \fI\%ncurses\fP,
+including \fB@TIC@\fP's \fB\-x\fP option.
+.PP
+The \fB\-c\fP option tells \fB@TIC@\fP to check for problems in the
+terminfo source file.
+Continued development provides additional checks:
+.bP
+\fIpcurses\fP had 8 warnings
+.bP
+\fI\%ncurses\fP in 1996 had 16 warnings
+.bP
+Solaris (SVr4) curses has 28 warnings
+.bP
+NetBSD tic in 2019 has 19 warnings.
+.bP
+\fI\%ncurses\fP in 2019 has 96 warnings
+.PP
+The checking done in \fI\%ncurses\fP' \fB@TIC@\fP helps with the
+conversion to termcap,
+as well as pointing out errors and inconsistencies.
+It is also used to ensure consistency with the user-defined capabilities.
+There are 527 distinct capabilities in \fI\%ncurses\fP' terminal
+database;
+128 of those are user-defined.
+.SH AUTHORS
Eric S. Raymond <esr@snark.thyrsus.com>
and
.br
-Thomas E. Dickey <dickey@invisible-island.net>
+Thomas E. Dickey <dickey@invisible\-island.net>
+.SH SEE ALSO
+\fB\%@CAPTOINFO@\fP(1M),
+\fB\%@INFOCMP@\fP(1M),
+\fB\%@INFOTOCAP@\fP(1M),
+\fB\%@TOE@\fP(1M),
+\fB\%curses\fP(3X),
+\fB\%term\fP(5),
+\fB\%terminfo\fP(5),
+\fB\%user_caps\fP(5)
diff --git a/man/toe.1m b/man/toe.1m
index 26af319..c4eba84 100644
--- a/man/toe.1m
+++ b/man/toe.1m
@@ -1,5 +1,7 @@
+'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2011 Free Software Foundation, Inc. *
+.\" Copyright 2019-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 *
.\" copy of this software and associated documentation files (the *
@@ -26,85 +28,215 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: toe.1m,v 1.26 2012/01/01 00:40:51 tom Exp $
-.TH @TOE@ 1M ""
-.ds n 5
+.\" $Id: toe.1m,v 1.68 2024/04/20 18:59:26 tom Exp $
+.TH @TOE@ 1M 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.ie n .ds CW R
+.el \{
+.ie \n(.g .ds CW CR
+.el .ds CW CW
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.ds d @TERMINFO@
.SH NAME
-\fB@TOE@\fR \- table of (terminfo) entries
+\fB\%@TOE@\fP \-
+list table of entries of \fIterminfo\fR terminal types
.SH SYNOPSIS
-\fB@TOE@\fR [\fB\-v\fR[\fIn\fR]] [\fB\-ahsuUV\fR] \fIfile...\fR
-.br
+.B @TOE@
+.RB [ \-ahs ]
+.RB [ \-v\ \c
+.RI [ n ]]
+.RI [ directory
+\&.\|.\|.]
+.PP
+.B @TOE@
+.RB [ \-u | \-U ]
+.I file
+.PP
+.B "@TOE@ \-V"
.SH DESCRIPTION
-.PP
-With no options,
-\fB@TOE@\fR lists all available terminal types by primary name
-with descriptions.
-File arguments specify the directories to be scanned; if no
-such arguments are given,
-your default terminfo directory is scanned.
-If you also specify the \fB\-h\fR option,
-a directory header will be issued as each
-directory is entered.
-.PP
-There are other options intended for use by terminfo file maintainers:
-.TP
-\fB\-a\fR
-report on all of the terminal databases which ncurses would search,
-rather than only the first one that it finds.
+\fB\%@TOE@\fP reports to the standard output stream the (primary) names
+and descriptions of the terminal types available to the \fIterminfo\fP
+library.
+Each \fIdirectory\fP is scanned;
+if none are given,
+\fB\%@TOE@\fP scans the default \fIterminfo\fP directory.
+.SH OPTIONS
+The \fB\-h\fP option can be helpful to observe where \fB\%@TOE@\fP is
+looking for terminal descriptions.
+Other options support maintainers of \fIterminfo\fP terminal
+descriptions.
+.TP 9 \" "-u file" + 2n
+.B \-a
+lists entries from all terminal database directories that \fIterminfo\fP
+would search,
+instead of only the first that it finds.
.IP
-If the \fB\-s\fR is also given, \fB@TOE@\fR
-adds a column to the report,
-showing (like \fBconflict\fP(1)) which entries which
-belong to a given terminal database.
-An "*" marks entries which differ, and "+" marks equivalent entries.
+If
+.B \-s
+is also given,
+\fB\%@TOE@\fP
+additionally reports,
+like \fI\%conflict\fP(1),
+which entries correspond to a given terminal database.
+An \*(``*\*('' marks entries that differ,
+and \*(``+\*('' marks equivalent entries.
+.IP
+Without the \fB\-s\fP option,
+\fB\%@TOE@\fP does not attempt to merge duplicates in its report.
.TP
-\fB\-s\fR
-sort the output by the entry names.
+.B \-h
+writes a heading naming each each directory as it is accessed.
.TP
-\fB\-u\fR \fIfile\fR
-says to write a report to the standard output,
-listing dependencies in the given terminfo/termcap source file.
-The report condenses the `use' relation:
-each line consists of the primary name of a terminal that
-has use capabilities,
-followed by a colon,
-followed by the
-whitespace-separated primary names of all terminals which occur in those use
-capabilities,
-followed by a newline
+.B \-s
+sorts the output by the entry names.
.TP
-\fB\-U\fR \fIfile\fR
-says to write a report to the standard output,
-listing reverse dependencies in the given terminfo/termcap source file.
-The report reverses the `use' relation:
-each line consists of the primary name of a
-terminal that occurs in use capabilities,
-followed by a colon,
-followed by the
-whitespace-separated primary names of all terminals which depend on it,
-followed by a newline.
+.BI \-u\ file
+lists terminal type dependencies in \fIfile\fP,
+a \fIterminfo\fP entry source or \fItermcap\fP database file.
+The report summarizes the \*(``\fBuse\fP\*('' (\fIterminfo\fP) and
+\fBtc\fP (\fItermcap\fP) relations:
+each line comprises the primary name of a terminal type employing
+\fBuse\fP/\fBtc\fP capabilities,
+a colon,
+a space- and tab-separated list of primary names of terminal types thus
+named,
+and a newline.
.TP
-\fB\-v\fR\fIn\fR
-specifies that (verbose) output be written to standard error,
-showing \fB@TOE@\fR's progress.
-The optional parameter \fIn\fR is a number from 1 to 10,
-interpreted as for \fB@TIC@\fR(1M).
+.BI \-U\ file
+lists terminal type reverse dependencies in \fIfile\fP,
+a \fIterminfo\fP entry source or \fItermcap\fP database file.
+The report summarizes the \*(``\fBuse\fP\*('' (\fIterminfo\fP) and
+\fBtc\fP (\fItermcap\fP) reverse relations:
+each line comprises the primary name of a terminal type occurring in
+\fBuse\fP/\fBtc\fP capabilities,
+a colon,
+a space- and tab-separated list of primary names of terminal types
+naming them thus,
+and a newline.
.TP
-\fB\-V\fR
-reports the version of ncurses which was used in this program,
-and exits.
+.BR \-v\ [\c
+.IR n ]
+reports verbose status information to the standard error stream,
+showing \fB\%@TOE@\fP's progress.
+.IP
+The optional parameter \fIn\fP is an integer between 1 and 10 inclusive,
+interpreted as for \fB\%@TIC@\fP(1M).
+If \fI\%ncurses\fP is built without tracing support,
+\fIn\fP is ignored.
+.TP
+\fB\-V\fP
+reports the version of \fI\%ncurses\fP associated
+with this program and exits with a successful status.
.SH FILES
-.TP 5
-\fB\*d/?/*\fR
-Compiled terminal description database.
-.SH SEE ALSO
-\fB@TIC@\fR(1M),
-\fB@INFOCMP@\fR(1M),
-\fB@CAPTOINFO@\fR(1M),
-\fB@INFOTOCAP@\fR(1M),
-\fBcurses\fR(3X),
-\fBterminfo\fR(\*n).
+.TP
+.I \*d
+compiled terminal description database
+.SH PORTABILITY
+\fB\%@TOE@\fP is not provided by other implementations.
+There is no applicable X/Open or POSIX standard for it.
+.SH HISTORY
+\fB\%@TOE@\fP replaces a \fB\-T\fP option that was briefly supported by
+the \fI\%ncurses\fP \fB\%infocmp\fP utility in 1995.
.PP
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
+The \fB\-a\fP and \fB\-s\fP options were added in 2006 and 2011,
+respectively.
+.PP
+The program's name originates with a developer's pun:
+.bP
+\fBtic\fP,
+.bP
+\fBtac\fP (now \fBtack\fP),
+.bP
+\fBtoe\fP.
+.SH EXAMPLES
+When not sorting with the \fB\-s\fP option,
+the \fB\-a\fP option reports all of the names found in all of the
+terminal database directories named in the \fI\%TERMINFO\fP and
+\fI\%TERMINFO_DIRS\fP environment variables.
+.RS 4
+.PP
+.\" toe -a | grep -E '^(xterm|vt)'
+.ft \*(CW
+.TS
+L2 Lx.
+xterm\-color generic color xterm
+xterm\-xfree86 xterm terminal emulator (XFree86)
+xterm\-vt220 xterm emulating vt220
+xterm\-256color xterm with 256 colors
+xterm\-r6 xterm X11R6 version
+xterm\-r5 xterm R5 version
+xterm\-mono monochrome xterm
+xterm T{
+.ad l
+xterm terminal emulator (X Window System)
+T}
+vt220 dec vt220
+vt102 dec vt102
+vt100 dec vt100 (w/advanced video)
+vt52 dec vt52
+.T&
+L.
+\&.\|.\|.
+.TE
+.ft
+.RE
+.PP
+Use the \fB\-a\fP and \fB\-s\fP options together to show where each
+terminal description was found.
+.RS 4
+.PP
+.\" toe -as | grep -E '(^-+>|:.(xterm|vt))'
+.ft \*(CW
+.TS
+Lx.
+\-\-> /etc/terminfo
+\-\-\-\-> /lib/terminfo
+\-\-\-\-\-\-> /usr/share/terminfo
+.TE
+.TS
+L1 L2 Lx.
+\-\-*\-\-\-: vt100 dec vt100 (w/advanced video)
+\-\-*\-\-\-: vt102 dec vt102
+\-\-*\-\-\-: vt220 dec vt220
+\-\-*\-\-\-: vt52 dec vt52
+\-\-*\-\-\-: xterm T{
+.ad l
+xterm terminal emulator (X Window System)
+T}
+\-\-*\-\-\-: xterm\-256color xterm with 256 colors
+\-\-*\-\-\-: xterm\-color generic color xterm
+\-\-*\-\-\-: xterm\-mono monochrome xterm
+\-\-*\-\-\-: xterm\-r5 xterm R5 version
+\-\-*\-\-\-: xterm\-r6 xterm X11R6 version
+\-\-*\-\-\-: xterm\-vt220 xterm emulating vt220
+\-\-*\-\-\-: xterm\-xfree86 T{
+.ad l
+xterm terminal emulator (XFree86)
+T}
+.T&
+L.
+\&.\|.\|.
+.TE
+.ft
+.RE
+.SH SEE ALSO
+\fB\%@CAPTOINFO@\fP(1M),
+\fB\%@INFOCMP@\fP(1M),
+\fB\%@INFOTOCAP@\fP(1M),
+\fB\%@TIC@\fP(1M),
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(5)
diff --git a/man/tput.1 b/man/tput.1
index a1b81bc..eba0733 100644
--- a/man/tput.1
+++ b/man/tput.1
@@ -1,6 +1,7 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2011,2012 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -27,306 +28,977 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tput.1,v 1.32 2012/07/14 21:06:45 tom Exp $
-.TH @TPUT@ 1 ""
+.\" $Id: tput.1,v 1.113 2024/04/20 19:58:50 tom Exp $
+.TH @TPUT@ 1 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.ds d @TERMINFO@
-.ds n 1
.SH NAME
-\fB@TPUT@\fR, \fBreset\fR \- initialize a terminal or query terminfo database
+\fB\%@TPUT@\fP \-
+initialize a terminal, exercise its capabilities, or query \fI\%term\%info\fP database
.SH SYNOPSIS
-\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fIcapname\fR [\fIparms\fR ... ]
-.br
-\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBinit\fR
-.br
-\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBreset\fR
-.br
-\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBlongname\fR
-.br
-\fB@TPUT@ \-S\fR \fB<<\fR
-.br
-\fB@TPUT@ \-V\fR
-.br
+\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP]
+{\fIcap-code\fP [\fIparameter\fP .\|.\|.\&]} .\|.\|.
+.PP
+\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] [\fB\-x\fP] \fBclear\fP
+.PP
+\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBinit\fP
+.PP
+\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fB\%reset\fP
+.PP
+\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fB\%longname\fP
+.PP
+\fB@TPUT@ \-S\fP
+.PP
+\fB@TPUT@ \-V\fP
.SH DESCRIPTION
-The \fB@TPUT@\fR utility uses the \fBterminfo\fR database to make the
-values of terminal-dependent capabilities and information available to
-the shell (see \fBsh\fR(1)), to initialize or reset the terminal, or
-return the long name of the requested terminal type.
-The result depends upon the capability's type:
-.RS
-.TP 5
+\fB\%@TPUT@\fP uses the
+.I \%term\%info
+library and database to make terminal-specific capabilities and
+information available to the shell,
+to initialize or reset the terminal,
+or
+to report a description of the current
+(or specified)
+terminal type.
+Terminal capabilities are accessed by
+.IR cap-code .
+.PP
+\fB\%terminfo\fP(5) discusses terminal capabilities at length
+and presents a complete list of
+.IR cap-codes .
+.PP
+When retrieving capability values,
+the result depends upon the capability's type.
+.TP 9 \" "Boolean" + 2n
+Boolean
+\fB\%@TPUT@\fP sets its exit status to
+.B 0
+if the terminal possesses
+.IR cap-code ,
+and
+.B 1
+if it does not.
+.TP
+numeric
+\fB\%@TPUT@\fP writes
+.IR cap-code 's
+decimal value to the standard output stream if defined
+.RB ( \-1
+if it is not)
+followed by a newline.
+.TP
string
-\fB@TPUT@\fR writes the string to the standard output.
-No trailing newline is supplied.
-.TP
-integer
-\fB@TPUT@\fR writes the decimal value to the standard output,
-with a trailing newline.
-.TP
-boolean
-\fB@TPUT@\fR simply sets the exit code
-(\fB0\fR for TRUE if the terminal has the capability,
-\fB1\fR for FALSE if it does not),
-and writes nothing to the standard output.
-.RE
+\fB\%@TPUT@\fP writes
+.IR cap-code 's
+value to the standard output stream if defined,
+without a trailing newline.
.PP
Before using a value returned on the standard output,
-the application should test the exit code
-(e.g., \fB$?\fR, see \fBsh\fR(1)) to be sure it is \fB0\fR.
-(See the \fBEXIT CODES\fR and \fBDIAGNOSTICS\fR sections.)
-For a complete list of capabilities
-and the \fIcapname\fR associated with each, see \fBterminfo\fR(5).
-.TP
-\fB\-T\fR\fItype\fR
-indicates the \fItype\fR of terminal.
-Normally this option is
-unnecessary, because the default is taken from the environment
-variable \fBTERM\fR.
-If \fB\-T\fR is specified, then the shell
-variables \fBLINES\fR and \fBCOLUMNS\fR will also be ignored.
-.TP
-\fIcapname\fR
-indicates the capability from the \fBterminfo\fR database. When
-\fBtermcap\fR support is compiled in, the \fBtermcap\fR name for
-the capability is also accepted.
-.TP
-\fIparms\fR
-If the capability is a string that takes parameters, the arguments
-\fIparms\fR will be instantiated into the string.
+the application should test \fB\%@TPUT@\fP's exit status
+to be sure it is 0;
+see section \*(``EXIT STATUS\*('' below.
+.SS Operands
+Generally,
+an operand is a
+.IR cap-code ,
+a capability code from the terminal database,
+or a parameter thereto.
+Three others are specially recognized by \fB\%@TPUT@\fP:
+.BR init ,
+.BR \%reset ,
+and
+.BR \%longname .
+Although these resemble capability codes,
+they in fact receive special handling;
+we term them \*(``pseudo-capabilities\*(''.
+.TP 11n \" "longname" + 2n + adjustment for PDF
+.I cap-code
+indicates a capability from the terminal database.
.IP
-Most parameters are numbers.
-Only a few terminfo capabilities require string parameters;
-\fB@TPUT@\fR uses a table to decide which to pass as strings.
-Normally \fB@TPUT@\fR uses \fBtparm\fR (3X) to perform the substitution.
+If
+.I cap-code
+is of string type and takes parameters,
+\fB\%@TPUT@\fP interprets arguments following
+.I cap-code
+as the parameters,
+up to the (fixed) quantity the capability requires.
+.IP
+Most parameters are numeric.
+Only a few terminal capabilities require string parameters;
+\fB\%@TPUT@\fP uses a table to decide which to pass as strings.
+Normally \fB\%@TPUT@\fP uses \fB\%tparm\fP(3X) to perform the
+substitution.
If no parameters are given for the capability,
-\fB@TPUT@\fR writes the string without performing the substitution.
+\fB\%@TPUT@\fP writes the string without performing the substitution.
.TP
-\fB\-S\fR
-allows more than one capability per invocation of \fB@TPUT@\fR. The
-capabilities must be passed to \fB@TPUT@\fR from the standard input
-instead of from the command line (see example).
-Only one \fIcapname\fR is allowed per line.
-The \fB\-S\fR option changes the
-meaning of the \fB0\fR and \fB1\fR boolean and string exit codes (see the
-EXIT CODES section).
-.IP
-Again, \fB@TPUT@\fR uses a table and the presence of parameters in its input
-to decide whether to use \fBtparm\fR (3X),
-and how to interpret the parameters.
-.TP
-\fB\-V\fR
-reports the version of ncurses which was used in this program, and exits.
-.TP
-\fBinit\fR
-If the \fBterminfo\fR database is present and an entry for the user's
-terminal exists (see \fB\-T\fR\fItype\fR, above), the following will
-occur:
+.B init
+initializes the terminal.
+If the terminal database is present
+and an entry for the user's terminal type exists,
+the following occur.
.RS
-.TP
+.TP 5
(1)
-if present, the terminal's initialization strings will be
-output as detailed in the \fBterminfo\fR(5) section on
-.IR "Tabs and Initialization" ,
+\fB\%@TPUT@\fP retrieves the terminal's mode settings.
+It successively tests the file descriptors corresponding to
+.RS
+.bP
+the standard error stream,
+.bP
+the standard output stream,
+.bP
+the standard input stream,
+and
+.bP
+.I \%/dev/tty
+.RE
+.IP
+to obtain terminal settings.
+Having retrieved them,
+\fB\%@TPUT@\fP remembers which descriptor to use for further updates.
.TP
(2)
-any delays (e.g., newline) specified in the entry will
-be set in the tty driver,
+If the terminal dimensions cannot be obtained from the operating system,
+but the environment or terminal type database entry describes them,
+\fB\%@TPUT@\fP updates the operating system's notion of them.
.TP
(3)
-tabs expansion will be turned on or off according to
-the specification in the entry, and
+\fB\%@TPUT@\fP updates the terminal modes.
+.RS
+.bP
+Any delays specified in the entry
+(for example,
+when a newline is sent)
+are set in the terminal driver.
+.bP
+Tab expansion is turned on or off per the specification in the entry,
+and
+.bP
+if tabs are not expanded,
+standard tabs
+(every 8 spaces)
+are set.
+.RE
.TP
(4)
-if tabs are not expanded,
-standard tabs will be set (every 8 spaces).
+If initialization capabilities,
+detailed in subsection \*(``Tabs and Initialization\*('' of
+\fB\%terminfo\fP(5),
+are present,
+\fB\%@TPUT@\fP writes them to the standard output stream.
+.TP
+(5)
+\fB\%@TPUT@\fP flushes the standard output stream.
.RE
.IP
-If an entry does not
-contain the information needed for any of the four above activities,
-that activity will silently be skipped.
+If an entry lacks the information needed for an activity above,
+that activity is silently skipped.
.TP
-\fBreset\fR
-Instead of putting out initialization strings, the terminal's
-reset strings will be output if present (\fBrs1\fR, \fBrs2\fR, \fBrs3\fR, \fBrf\fR).
-If the reset strings are not present, but initialization
-strings are, the initialization strings will be output.
-Otherwise, \fBreset\fR acts identically to \fBinit\fR.
-.TP
-\fBlongname\fR
-If the \fBterminfo\fR database is present and an entry for the
-user's terminal exists (see \fB\-T\fR\fItype\fR above), then the long name
-of the terminal will be put out. The long name is the last
-name in the first line of the terminal's description in the
-\fBterminfo\fR database [see \fBterm\fR(5)].
-.PP
-If \fB@TPUT@\fR is invoked by a link named \fBreset\fR, this has the
-same effect as \fB@TPUT@ reset\fR.
-See \fB@TSET@\fR for comparison, which has similar behavior.
-.SH EXAMPLES
+.B reset
+re-initializes the terminal.
+A reset differs from initialization in two ways.
+.RS
.TP 5
-\fB@TPUT@ init\fR
-Initialize the terminal according to the type of
-terminal in the environmental variable \fBTERM\fR. This
-command should be included in everyone's .profile after
-the environmental variable \fBTERM\fR has been exported, as
-illustrated on the \fBprofile\fR(5) manual page.
-.TP 5
-\fB@TPUT@ \-T5620 reset\fR
-Reset an AT&T 5620 terminal, overriding the type of
-terminal in the environmental variable \fBTERM\fR.
-.TP 5
-\fB@TPUT@ cup 0 0\fR
-Send the sequence to move the cursor to row \fB0\fR, column \fB0\fR
-(the upper left corner of the screen, usually known as the "home"
-cursor position).
-.TP 5
-\fB@TPUT@ clear\fR
-Echo the clear-screen sequence for the current terminal.
-.TP 5
-\fB@TPUT@ cols\fR
-Print the number of columns for the current terminal.
-.TP 5
-\fB@TPUT@ \-T450 cols\fR
-Print the number of columns for the 450 terminal.
-.TP 5
-\fBbold=`@TPUT@ smso` offbold=`@TPUT@ rmso`\fR
-Set the shell variables \fBbold\fR, to begin stand-out mode
-sequence, and \fBoffbold\fR, to end standout mode sequence,
-for the current terminal. This might be followed by a
-prompt: \fBecho "${bold}Please type in your name: ${offbold}\\c"\fR
-.TP 5
-\fB@TPUT@ hc\fR
-Set exit code to indicate if the current terminal is a hard copy terminal.
-.TP 5
-\fB@TPUT@ cup 23 4\fR
-Send the sequence to move the cursor to row 23, column 4.
-.TP 5
-\fB@TPUT@ cup\fR
-Send the terminfo string for cursor-movement, with no parameters substituted.
-.TP 5
-\fB@TPUT@ longname\fR
-Print the long name from the \fBterminfo\fR database for the
-type of terminal specified in the environmental
-variable \fBTERM\fR.
-.PP
-.RS 5
-\fB@TPUT@ \-S <<!\fR
-.br
-\fB> clear\fR
-.br
-\fB> cup 10 10\fR
-.br
-\fB> bold\fR
-.br
-\fB> !\fR
+(1)
+\fB\%@TPUT@\fP sets the the terminal modes to a \*(``sane\*('' state,
+.RS
+.bP
+enabling cooked and echo modes,
+.bP
+disabling cbreak and raw modes,
+.bP
+enabling newline translation,
+and
+.bP
+setting any unset special characters to their default values.
.RE
.TP 5
-\&
-This example shows \fB@TPUT@\fR processing several capabilities in one invocation.
-It clears the screen,
-moves the cursor to position 10, 10
-and turns on bold (extra bright) mode.
-The list is terminated by an exclamation mark (\fB!\fR) on a line by itself.
+(2)
+If any reset capabilities are defined for the terminal type,
+\fB\%@TPUT@\fP writes them to the output stream.
+Otherwise,
+\fB\%@TPUT@\fP uses any defined initialization capabilities.
+Reset capabilities are detailed in subsection
+\*(``Tabs and Initialization\*('' of \fB\%terminfo\fP(5).
+.RE
+.TP
+.B longname
+A
+.I \%term\%info
+entry begins with one or more names by which an application
+can refer to the entry,
+before the list of terminal capabilities.
+The names are separated by \*(``|\*('' characters.
+X/Open Curses terms the last name the \*(``long name\*('',
+and indicates that it may include blanks.
+.IP
+\fB\%@TIC@\fP warns if the last name does not include blanks,
+to accommodate old
+.I \%term\%info
+entries that treated the long name as an optional feature.
+The long name is often referred to as the description field.
+.IP
+If the terminal database is present and an entry for the user's terminal
+type exists,
+\fB\%@TPUT@\fP reports its description to the standard output stream,
+without a trailing newline.
+See \fB\%terminfo\fP(5).
+.PP
+.I Note:
+Redirecting the output of
+.RB \%\*(`` "@TPUT@ init" \*(''
+or
+.RB \%\*(`` "@TPUT@ reset" \*(''
+to a file will capture only part of their actions.
+Changes to the terminal modes are not affected by file descriptor
+redirection,
+since the terminal modes are altered via \fB\%ioctl\fP(2).
+.SS Aliases
+If \fB\%@TPUT@\fP is invoked via link with any of the names
+.BR clear ,
+.BR init ,
+or
+.BR \%reset ,
+it operates as if run with the corresponding (pseudo-)capability
+operand.
+For example,
+executing a link named
+.B \%reset
+that points to \fB\%@TPUT@\fP has the same effect as
+.RB \%\*(`` "@TPUT@ \%reset" \*(''.
+.PP
+This feature was introduced by
+.I \%ncurses
+5.2 in 2000.
+It is rarely used:
+.TP
+.B \%clear
+is a separate program,
+which is both smaller and more frequently executed.
+.TP
+.B init
+has the same name as another program in widespread use.
+.TP
+.B \%reset
+is provided
+by the \fB\%@TSET@\fP(1) utility (also via a link named
+.BR \%reset ")."
+.SS "Terminal Size"
+Besides the pseudo-capabilities
+(such as
+.BR init ),
+\fB\%@TPUT@\fP treats the
+.B lines
+and
+.B cols
+.I cap-codes
+specially:
+it may call \fB\%setupterm\fP(3X) to obtain the terminal size.
+.bP
+First,
+\fB\%@TPUT@\fP attempts to obtain these capabilities from the terminal
+database.
+This generally fails for terminal emulators,
+which lack a fixed window size and thus omit the capabilities.
+.bP
+It then asks the operating system for the terminal's size,
+which generally works,
+unless the connection is via a serial line that
+does not support \*(``NAWS\*('': negotiations about window size.
+.bP
+Finally,
+it inspects the environment variables
+.I LINES
+and
+.IR \%COLUMNS ,
+which may override the terminal size.
+.PP
+If the
+.B \-T
+option is given,
+\fB\%@TPUT@\fP ignores the environment variables by calling
+.BR \%use_tioctl(TRUE) ,
+relying upon the operating system
+(or,
+ultimately,
+the terminal database).
+.SH OPTIONS
+.TP 9n \" "-T type" + 2n
+.B \-S
+retrieves more than one capability per invocation of \fB\%@TPUT@\fP.
+The capabilities must be passed to \fB\%@TPUT@\fP from the standard
+input stream instead of from the command line
+(see section \*(``EXAMPLES\*('' below).
+Only one
+.I cap-code
+is allowed per line.
+The
+.B \-S
+option changes the meanings of the
+.B 0
+and
+.B 1
+exit statuses
+(see section \*(``EXIT STATUS\*('' below).
+.IP
+Some capabilities use string parameters rather than numeric ones.
+\fB\%@TPUT@\fP employs a built-in table and the presence of parameters
+in its input to decide how to interpret them,
+and whether to use \fB\%tparm\fP(3X).
+.TP
+.BI \-T\ type
+indicates the terminal's
+.IR type .
+Normally this option is unnecessary,
+because a default is taken from the
+.I TERM
+environment variable.
+If specified,
+the environment variables
+.I LINES
+and
+.I \%COLUMNS
+are also ignored.
+.TP
+.B \-V
+reports the version of
+.I \%ncurses
+associated with \fB\%@TPUT@\fP,
+and exits with a successful status.
+.TP
+.B \-x
+prevents
+.RB \%\*(`` "@TPUT@ clear" \*(''
+from attempting to clear the scrollback buffer.
+.SH EXIT STATUS
+Normally,
+one should interpret \fB\%@TPUT@\fP's exit statuses as follows.
+.PP
+.if n .ne 3
+.if t .ne 2
+.TS
+Lb Lb
+Lb Lx.
+Status Meaning When \-S Not Specified
+_
+0 Boolean or string capability present
+1 Boolean or numeric capability absent
+2 usage error or no terminal type specified
+3 unrecognized terminal type
+4 unrecognized capability code
+>4 system error (4 + \fBerrno\fP)
+.TE
+.PP
+When the
+.B \-S
+option is used,
+some statuses change meanings.
+.PP
+.if n .ne 4
+.if t .ne 3
+.TS
+Lb Lb
+Lb Lx.
+Status Meaning When \-S Specified
+_
+0 all operands interpreted
+1 unused
+4 some operands not interpreted
+.TE
+.SH ENVIRONMENT
+\fB@TPUT@\fP reads one environment variable.
+.TP 8n \" "TERM" + 2n + adjustment for PDF
+.I TERM
+denotes the terminal type.
+Each terminal type is distinct,
+though many are similar.
+The
+.B \-T
+option overrides its value.
.SH FILES
.TP
-\fB\*d\fR
+.I @DATADIR@/tabset
+tab stop initialization database
+.TP
+.I \*d
compiled terminal description database
-.TP
-\fB@DATADIR@/tabset/*\fR
-tab settings for some terminals, in a format
-appropriate to be output to the terminal (escape
-sequences that set margins and tabs); for more
-information, see the "Tabs and Initialization"
-section of \fBterminfo\fR(5)
-.SH EXIT CODES
-If the \fB\-S\fR option is used,
-\fB@TPUT@\fR checks for errors from each line,
-and if any errors are found, will set the exit code to 4 plus the
-number of lines with errors.
-If no errors are found, the exit code is \fB0\fR.
-No indication of which line failed can be given so
-exit code \fB1\fR will never appear. Exit codes \fB2\fR, \fB3\fR, and
-\fB4\fR retain their usual interpretation.
-If the \fB\-S\fR option is not used,
-the exit code depends on the type of \fIcapname\fR:
-.RS 5
-.TP
-.I boolean
-a value of \fB0\fR is set for TRUE and \fB1\fR for FALSE.
-.TP
-.I string
-a value of \fB0\fR is set if the
-\fIcapname\fR is defined for this terminal \fItype\fR (the value of
-\fIcapname\fR is returned on standard output);
-a value of \fB1\fR is set if \fIcapname\fR
-is not defined for this terminal \fItype\fR
-(nothing is written to standard output).
-.TP
-.I integer
-a value of \fB0\fR is always set,
-whether or not \fIcapname\fR is defined for this terminal \fItype\fR.
-To determine if \fIcapname\fR is defined for this terminal \fItype\fR,
-the user must test the value written to standard output.
-A value of \fB\-1\fR
-means that \fIcapname\fR is not defined for this terminal \fItype\fR.
-.TP
-.I other
-\fBreset\fR or \fBinit\fR may fail to find their respective files.
-In that case, the exit code is set to 4 + \fBerrno\fR.
-.RE
-.PP
-Any other exit code indicates an error; see the DIAGNOSTICS section.
-.SH DIAGNOSTICS
-\fB@TPUT@\fR prints the following error messages and sets the corresponding exit
-codes.
-.PP
-.ne 15
-.TS
-l l.
-exit code error message
-=
-\fB0\fR T{
-(\fIcapname\fR is a numeric variable that is not specified in the
-\fBterminfo\fR(5) database for this terminal type, e.g.
-\fB@TPUT@ \-T450 lines\fR and \fB@TPUT@ \-T2621 xmc\fR)
-T}
-\fB1\fR no error message is printed, see the \fBEXIT CODES\fR section.
-\fB2\fR usage error
-\fB3\fR unknown terminal \fItype\fR or no \fBterminfo\fR database
-\fB4\fR unknown \fBterminfo\fR capability \fIcapname\fR
-\fB>4\fR error occurred in \-S
-=
-.TE
.SH PORTABILITY
-.PP
-The \fBlongname\fR and \fB\-S\fR options, and the parameter-substitution
-features used in the \fBcup\fR example, are not supported in BSD curses or in
-AT&T/USL curses before SVr4.
-.PP
-X/Open documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP.
-In this implementation, \fBclear\fP is part of the \fIcapname\fR support.
-Other implementations of \fB@TPUT@\fP on
-SVr4-based systems such as Solaris, IRIX64 and HPUX
-as well as others such as AIX and Tru64
-provide support for \fIcapname\fR operands.
-.PP
-A few platforms such as FreeBSD and NetBSD recognize termcap names rather
-than terminfo capability names in their respective \fB@TPUT@\fP commands.
-.PP
-Most implementations which provide support for \fIcapname\fR operands
-use the \fItparm\fP function to expand parameters in it.
+Over time
+.I \%ncurses
+\fB\%@TPUT@\fP
+has differed from that of System\ V in two important respects,
+one now mostly historical.
+.bP
+\%\*(``\fB@TPUT@\fP
+.IR cap-code \*(''
+writes to the standard output,
+which need not be a terminal device.
+However,
+the operands that manipulate terminal modes might not use the standard
+output.
+.IP
+System\ V
+.BR tput 's
+.B init
+and
+.B \%reset
+operands use logic from 4.1cBSD
+.BR tset ,
+manipulating terminal modes.
+It checks the same file descriptors
+(and
+.IR \%/dev/tty )
+for association with a terminal device as
+.I \%ncurses
+now does,
+and if none are,
+finally assumes a 1200 baud terminal.
+When updating terminal modes,
+it ignores errors.
+.IP
+Until
+.I \%ncurses
+6.1
+(see section \*(``HISTORY\*('' below),
+\fB\%@TPUT@\fP did not modify terminal modes.
+It now employs a scheme similar to System\ V,
+using functions shared with \fB\%@TSET@\fP
+(and ultimately based on 4.4BSD
+.BR tset ).
+If it is not able to open a terminal
+(for instance,
+when run by \fIcron\fP(1)),
+\fB\%@TPUT@\fP exits with an error status.
+.bP
+System\ V
+.B tput
+assumes that the type of a
+.I cap-code
+operand is numeric if all the characters of its value are decimal
+numbers;
+if they are not,
+it treats
+.I cap-code
+as a string capability.
+.IP
+Most implementations that provide support for
+.I cap-code
+operands use the \fB\%tparm\fP(3X) function to expand its parameters.
That function expects a mixture of numeric and string parameters,
-requiring \fB@TPUT@\fP to know which type to use.
-This implementation uses a table to determine that for
-the standard \fIcapname\fR operands, and an internal library
-function to analyze nonstandard \fIcapname\fR operands.
-Other implementations may simply guess that an operand containing only digits
-is intended to be a number.
-.SH SEE ALSO
-\fB@CLEAR@\fR(1),
-\fBstty\fR(1),
-\fBtabs\fR(\*n),
-\fBterminfo\fR(5),
-\fBcurs_termcap\fR(3X).
+requiring \fB\%@TPUT@\fP to know which type to use.
+.IP
+.I \%ncurses
+\fB\%@TPUT@\fP
+uses a table to determine the parameter types for
+the standard
+.I cap-code
+operands,
+and an internal function to analyze nonstandard
+.I cap-code
+operands.
+.IP
+While more reliable than System\ V's utility,
+a portability problem is introduced by this analysis.
+An OpenBSD developer adapted the internal library function from
+.I \%ncurses
+to port NetBSD's
+.IR termcap -based
+.B tput
+to
+.IR \%term\%info ,
+and modified it to interpret multiple
+.I cap-codes
+(and parameters)
+on the command line.
+Portable applications should not rely upon this feature;
+.I \%ncurses
+offers it to support applications written specifically for OpenBSD.
.PP
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
+This implementation,
+unlike others,
+accepts both
+.I termcap
+and
+.I \%term\%info
+.I cap-codes
+if
+.I termcap
+support is compiled in.
+In that case,
+however,
+the predefined
+.I termcap
+and
+.I \%term\%info
+codes have two
+ambiguities;
+.I \%ncurses
+assumes the
+.I \%term\%info
+code.
+.bP
+The
+.I cap-code
+.B dl
+means
+.B \%delete_line
+to
+.I termcap
+but
+.B \%parm_delete_line
+to
+.IR \%term\%info .
+.I termcap
+uses the code
+.B DL
+for
+.BR \%parm_delete_line .
+.I \%term\%info
+uses the code
+.B dl1
+for
+.BR \%delete_line .
+.bP
+The
+.I cap-code
+.B ed
+means
+.B \%exit_delete_mode
+to
+.I termcap
+but
+.B \%clr_eos
+to
+.IR \%term\%info .
+.I termcap
+uses the code
+.B cd
+for
+.BR \%clr_eos .
+.I \%term\%info
+uses the code
+.B rmdc
+for
+.BR \%exit_delete_mode .
+.PP
+The
+.B \%longname
+operand,
+.B \-S
+option,
+and the parameter-substitution features used in the
+.B cup
+example below,
+were not supported in
+AT&T/USL
+.I curses
+before SVr4 (1989).
+Later,
+4.3BSD-Reno (1990) added support for
+.BR \%longname ,
+.\" longname was added in October 1989.
+and in 1994,
+NetBSD added support for the parameter-substitution features.
+.PP
+IEEE Std 1003.1/The Open Group Base Specifications Issue 7
+(POSIX.1-2008)
+documents only the
+.BR clear ,
+.BR init ,
+and
+.B \%reset
+operands.
+A few observations of interest arise from that selection.
+.bP
+.I \%ncurses
+supports
+.B clear
+as it does any other standard
+.IR cap-code .
+The others
+.RB ( init
+and
+.BR \%longname )
+do not correspond to terminal capabilities.
+.bP
+The
+.B tput
+on SVr4-based systems such as Solaris,
+IRIX64,
+and HP-UX,
+as well as others such as AIX and Tru64,
+also support standard
+.I cap-code
+operands.
+.bP
+A few platforms such as FreeBSD recognize
+.I termcap
+codes rather than
+.I \%term\%info
+capability codes in their respective
+.B tput
+commands.
+Since 2010,
+NetBSD's
+.B tput
+uses
+.I \%term\%info
+codes.
+Before that,
+it
+(like FreeBSD)
+recognized
+.I termcap
+codes.
+.IP
+Beginning in 2021,
+FreeBSD uses
+.I \%ncurses
+.BR tput ,
+configured for both
+.I \%term\%info
+(tested first)
+and
+.I termcap
+(as a fallback).
+.PP
+Because (apparently) all
+.I certified
+Unix systems support the full set of capability codes,
+the reason for documenting only a few may not be apparent.
+.bP
+X/Open Curses Issue 7 documents
+.B tput
+differently,
+with
+.I cap-code
+and the other features used in this implementation.
+.bP
+That is,
+there are two standards for
+.BR tput :
+POSIX (a subset) and X/Open Curses (the full implementation).
+POSIX documents a subset to avoid the complication of including
+X/Open Curses and the terminal capability database.
+.bP
+While it is certainly possible to write a
+.B tput
+program without using
+.IR curses ,
+no system with a
+.I curses
+implementation provides a
+.B tput
+utility that does not also support standard
+.IR cap-codes .
+.PP
+X/Open Curses Issue 7 (2009) is the first version to document utilities.
+However that part of X/Open Curses does not follow existing practice
+(that is,
+System\ V
+.I curses
+behavior).
+.bP
+It assigns exit status 4 to \*(``invalid operand\*('',
+which may have the same meaning as \*(``unknown capability\*(''.
+For instance,
+the source code for
+Solaris
+.I xcurses
+uses the term \*(``invalid\*('' in this case.
+.bP
+It assigns exit status 255 to a numeric variable that is not specified
+in the
+.I \%term\%info
+database.
+That likely is a documentation error,
+mistaking the \*(``\-1\*('' written to the standard output to indicate
+an absent or cancelled numeric capability for an (unsigned) exit status.
+.PP
+The various System\ V implementations
+(AIX,
+HP-UX,
+Solaris)
+use the same exit statuses as
+.IR \%ncurses .
+.PP
+NetBSD
+.I curses
+documents exit statuses that correspond to neither
+.I \%ncurses
+nor X/Open Curses.
+.SH HISTORY
+Bill Joy wrote a
+.B tput
+command during development of 4BSD in October 1980.
+This initial version only cleared the screen,
+and did not ship with official distributions.
+.\" It also exited with backwards exit status (1 on success, 0 on
+.\" failure), and was characterized by Bostic in 1988 as "pretty
+.\" unreasonable".
+.\" See Spinellis's "unix-history-repo" on GitHub.
+.PP
+System\ V developed a different
+.B tput
+command.
+.bP
+SVr2 (1984) provided a rudimentary
+.B tput
+that checked the parameter against each
+predefined capability and returned the corresponding value.
+This version of
+.B tput
+did not use \fB\%tparm\fP(3X) for parameterized capabilities.
+.bP
+SVr3 (1987) replaced that
+.\" SVr3 released in 1987, not 1985.
+.\" https://unix.org/what_is_unix/history_timeline.html
+with a more extensive program
+whose support for
+.B init
+and
+.B \%reset
+operands
+(more than half the program)
+incorporated the
+.B \%reset
+feature of BSD
+.B tset
+written by Eric Allman.
+.bP
+SVr4 (1989) added color initialization by using the
+.B \%orig_colors
+.RB ( oc )
+and
+.B \%orig_pair
+.RB ( op )
+capabilities in its
+.B init
+logic.
+.PP
+Keith Bostic refactored BSD
+.B tput
+for shipment in 4.3BSD-Tahoe (1988),
+then replaced it the next year with a new implementation based on
+System\ V
+.BR tput .
+Bostic's version similarly accepted some parameters named for
+.I \%term\%info
+(pseudo-)capabilities:
+.BR clear ,
+.BR init ,
+.BR \%longname ,
+and
+.BR \%reset .
+However,
+because he had only
+.I termcap
+available,
+it accepted
+.I termcap
+codes for other capabilities.
+Also,
+Bostic's BSD
+.B tput
+did not modify the terminal modes as the earlier BSD
+.B tset
+had done.
+.PP
+At the same time,
+Bostic added a shell script named \*(``clear\*('' that used
+.B tput
+to clear the screen.
+Both of these appeared in 4.4BSD,
+becoming the \*(``modern\*('' BSD implementation of
+.BR tput .
+.PP
+The origin of
+.I \%ncurses
+\fB\%@TPUT@\fP lies outside both System\ V and BSD,
+in Ross Ridge's
+.I \%mytinfo
+package,
+published on
+.I comp.sources.unix
+in December 1992.
+Ridge's program made more sophisticated use of the terminal capabilities
+than the BSD program.
+Eric Raymond used that
+.B tput
+program
+(and other parts of
+.IR \%mytinfo )
+in
+.I \%ncurses
+in June 1995.
+Incorporating the portions dealing with terminal capabilities
+almost without change,
+Raymond made improvements to the way command-line parameters
+were handled.
+.PP
+Before
+.I \%ncurses
+6.1 (2018),
+its \fB\%@TSET@\fP and \fB\%@TPUT@\fP utilities differed.
+.bP
+\fB\%@TSET@\fP was more effective,
+resetting the terminal modes and special characters.
+.bP
+On the other hand,
+\fB\%@TSET@\fP's repertoire of terminal capabilities for resetting the
+terminal was more limited;
+it had only equivalents of
+.B \%reset_1string
+.RB ( rs1 ),
+.B \%reset_2string
+.RB ( rs2 ),
+and
+.B \%reset_file
+.RB ( rf ),
+and not the tab stop and margin update features of \fB\%@TPUT@\fP.
+.PP
+The
+.B \%reset
+program is traditionally an alias for \fB\%@TSET@\fP due to its ability
+to reset terminal modes and special characters.
+.PP
+As of
+.I \%ncurses
+6.1,
+the \*(``reset\*('' features of the two programs are (mostly) the same.
+Two minor differences remain.
+.bP
+The \fB\%@TSET@\fP program waits one second when resetting,
+in case the terminal happens to be a hardware device.
+.bP
+The two programs write the terminal initialization strings
+to different streams;
+that is,
+standard error for \fB\%@TSET@\fP and
+standard output for \fB\%@TPUT@\fP.
+.SH EXAMPLES
+.TP
+.B "@TPUT@ init"
+Initialize the terminal according to the type of
+terminal in the
+.I TERM
+environment variable.
+If the system does not reliably initialize the terminal upon login,
+this command can be included in
+.I \%$HOME/.profile
+after exporting the
+.I TERM
+environment variable.
+.TP
+.B "@TPUT@ \-T5620 reset"
+Reset an AT&T 5620 terminal,
+overriding the terminal type in the
+.I TERM
+environment variable.
+.TP
+.B "@TPUT@ cnorm"
+Set cursor to normal visibility.
+.TP
+.B "@TPUT@ home"
+Move the cursor to row 0,
+column 0:
+the upper left corner of the screen,
+usually known as the \*(``home\*('' cursor position.
+.TP
+.B "@TPUT@ clear"
+Clear the screen:
+write the
+.B \%clear_screen
+capability's value to the standard output stream.
+.TP
+.B "@TPUT@ cols"
+Report the number of columns used by the current terminal type.
+.TP
+.B "@TPUT@ \-Tadm3a cols"
+Report the number of columns used by an ADM-3A terminal.
+.TP
+.B "strong=\(ga@TPUT@ smso\(ga normal=\(ga@TPUT@ rmso\(ga"
+Set shell variables to capability values:
+.B strong
+and
+.BR normal ,
+to begin and end,
+respectively,
+stand-out mode for the terminal.
+One might use these to present a prompt.
+.IP
+.EX
+.RS 14
+printf "${strong}Username:${normal} "
+.RE
+.EE
+.TP
+.B "@TPUT@ hc"
+Indicate via exit status whether the terminal is a hard copy device.
+.TP
+.B "@TPUT@ cup 23 4"
+Move the cursor to row 23,
+column 4.
+.TP
+.B "@TPUT@ cup"
+Report the value of the
+.B \%cursor_address
+.RB ( cup )
+capability
+(used for cursor movement),
+with no parameters substituted.
+.TP
+.B "@TPUT@ longname"
+Report the
+.I \%term\%info
+database's description of the terminal type specified in the
+.I TERM
+environment variable.
+.TP
+.B "@TPUT@ \-S"
+Process multiple capabilities.
+The
+.B \-S
+option can be profitably used with a shell \*(``here document\*(''.
+.IP
+.EX
+.RB $\ "@TPUT@ \-S <<!"
+.RB >\ clear
+.RB >\ "cup 10 10"
+.RB >\ bold
+.RB >\ !
+.EE
+.IP
+The foregoing
+clears the screen,
+moves the cursor to position
+(10, 10)
+and turns on bold
+(extra bright)
+mode.
+.TP
+.B "@TPUT@ clear cup 10 10 bold"
+Perform the same actions as the foregoing
+.RB \%\*(`` "@TPUT@ \-S" \*(''
+example.
+.SH SEE ALSO
+\fB\%@CLEAR@\fP(1),
+\fB\%stty\fP(1),
+\fB\%@TABS@\fP(1),
+\fB\%@TSET@\fP(1),
+\fB\%curs_termcap\fP(3X),
+\fB\%terminfo\fP(5)
diff --git a/man/tset.1 b/man/tset.1
index e151e75..185227d 100644
--- a/man/tset.1
+++ b/man/tset.1
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2011,2013 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2016,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 *
@@ -26,156 +27,173 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tset.1,v 1.29 2013/12/21 22:15:53 tom Exp $
-.TH @TSET@ 1 ""
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: tset.1,v 1.85 2024/04/27 17:57:47 tom Exp $
+.TH @TSET@ 1 2024-04-27 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.ds ^ \(ha
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.ds ^ ^
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
+.
+.ds d @TERMINFO@
.SH NAME
-\fB@TSET@\fR, \fBreset\fR \- terminal initialization
+\fB\%@TSET@\fP,
+\fB\%@RESET@\fP \-
+initialize or reset terminal state
.SH SYNOPSIS
-\fB@TSET@\fR [\fB\-IQVcqrsw\fR] [\fB\-\fR] [\fB\-e\fR \fIch\fR] [\fB\-i\fR \fIch\fR] [\fB\-k\fR \fIch\fR] [\fB\-m\fR \fImapping\fR] [\fIterminal\fR]
+\fB@TSET@\fP [\fB\-IQVcqrsw\fP] [\fB\-\fP] [\fB\-e\fP \fIch\fP] [\fB\-i\fP \fIch\fP] [\fB\-k\fP \fIch\fP] [\fB\-m\fP \fImapping\fP] [\fIterminal-type\fP]
.br
-\fBreset\fR [\fB\-IQVcqrsw\fR] [\fB\-\fR] [\fB\-e\fR \fIch\fR] [\fB\-i\fR \fIch\fR] [\fB\-k\fR \fIch\fR] [\fB\-m\fR \fImapping\fR] [\fIterminal\fR]
+\fB@RESET@\fP [\fB\-IQVcqrsw\fP] [\fB\-\fP] [\fB\-e\fP \fIch\fP] [\fB\-i\fP \fIch\fP] [\fB\-k\fP \fIch\fP] [\fB\-m\fP \fImapping\fP] [\fIterminal-type\fP]
.SH DESCRIPTION
-\&\fBTset\fR initializes terminals.
-\fBTset\fR first determines the type of terminal that you are using.
+.SS "\fItset\fP \(em initialization"
+This program initializes terminals.
+.PP
+First, \fB@TSET@\fP retrieves the current terminal mode settings
+for your terminal.
+It does this by successively testing
+.bP
+the standard error,
+.bP
+standard output,
+.bP
+standard input and
+.bP
+ultimately \*(``/dev/tty\*(''
+.PP
+to obtain terminal settings.
+Having retrieved these settings, \fB@TSET@\fP remembers which
+file descriptor to use when updating settings.
+.PP
+Next, \fB@TSET@\fP determines the type of terminal that you are using.
This determination is done as follows, using the first terminal type found.
.PP
-1. The \fBterminal\fR argument specified on the command line.
+1. The \fBterminal\fP argument specified on the command line.
.PP
-2. The value of the \fBTERM\fR environmental variable.
+2. The value of the \fITERM\fP environment variable.
.PP
3. (BSD systems only.) The terminal type associated with the standard
-error output device in the \fI/etc/ttys\fR file.
-(On System\-V-like UNIXes and systems using that convention,
-\fIgetty\fR does this job by setting
-\fBTERM\fR according to the type passed to it by \fI/etc/inittab\fR.)
+error output device in the \fI/etc/ttys\fP file.
+(On System\ V hosts and systems using that convention,
+\fI\%getty\fP(8) does this job by setting
+\fITERM\fP according to the type passed to it by \fI\%/etc/inittab\fP.)
.PP
-4. The default terminal type, \*(``unknown\*(''.
+4. The default terminal type, \*(``unknown\*('',
+is not suitable for curses applications.
.PP
-If the terminal type was not specified on the command-line, the \fB\-m\fR
-option mappings are then applied (see the section
-.B TERMINAL TYPE MAPPING
-for more information).
+If the terminal type was not specified on the command-line, the \fB\-m\fP
+option mappings are then applied;
+see subsection \*(``Terminal Type Mapping\*(''.
Then, if the terminal type begins with a question mark (\*(``?\*(''), the
-user is prompted for confirmation of the terminal type. An empty
+user is prompted for confirmation of the terminal type.
+An empty
response confirms the type, or, another type can be entered to specify
-a new type. Once the terminal type has been determined, the terminfo
-entry for the terminal is retrieved. If no terminfo entry is found
+a new type.
+Once the terminal type has been determined,
+the terminal description for the terminal is retrieved.
+If no terminal description is found
for the type, the user is prompted for another terminal type.
.PP
-Once the terminfo entry is retrieved, the window size, backspace, interrupt
-and line kill characters (among many other things) are set and the terminal
-and tab initialization strings are sent to the standard error output.
+Once the terminal description is retrieved,
+.bP
+if the \*(``\fB\-w\fP\*('' option is enabled, \fB@TSET@\fP may update
+the terminal's window size.
+.IP
+If the window size cannot be obtained from the operating system,
+but the terminal description
+(or environment,
+e.g.,
+\fILINES\fP and \fI\%COLUMNS\fP variables specify this),
+use this to set the operating system's notion of the window size.
+.bP
+if the \*(``\fB\-c\fP\*('' option is enabled,
+the backspace, interrupt and line kill characters
+(among many other things) are set
+.bP
+unless the \*(``\fB\-I\fP\*('' option is enabled,
+the terminal
+and tab \fIinitialization\fP strings are sent to the standard error output,
+and \fB@TSET@\fP waits one second (in case a hardware reset was issued).
+.bP
Finally, if the erase, interrupt and line kill characters have changed,
or are not set to their default values, their values are displayed to the
standard error output.
-Use the \fB\-c\fP or \fB\-w\fP option to select only the window sizing
-versus the other initialization.
-If neither option is given, both are assumed.
+.SS "\fIreset\fP \(em reinitialization"
+When invoked as \fB@RESET@\fP, \fB@TSET@\fP sets the terminal
+modes to \*(``sane\*('' values:
+.bP
+sets cooked and echo modes,
+.bP
+turns off cbreak and raw modes,
+.bP
+turns on newline translation and
+.bP
+resets any unset special characters to their default values
.PP
-When invoked as \fBreset\fR, \fB@TSET@\fR sets cooked and echo modes,
-turns off cbreak and raw modes, turns on newline translation and
-resets any unset special characters to their default values before
-doing the terminal initialization described above. This is useful
-after a program dies leaving a terminal in an abnormal state. Note,
+before
+doing the terminal initialization described above.
+Also, rather than using the terminal \fIinitialization\fP strings,
+it uses the terminal \fIreset\fP strings.
+.PP
+The \fB@RESET@\fP command is useful
+after a program dies leaving a terminal in an abnormal state:
+.bP
you may have to type
.sp
- \fB<LF>reset<LF>\fR
+ \fI<LF>\fB@RESET@\fI<LF>\fR
.sp
(the line-feed character is normally control-J) to get the terminal
to work, as carriage-return may no longer work in the abnormal state.
+.bP
Also, the terminal will often not echo the command.
-.PP
-The options are as follows:
-.TP 5
-.B \-c
-Set control characters and modes.
-.TP 5
-.B \-e
-Set the erase character to \fIch\fR.
-.TP
-.B \-I
-Do not send the terminal or tab initialization strings to the terminal.
-.TP
-.B \-i
-Set the interrupt character to \fIch\fR.
-.TP
-.B \-k
-Set the line kill character to \fIch\fR.
-.TP
-.B \-m
-Specify a mapping from a port type to a terminal.
-See the section
-.B TERMINAL TYPE MAPPING
-for more information.
-.TP
-.B \-Q
-Do not display any values for the erase, interrupt and line kill characters.
-Normally \fB@TSET@\fR displays the values for control characters which
-differ from the system's default values.
-.TP
-.B \-q
-The terminal type is displayed to the standard output, and the terminal is
-not initialized in any way. The option `\-' by itself is equivalent but
-archaic.
-.TP
-.B \-r
-Print the terminal type to the standard error output.
-.TP
-.B \-s
-Print the sequence of shell commands to initialize the environment variable
-\fBTERM\fR to the standard output.
-See the section
-.B SETTING THE ENVIRONMENT
-for details.
-.TP
-.B \-V
-reports the version of ncurses which was used in this program, and exits.
-.TP
-.B \-w
-Resize the window to match the size deduced via \fBsetupterm\fP.
-Normally this has no effect,
-unless \fBsetupterm\fP is not able to detect the window size.
-.PP
-The arguments for the \fB\-e\fR, \fB\-i\fR, and \fB\-k\fR
-options may either be entered as actual characters or by using the `hat'
-notation, i.e., control-h may be specified as \*(``^H\*('' or \*(``^h\*(''.
-.
-.SH SETTING THE ENVIRONMENT
+.SS "Setting the Environment"
It is often desirable to enter the terminal type and information about
the terminal's capabilities into the shell's environment.
-This is done using the \fB\-s\fR option.
+This is done using the \fB\-s\fP option.
.PP
-When the \fB\-s\fR option is specified, the commands to enter the information
-into the shell's environment are written to the standard output. If
-the \fBSHELL\fR environmental variable ends in \*(``csh\*('', the commands
-are for \fBcsh\fR, otherwise, they are for \fBsh\fR.
-Note, the \fBcsh\fR commands set and unset the shell variable
-\fBnoglob\fR, leaving it unset. The following line in the \fB.login\fR
-or \fB.profile\fR files will initialize the environment correctly:
+When the \fB\-s\fP option is specified, the commands to enter the information
+into the shell's environment are written to the standard output.
+If the \fISHELL\fP environment variable ends in \*(``csh\*('',
+the commands
+are for \fIcsh\fP(1),
+otherwise,
+they are for \fIsh\fP(1).
+The \fIcsh\fP commands set and unset the shell variable \fBnoglob\fP,
+leaving it unset.
+The following line in the \fB.login\fP
+or \fB.profile\fP files will initialize the environment correctly:
.sp
- eval \`@TSET@ \-s options ... \`
+ eval \(ga@TSET@ \-s options ... \(ga
.
-.SH TERMINAL TYPE MAPPING
+.SS "Terminal Type Mapping"
When the terminal is not hardwired into the system (or the current
system information is incorrect) the terminal type derived from the
-\fI/etc/ttys\fR file or the \fBTERM\fR environmental variable is often
-something generic like \fBnetwork\fR, \fBdialup\fR, or \fBunknown\fR.
-When \fB@TSET@\fR is used in a startup script it is often desirable to
+\fI/etc/ttys\fP file or the \fITERM\fP environment variable is often
+something generic like \fBnetwork\fP, \fBdialup\fP, or \fBunknown\fP.
+When \fB@TSET@\fP is used in a startup script it is often desirable to
provide information about the type of terminal used on such ports.
.PP
-The purpose of the \fB\-m\fR option is to map
+The \fB\-m\fP options maps
from some set of conditions to a terminal type, that is, to
-tell \fB@TSET@\fR
+tell \fB@TSET@\fP
\*(``If I'm on this port at a particular speed,
guess that I'm on that kind of terminal\*(''.
.PP
-The argument to the \fB\-m\fR option consists of an optional port type, an
+The argument to the \fB\-m\fP option consists of an optional port type, an
optional operator, an optional baud rate specification, an optional
-colon (\*(``:\*('') character and a terminal type. The port type is a
+colon (\*(``:\*('') character and a terminal type.
+The port type is a
string (delimited by either the operator or the colon character).
The operator may be any combination of
\*(``>\*('',
@@ -190,111 +208,257 @@
of the standard error output (which should be the control terminal).
The terminal type is a string.
.PP
-If the terminal type is not specified on the command line, the \fB\-m\fR
-mappings are applied to the terminal type. If the port type and baud
+If the terminal type is not specified on the command line, the \fB\-m\fP
+mappings are applied to the terminal type.
+If the port type and baud
rate match the mapping, the terminal type specified in the mapping
-replaces the current type. If more than one mapping is specified, the
+replaces the current type.
+If more than one mapping is specified, the
first applicable mapping is used.
.PP
-For example, consider the following mapping: \fBdialup>9600:vt100\fR.
+For example, consider the following mapping: \fBdialup>9600:vt100\fP.
The port type is dialup , the operator is >, the baud rate
-specification is 9600, and the terminal type is vt100. The result of
-this mapping is to specify that if the terminal type is \fBdialup\fR,
+specification is 9600, and the terminal type is vt100.
+The result of
+this mapping is to specify that if the terminal type is \fBdialup\fP,
and the baud rate is greater than 9600 baud, a terminal type of
-\fBvt100\fR will be used.
+\fBvt100\fP will be used.
.PP
If no baud rate is specified, the terminal type will match any baud rate.
If no port type is specified, the terminal type will match any port type.
-For example, \fB\-m dialup:vt100 \-m :?xterm\fR
+For example, \fB\-m dialup:vt100 \-m :?xterm\fP
will cause any dialup port, regardless of baud rate, to match the terminal
type vt100, and any non-dialup port type to match the terminal type ?xterm.
Note, because of the leading question mark, the user will be
queried on a default port as to whether they are actually using an xterm
terminal.
.PP
-No whitespace characters are permitted in the \fB\-m\fR option argument.
+No whitespace characters are permitted in the \fB\-m\fP option argument.
Also, to avoid problems with meta-characters, it is suggested that the
-entire \fB\-m\fR option argument be placed within single quote characters,
-and that \fBcsh\fR users insert a backslash character (\*(``\e\*('') before
-any exclamation marks (\*(``!\*('').
-.SH HISTORY
-The \fB@TSET@\fR command appeared in BSD 3.0. The \fBncurses\fR implementation
-was lightly adapted from the 4.4BSD sources for a terminfo environment by Eric
-S. Raymond <esr@snark.thyrsus.com>.
-.SH COMPATIBILITY
-The \fB@TSET@\fR utility has been provided for backward-compatibility with BSD
-environments (under most modern UNIXes, \fB/etc/inittab\fR and \fIgetty\fR(1)
-can set \fBTERM\fR appropriately for each dial-up line; this obviates what was
-\fB@TSET@\fR's most important use). This implementation behaves like 4.4BSD
-tset, with a few exceptions specified here.
+entire \fB\-m\fP option argument be placed within single quote characters,
+and that \fIcsh\fP users insert a backslash character (\*(``\e\*('')
+before any exclamation marks (\*(``!\*('').
+.SH OPTIONS
+The options are as follows:
+.TP 5
+.B \-c
+Set control characters and modes.
+.TP 5
+.BI \-e\ ch
+Set the erase character to \fIch\fP.
+.TP
+.B \-I
+Do not send the terminal or tab initialization strings to the terminal.
+.TP
+.BI \-i\ ch
+Set the interrupt character to \fIch\fP.
+.TP
+.BI \-k\ ch
+Set the line kill character to \fIch\fP.
+.TP
+.BI \-m\ mapping
+Specify a mapping from a port type to a terminal;
+see subsection \*(``Terminal Type Mapping\*(''.
+.TP
+.B \-Q
+Do not display any values for the erase, interrupt and line kill characters.
+Normally \fB@TSET@\fP displays the values for control characters which
+differ from the system's default values.
+.TP
+.B \-q
+The terminal type is displayed to the standard output, and the terminal is
+not initialized in any way.
+The option \*(``\-\*('' by itself is equivalent but archaic.
+.TP
+.B \-r
+Print the terminal type to the standard error output.
+.TP
+.B \-s
+Print the sequence of shell commands to initialize the environment variable
+\fITERM\fP to the standard output;
+see subsection \*(``Setting the Environment\*(''.
+.TP
+.B \-V
+reports the version of \fI\%ncurses\fP which was used in this program,
+and exits.
+.TP
+.B \-w
+Resize the window to match the size deduced via \fBsetupterm\fP(3X).
+Normally this has no effect,
+unless \fBsetupterm\fP is not able to detect the window size.
.PP
-The \fB\-S\fR option of BSD tset no longer works;
-it prints an error message to stderr and dies.
-The \fB\-s\fR option only sets \fBTERM\fR, not \fBTERMCAP\fP.
-Both of these changes are because the \fBTERMCAP\fR variable
-is no longer supported under terminfo-based \fBncurses\fR,
-which makes \fB@TSET@ \-S\fR useless
-(we made it die noisily rather than silently induce lossage).
+The arguments for the \fB\-e\fP, \fB\-i\fP, and \fB\-k\fP
+options may either be entered as actual characters
+or by using the \*(``hat\*(''
+notation, i.e., control-h may be specified as \*(``\*^H\*('' or \*(``\*^h\*(''.
.PP
-There was an undocumented 4.4BSD feature that invoking tset via a link named
-`TSET` (or via any other name beginning with an upper-case letter) set the
-terminal to use upper-case only. This feature has been omitted.
+If neither \fB\-c\fP or \fB\-w\fP is given, both options are assumed.
+.SH ENVIRONMENT
+The \fB@TSET@\fP command uses these environment variables:
+.TP 5
+.I SHELL
+tells \fB@TSET@\fP whether to initialize \fITERM\fP using \fIsh\fP(1) or
+\fIcsh\fP(1) syntax.
+.TP 5
+.I TERM
+Denotes your terminal type.
+Each terminal type is distinct, though many are similar.
+.TP 5
+.I TERMCAP
+may denote the location of a termcap database.
+If it is not an absolute pathname, e.g., begins with a \*(``/\*('',
+\fB@TSET@\fP removes the variable from the environment before looking
+for the terminal description.
+.SH FILES
+.TP
+.I /etc/ttys
+system port name to terminal type mapping database (BSD versions only).
+.TP
+.I \*d
+compiled terminal description database directory
+.SH PORTABILITY
+Neither IEEE Std 1003.1/The Open Group Base Specifications Issue 7
+(POSIX.1-2008) nor
+X/Open Curses Issue 7 documents \fB@TSET@\fP or \fB@RESET@\fP.
.PP
-The \fB\-A\fR, \fB\-E\fR, \fB\-h\fR, \fB\-u\fR and \fB\-v\fR
-options were deleted from the \fB@TSET@\fR
+The AT&T \fBtput\fP utility (AIX, HP-UX, Solaris)
+incorporated the terminal-mode manipulation as well as termcap-based features
+such as resetting tabstops from \fBtset\fP in BSD (4.1c),
+presumably with the intention of making \fBtset\fP obsolete.
+However, each of those systems still provides \fBtset\fP.
+In fact, the commonly-used \fBreset\fP utility
+is always an alias for \fBtset\fP.
+.PP
+The \fB\%@TSET@\fP utility provides backward compatibility with BSD
+environments;
+under most modern Unices,
+\fI\%/etc/inittab\fP and \fI\%getty\fP(8) can set \fITERM\fP
+appropriately for each dial-up line,
+obviating what was \fB\%@TSET@\fP's most important use.
+This implementation behaves like 4.4BSD \fBtset\fP,
+with a few exceptions we shall consider now.
+.PP
+A few options are different
+because the \fI\%TERMCAP\fP variable
+is no longer supported under terminfo-based \fI\%ncurses\fP:
+.bP
+The \fB\-S\fP option of BSD \fBtset\fP no longer works;
+it prints an error message to the standard error and dies.
+.bP
+The \fB\-s\fP option only sets \fITERM\fP,
+not \fI\%TERMCAP\fP.
+.PP
+There was an undocumented 4.4BSD feature
+that invoking \fBtset\fP via a link named
+\*(``TSET\*('' (or via any other name beginning with an upper-case letter)
+set the terminal to use upper-case only.
+This feature has been omitted.
+.PP
+The \fB\-A\fP, \fB\-E\fP, \fB\-h\fP, \fB\-u\fP and \fB\-v\fP
+options were deleted from the \fB@TSET@\fP
utility in 4.4BSD.
None of them were documented in 4.3BSD and all are
of limited utility at best.
-The \fB\-a\fR, \fB\-d\fR, and \fB\-p\fR options are similarly
+The \fB\-a\fP, \fB\-d\fP, and \fB\-p\fP options are similarly
not documented or useful, but were retained as they appear to be in
-widespread use. It is strongly recommended that any usage of these
-three options be changed to use the \fB\-m\fR option instead.
-The \fB\-n\fP option remains, but has no effect.
-The \fB\-adnp\fR options are therefore omitted from the usage summary above.
+widespread use.
+It is strongly recommended that any usage of these
+three options be changed to use the \fB\-m\fP option instead.
+The \fB\-a\fP, \fB\-d\fP, and \fB\-p\fP options
+are therefore omitted from the usage summary above.
.PP
-It is still permissible to specify the \fB\-e\fR, \fB\-i\fR,
-and \fB\-k\fR options without arguments,
+Very old systems, e.g., 3BSD, used a different terminal driver which
+was replaced in 4BSD in the early 1980s.
+To accommodate these older systems, the 4BSD \fB@TSET@\fP provided a
+\fB\-n\fP option to specify that the new terminal driver should be used.
+This implementation does not provide that choice.
+.PP
+It is still permissible to specify the \fB\-e\fP, \fB\-i\fP,
+and \fB\-k\fP options without arguments,
although it is strongly recommended that such usage be fixed to
explicitly specify the character.
.PP
As of 4.4BSD,
-executing \fB@TSET@\fR as \fBreset\fR no longer implies the \fB\-Q\fR option.
-Also, the interaction between the \- option and the \fIterminal\fR
-argument in some historic implementations of \fB@TSET@\fR has been removed.
-.SH ENVIRONMENT
-The \fB@TSET@\fR command uses these environment variables:
-.TP 5
-SHELL
-tells \fB@TSET@\fP whether to initialize \fBTERM\fP using \fBsh\fP or
-\fBcsh\fP syntax.
-.TP 5
-TERM
-Denotes your terminal type.
-Each terminal type is distinct, though many are similar.
-.TP 5
-TERMCAP
-may denote the location of a termcap database.
-If it is not an absolute pathname, e.g., begins with a `/',
-\fB@TSET@\fP removes the variable from the environment before looking
-for the terminal description.
-.SH FILES
-.TP 5
-/etc/ttys
-system port name to terminal type mapping database (BSD versions only).
-.TP
-@TERMINFO@
-terminal capability database
-.SH SEE ALSO
-.hy 0
-csh(1),
-sh(1),
-stty(1),
-curs_terminfo(3X),
-tty(4),
-terminfo(5),
-ttys(5),
-environ(7)
-.hy
+executing \fB@TSET@\fP as \fB@RESET@\fP no longer implies the \fB\-Q\fP option.
+Also, the interaction between the \- option and the \fIterminal\fP
+argument in some historic implementations of \fB@TSET@\fP has been removed.
.PP
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
+The \fB\-c\fP and \fB\-w\fP options are not found in earlier implementations.
+However, a different window size-change feature was provided in 4.4BSD.
+.bP
+In 4.4BSD, \fBtset\fP uses the window size from the termcap description
+to set the window size if \fBtset\fP is not able to obtain the window
+size from the operating system.
+.bP
+In \fI\%ncurses\fP, \fB@TSET@\fP obtains the window size using
+\fB\%setupterm\fP(3X), which may be from
+the operating system,
+the \fILINES\fP and \fICOLUMNS\fP environment variables or
+the terminal description.
+.PP
+Obtaining the window size from a terminal's type description is common
+to both implementations,
+but considered obsolescent.
+Its only practical use is for hardware terminals.
+Generally,
+the window size will remain uninitialized only if there were a problem
+obtaining the value from the operating system
+(and \fB\%setupterm\fP would still fail).
+The \fILINES\fP and \fI\%COLUMNS\fP environment variables
+may thus be useful for working around window-size problems,
+but have the drawback that if the window is resized,
+their values must be recomputed and reassigned.
+The \fI\%resize\fP(1) program distributed with
+\fI\%xterm\fP(1) assists this activity.
+.SH HISTORY
+A \fB\%reset\fP command written by Kurt Shoens appeared in 1BSD
+(March 1978).
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/s6/reset.c
+It set the \fIerase\fP and \fIkill\fP characters
+to \fB\*^H\fP (backspace) and \fB@\fP respectively.
+Mark Horton improved this \fB\%reset\fP in 3BSD
+(October 1979),
+adding \fIintr\fP,
+\fIquit\fP,
+\fIstart\fP/\fIstop\fP,
+and \fIeof\fP
+characters as well as changing the program to avoid modifying any user
+settings.
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/cmd/\
+.\" reset.c
+That version of \fB\%reset\fP did not use \fI\%termcap\fP.
+.PP
+Eric Allman wrote a distinct \fBtset\fP command for 1BSD,
+using a forerunner of \fI\%termcap\fP called \fI\%ttycap\fP.
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/s6/tset.c
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/man7/ttycap.7
+Allman's comments in the source code indicate
+that he began work in October 1977,
+continuing development over the next few years.
+By late 1979,
+it had migrated to \fI\%termcap\fP and handled the \fI\%TERMCAP\fP
+variable.
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/cmd/\
+.\" tset/tset.c
+Later comments indicate that \fBtset\fP was modified in September 1980
+to use logic copied from the 3BSD \*(``reset\*('' program when it was
+invoked as \fB\%reset\fP.
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=2.9BSD/usr/src/ucb/\
+.\" tset/tset.c
+This version appeared in 4.1cBSD, \" and backported to 2.9BSD
+late in 1982.
+Other developers such as Keith Bostic and Jim Bloom continued to modify
+\fBtset\fP until 4.4BSD was released in 1993.
+.PP
+The \fI\%ncurses\fP implementation was lightly adapted from the 4.4BSD
+sources to use the \fI\%terminfo\fP API by Eric S.\& Raymond
+<esr@snark.thyrsus.com>.
+.SH SEE ALSO
+\fB\%csh\fP(1),
+\fB\%sh\fP(1),
+\fB\%stty\fP(1),
+\fB\%curs_terminfo\fP(3X),
+\fB\%tty\fP(4),
+\fB\%terminfo\fP(5),
+\fB\%ttys\fP(5),
+\fB\%environ\fP(7)
diff --git a/man/user_caps.5 b/man/user_caps.5
new file mode 100644
index 0000000..219bbf5
--- /dev/null
+++ b/man/user_caps.5
@@ -0,0 +1,464 @@
+'\" t
+.\"***************************************************************************
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 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 *
+.\" "Software"), to deal in the Software without restriction, including *
+.\" without limitation the rights to use, copy, modify, merge, publish, *
+.\" distribute, distribute with modifications, sublicense, and/or sell *
+.\" copies of the Software, and to permit persons to whom the Software is *
+.\" furnished to do so, subject to the following conditions: *
+.\" *
+.\" The above copyright notice and this permission notice shall be included *
+.\" in all copies or substantial portions of the Software. *
+.\" *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
+.\" *
+.\" Except as contained in this notice, the name(s) of the above copyright *
+.\" holders shall not be used in advertising or otherwise to promote the *
+.\" sale, use or other dealings in this Software without prior written *
+.\" authorization. *
+.\"***************************************************************************
+.\"
+.\" $Id: user_caps.5,v 1.49 2024/03/16 15:35:01 tom Exp $
+.TH user_caps 5 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
+.SH NAME
+user_caps \-
+user-defined \fIterminfo\fR capability format
+.SH SYNOPSIS
+.B @INFOCMP@ \-x
+.PP
+.B @TIC@ \-x
+.SH DESCRIPTION
+.SS Background
+Before \fI\%ncurses\fP 5.0,
+terminfo databases used a \fIfixed repertoire\fP of terminal
+capabilities designed for the SVr2 terminal database in 1984,
+and extended in stages through SVr4 (1989),
+and standardized in the Single Unix Specification beginning in 1995.
+.PP
+Most of the \fIextensions\fP in this fixed repertoire were additions
+to the tables of Boolean, numeric and string capabilities.
+Rather than change the meaning of an existing capability, a new name was added.
+The terminfo database uses a binary format; binary compatibility was
+ensured by using a header which gave the number of items in the
+tables for each type of capability.
+The standardization was incomplete:
+.bP
+The \fIbinary format\fP itself is not described
+in the X/Open Curses documentation.
+Only the \fIsource format\fP is described.
+.IP
+Library developers rely upon the SVr4 documentation,
+and reverse-engineering the compiled terminfo files to match the binary format.
+.bP
+Lacking a standard for the binary format, most implementations
+copy the SVr2 binary format, which uses 16-bit signed integers,
+and is limited to 4096-byte entries.
+.IP
+The format cannot represent very large numeric capabilities,
+nor can it represent large numbers of special keyboard definitions.
+.bP
+The tables of capability names differ between implementations.
+.IP
+Although they \fImay\fP provide all of the standard capability names,
+the position in the tables differs because some features were added as needed,
+while others were added (out of order) to comply with X/Open Curses.
+.IP
+While \fI\%ncurses\fP' repertoire of predefined capabilities is closest
+to Solaris,
+Solaris's terminfo database has a few differences from
+the list published by X/Open Curses.
+For example,
+\fI\%ncurses\fP can be configured with tables which match the terminal
+databases for AIX, HP-UX or OSF/1,
+rather than the default Solaris-like configuration.
+.bP
+In SVr4 curses and \fI\%ncurses\fP,
+the terminal database is defined at compile-time using a text file
+which lists the different terminal capabilities.
+.IP
+In principle, the text-file can be extended,
+but doing this requires recompiling and reinstalling the library.
+The text-file used in \fI\%ncurses\fP for terminal capabilities includes
+details for various systems past the documented X/Open Curses features.
+For example, \fI\%ncurses\fP supports these capabilities in each configuration:
+.RS 8
+.TP 5
+memory_lock
+(meml)
+lock memory above cursor
+.TP 5
+memory_unlock
+(memu)
+unlock memory
+.TP 5
+box_chars_1
+(box1)
+box characters primary set
+.RE
+.IP
+The memory lock/unlock capabilities were included because they were used
+in the X11R6 terminal description for \fBxterm\fP(1).
+The \fIbox1\fP capability is used in @TIC@ to help with terminal descriptions
+written for AIX.
+.PP
+During the 1990s, some users were reluctant to use terminfo
+in spite of its performance advantages over termcap:
+.bP
+The fixed repertoire prevented users from adding features
+for unanticipated terminal improvements
+(or required them to reuse existing capabilities as a workaround).
+.bP
+The limitation to 16-bit signed integers was also mentioned.
+Because termcap stores everything as a string,
+it could represent larger numbers.
+.PP
+Although termcap's extensibility was rarely used
+(it was never the \fIspeaker\fP who had actually used the feature),
+the criticism had a point.
+\fI\%ncurses\fP 5.0 provided a way to detect nonstandard capabilities,
+determine their
+type and optionally store and retrieve them in a way which did not interfere
+with other applications.
+These are referred to as \fIuser-defined capabilities\fP because no
+modifications to the toolset's predefined capability names are needed.
+.PP
+The \fI\%ncurses\fP utilities \fB@TIC@\fP and \fB@INFOCMP@\fP have a
+command-line option \*(``\-x\*('' to control whether the nonstandard
+capabilities are stored or retrieved.
+A library function \fBuse_extended_names\fP
+is provided for the same purpose.
+.PP
+When compiling a terminal database, if \*(``\-x\*('' is set,
+\fB@TIC@\fP will store a user-defined capability if the capability name is not
+one of the predefined names.
+.PP
+Because \fI\%ncurses\fP provides a termcap library interface,
+these user-defined capabilities may be visible to termcap applications:
+.bP
+The termcap interface (like all implementations of termcap)
+requires that the capability names are 2-characters.
+.IP
+When the capability is simple enough for use in a termcap application,
+it is provided as a 2-character name.
+.bP
+There are other
+user-defined capabilities which refer to features not usable in termcap,
+e.g., parameterized strings that use more than two parameters
+or use more than the trivial expression support provided by termcap.
+For these, the terminfo database should have only capability names with
+3 or more characters.
+.bP
+Some terminals can send distinct strings for special keys (cursor-,
+keypad- or function-keys) depending on modifier keys (shift, control, etc.).
+While terminfo and termcap have a set of 60 predefined function-key names,
+to which a series of keys can be assigned,
+that is insufficient for more than a dozen keys multiplied by more than
+a couple of modifier combinations.
+The \fI\%ncurses\fP database uses a convention based on \fBxterm\fP(1)
+to provide extended special-key names.
+.IP
+Fitting that into termcap's limitation of 2-character names
+would be pointless.
+These extended keys are available only with terminfo.
+.SS "Recognized Capabilities"
+The \fI\%ncurses\fP library uses the user-definable capabilities.
+While the terminfo database may have other extensions,
+\fI\%ncurses\fP makes explicit checks for these:
+.RS 3
+.TP 3
+AX
+\fIBoolean\fP, asserts that the terminal interprets SGR 39 and SGR 49
+by resetting the foreground and background color, respectively, to the default.
+.IP
+This is a feature recognized by the \fBscreen\fP program as well.
+.TP 3
+E3
+\fIstring\fP, tells how to clear the terminal's scrollback buffer.
+When present, the \fBclear\fP(1) program sends this before clearing
+the terminal.
+.IP
+The command \*(``\fBtput clear\fP\*('' does the same thing.
+.TP 3
+NQ
+\fIBoolean\fP,
+used to suppress a consistency check in @TIC@ for the \fI\%ncurses\fP
+capabilities
+in user6 through user9 (u6, u7, u8 and u9)
+which tell how to query the terminal's cursor position
+and its device attributes.
+.TP 3
+RGB
+\fIBoolean\fP, \fInumber\fP \fBor\fP \fIstring\fP,
+used to assert that the
+\fBset_a_foreground\fP and
+\fBset_a_background\fP capabilities correspond to \fIdirect colors\fP,
+using an RGB (red/green/blue) convention.
+This capability allows the \fBcolor_content\fP function to
+return appropriate values without requiring the application
+to initialize colors using \fBinit_color\fP.
+.IP
+The capability type determines the values which \fI\%ncurses\fP sees:
+.RS 3
+.TP 3
+\fIBoolean\fP
+implies that the number of bits for red, green and blue are the same.
+Using the maximum number of colors,
+\fI\%ncurses\fP adds two,
+divides that sum by three,
+and assigns the result to red,
+green and blue in that order.
+.IP
+If the number of bits needed for the number of colors is not a multiple
+of three, the blue (and green) components lose in comparison to red.
+.TP 3
+\fInumber\fP
+tells \fI\%ncurses\fP what result to add to red, green and blue.
+If \fI\%ncurses\fP runs out of bits,
+blue (and green) lose just as in the \fIBoolean\fP case.
+.TP 3
+\fIstring\fP
+explicitly list the number of bits used for red, green and blue components
+as a slash-separated list of decimal integers.
+.RE
+.IP
+Because there are several RGB encodings in use,
+applications which make assumptions about the number of bits per color
+are unlikely to work reliably.
+As a trivial case, for example, one could define \fBRGB#1\fP
+to represent the standard eight ANSI colors, i.e., one bit per color.
+.TP 3
+U8
+\fInumber\fP,
+asserts that \fI\%ncurses\fP must use Unicode values for line-drawing
+characters,
+and that it should ignore the alternate character set capabilities
+when the locale uses UTF-8 encoding.
+For more information, see the discussion of
+\fBNCURSES_NO_UTF8_ACS\fP in \fB\%ncurses\fP(3X).
+.IP
+Set this capability to a nonzero value to enable it.
+.TP 3
+XM
+\fIstring\fP,
+override \fI\%ncurses\fP's built-in string which
+enables/disables \fBxterm\fP(1) mouse mode.
+.IP
+\fI\%ncurses\fP sends a character sequence to the terminal to initialize mouse mode,
+and when the user clicks the mouse buttons or (in certain modes) moves the
+mouse, handles the characters sent back by the terminal to tell it what
+was done with the mouse.
+.IP
+The mouse protocol is enabled when
+the \fImask\fP passed in the \fBmousemask\fP function is nonzero.
+By default,
+\fI\%ncurses\fP handles the responses for the X11 xterm mouse protocol.
+It also knows about the \fISGR 1006\fP xterm mouse protocol,
+but must to be told to look for this specifically.
+It will not be able to guess which mode is used,
+because the responses are enough alike that only confusion would result.
+.IP
+The \fBXM\fP capability has a single parameter.
+If nonzero, the mouse protocol should be enabled.
+If zero, the mouse protocol should be disabled.
+\fI\%ncurses\fP inspects this capability if it is present,
+to see whether the 1006 protocol is used.
+If so, it expects the responses to use the \fISGR 1006\fP xterm mouse protocol.
+.IP
+The xterm mouse protocol is used by other terminal emulators.
+The terminal database uses building-blocks for the various xterm mouse
+protocols which can be used in customized terminal descriptions.
+.IP
+The terminal database building blocks for this mouse
+feature also have an experimental capability \fIxm\fP.
+The \*(``xm\*('' capability describes the mouse response.
+Currently there is no interpreter which would use this
+information to make the mouse support completely data-driven.
+.IP
+\fIxm\fP shows the format of the mouse responses.
+In this experimental capability, the parameters are
+.RS 5
+.TP 5
+.I p1
+y-ordinate
+.TP 5
+.I p2
+x-ordinate
+.TP 5
+.I p3
+button
+.TP 5
+.I p4
+state, e.g., pressed or released
+.TP 5
+.I p5
+y-ordinate starting region
+.TP 5
+.I p6
+x-ordinate starting region
+.TP 5
+.I p7
+y-ordinate ending region
+.TP 5
+.I p8
+x-ordinate ending region
+.RE
+.IP
+Here are examples from the terminal database for the most commonly used
+xterm mouse protocols:
+.IP
+.nf
+ xterm+x11mouse|X11 xterm mouse protocol,
+ kmous=\eE[M, XM=\eE[?1000%?%p1%{1}%=%th%el%;,
+ xm=\eE[M
+ %?%p4%t%p3%e%{3}%;%'\ '%+%c
+ %p2%'!'%+%c
+ %p1%'!'%+%c,
+
+ xterm+sm+1006|xterm SGR-mouse,
+ kmous=\eE[<, XM=\eE[?1006;1000%?%p1%{1}%=%th%el%;,
+ xm=\eE[<%i%p3%d;
+ %p1%d;
+ %p2%d;
+ %?%p4%tM%em%;,
+.fi
+.
+.SS "Extended Key Definitions"
+Several terminals provide the ability to send distinct strings for
+combinations of modified special keys.
+There is no standard for what those keys can send.
+.PP
+Since 1999, \fBxterm\fP(1) has supported
+\fIshift\fP, \fIcontrol\fP, \fIalt\fP, and \fImeta\fP modifiers which produce
+distinct special-key strings.
+In a terminal description,
+\fI\%ncurses\fP has no special knowledge of the modifiers used.
+Applications can use the \fInaming convention\fP established for \fBxterm\fP
+to find these special keys in the terminal description.
+.PP
+Starting with the
+.I curses
+convention that capability codes describing the input generated by a
+terminal's key caps begin with \*(``k\*('',
+and that shifted special keys use uppercase letters in their names,
+.IR \%ncurses 's
+terminal database defines the following names and codes to which a
+suffix is added.
+.PP
+.RS 5
+.TS
+Lb Lb
+Lb Lx.
+Code Description
+_
+kDC shifted kdch1 (delete character)
+.\" kDC is a standard capability; see X/Open Curses Issue 7, p. 345.
+kDN shifted kcud1 (cursor down)
+kEND shifted kend (end)
+kHOM shifted khome (home)
+kLFT shifted kcub1 (cursor back)
+kNXT shifted knext (next)
+kPRV shifted kprev (previous)
+kRIT shifted kcuf1 (cursor forward)
+kUP shifted kcuu1 (cursor up)
+.TE
+.RE
+.PP
+Keycap nomenclature on the Unix systems for which
+.I curses
+was developed differs from today's ubiquitous descendants of the IBM
+PC/AT keyboard layout.
+In the foregoing,
+interpret \*(``backward\*('' as \*(``left\*('',
+\*(``forward\*('' as \*(``right\*('',
+\*(``next\*('' as \*(``page down\*('',
+and
+\*(``prev(ious)\*('' as \*(``page up\*(''.
+.PP
+These are the suffixes used to denote the modifiers:
+.PP
+.RS 5
+.TS
+tab(/) ;
+l l .
+\fBValue\fP/\fBDescription\fP
+_
+2/Shift
+3/Alt
+4/Shift + Alt
+5/Control
+6/Shift + Control
+7/Alt + Control
+8/Shift + Alt + Control
+9/Meta
+10/Meta + Shift
+11/Meta + Alt
+12/Meta + Alt + Shift
+13/Meta + Ctrl
+14/Meta + Ctrl + Shift
+15/Meta + Ctrl + Alt
+16/Meta + Ctrl + Alt + Shift
+.TE
+.RE
+.PP
+None of these are predefined; terminal descriptions can refer to \fInames\fP
+which \fI\%ncurses\fP will allocate at runtime to \fIkey-codes\fP.
+To use these keys in an \fI\%ncurses\fP program,
+an application could do this:
+.bP
+using a list of extended key \fInames\fP,
+ask \fBtigetstr\fP(3X) for their values, and
+.bP
+given the list of values,
+ask \fBkey_defined\fP(3X) for the \fIkey-code\fP which
+would be returned for those keys by \fBwgetch\fP(3X).
+.\"
+.SH PORTABILITY
+The \*(``\-x\*('' extension feature of \fB@TIC@\fP and \fB@INFOCMP@\fP
+has been adopted in NetBSD curses.
+That implementation stores user-defined capabilities,
+but makes no use of these capabilities itself.
+.\"
+.SH AUTHORS
+Thomas E. Dickey
+.br
+beginning with \fI\%ncurses\fP 5.0 (1999)
+.\"
+.SH SEE ALSO
+\fB\%@INFOCMP@\fP(1M),
+\fB\%@TIC@\fP(1M)
+.PP
+The terminal database section
+.I "NCURSES USER-DEFINABLE CAPABILITIES"
+summarizes commonly-used user-defined capabilities
+which are used in the terminal descriptions.
+Some of those features are mentioned in \fB\%screen\fP(1) or
+\fBtmux\fP(1).
+.PP
+.I "XTerm Control Sequences"
+provides further information on the \fB\%xterm\fP(1) features
+that are used in these extended capabilities.
diff --git a/man/wresize.3x b/man/wresize.3x
index 0832450..b67fead 100644
--- a/man/wresize.3x
+++ b/man/wresize.3x
@@ -1,5 +1,6 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,2015 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 *
@@ -28,32 +29,44 @@
.\"
.\" Author: Thomas E. Dickey 1996
.\"
-.\" $Id: wresize.3x,v 1.13 2010/12/04 18:40:45 tom Exp $
-.TH wresize 3X ""
+.\" $Id: wresize.3x,v 1.36 2024/03/16 15:35:01 tom Exp $
+.TH wresize 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
-\fBwresize\fR \- resize a curses window
+\fB\%wresize\fP \-
+resize a \fIcurses\fR window
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBint wresize(WINDOW *win, int lines, int columns);\fR
+.nf
+\fB#include <curses.h>
+.PP
+\fBint wresize(WINDOW *\fIwin\fP, int \fIlines\fP, int \fIcolumns\fP);
+.fi
.SH DESCRIPTION
-This is an extension to the curses library.
-It reallocates storage for an \fBncurses\fR
-window to adjust its dimensions to the specified values.
-If either dimension is larger than the current values, the
-window's data is filled with blanks that have the current background rendition
-(as set by \fBwbkgdset\fR) merged into them.
+This \fI\%ncurses\fP extension to standard \fIcurses\fP reallocates
+storage for a \fIcurses\fP window to adjust its dimensions to the
+specified values.
+If either dimension is larger than its current value,
+the expanded part of the window is filled with blanks merged with
+current background rendition
+(as set by \fB\%wbkgdset\fP(3X)).
.SH RETURN VALUE
-The function returns the integer \fBERR\fR upon failure and \fBOK\fR on success.
-It will fail if either of the dimensions less than or equal to zero,
+\fB\%wresize\fP returns \fBERR\fP upon failure and \fBOK\fP on success.
+It will fail if either of the dimensions is less than or equal to zero,
or if an error occurs while (re)allocating memory for the window.
.SH NOTES
-The only restriction placed on the dimensions is that they be greater than zero.
-The dimensions are not compared to \fBcurses\fR screen dimensions to
-simplify the logic of \fBresizeterm\fR.
+The only restriction placed on the dimensions is that they be greater
+than zero.
+They are \fInot\fP compared to the \fIcurses\fP screen dimensions;
+this keeps the logic of \fB\%resizeterm\fP(3X) simple.
The caller must ensure that the window's dimensions fit within the
actual screen dimensions.
+.SH PORTABILITY
+It is not possible to resize windows with SVr4 \fIcurses\fP.
+.PP
+\fI\%ncurses\fP introduced this extension in mid-1995.
+NetBSD \fIcurses\fP adopted it in 2001,
+and \fI\%PDCurses\fP in 2003.
+.SH AUTHORS
+Thomas Dickey
+(from an equivalent function written in 1988 for BSD \fIcurses\fP).
.SH SEE ALSO
-\fBresizeterm\fR(3X).
-.SH AUTHOR
-Thomas Dickey (from an equivalent function written in 1988 for BSD curses).
+\fB\%resizeterm\fP(3X)