aboutsummaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
Diffstat (limited to 'man')
-rw-r--r--man/MKada_config.in84
-rwxr-xr-xman/MKterminfo.sh40
-rw-r--r--man/Makefile.in23
-rw-r--r--man/captoinfo.1m20
-rw-r--r--man/clear.1126
-rw-r--r--man/curs_add_wch.3x226
-rw-r--r--man/curs_add_wchstr.3x13
-rw-r--r--man/curs_addch.3x230
-rw-r--r--man/curs_addchstr.3x13
-rw-r--r--man/curs_addstr.3x13
-rw-r--r--man/curs_addwstr.3x13
-rw-r--r--man/curs_attr.3x553
-rw-r--r--man/curs_beep.3x13
-rw-r--r--man/curs_bkgd.3x108
-rw-r--r--man/curs_bkgrnd.3x38
-rw-r--r--man/curs_border.3x25
-rw-r--r--man/curs_border_set.3x10
-rw-r--r--man/curs_clear.3x15
-rw-r--r--man/curs_color.3x470
-rw-r--r--man/curs_delch.3x19
-rw-r--r--man/curs_deleteln.3x25
-rw-r--r--man/curs_extend.3x25
-rw-r--r--man/curs_get_wch.3x39
-rw-r--r--man/curs_get_wstr.3x70
-rw-r--r--man/curs_getcchar.3x77
-rw-r--r--man/curs_getch.3x153
-rw-r--r--man/curs_getstr.3x104
-rw-r--r--man/curs_in_wch.3x18
-rw-r--r--man/curs_in_wchstr.3x15
-rw-r--r--man/curs_inch.3x61
-rw-r--r--man/curs_inchstr.3x36
-rw-r--r--man/curs_initscr.3x194
-rw-r--r--man/curs_inopts.3x169
-rw-r--r--man/curs_ins_wch.3x14
-rw-r--r--man/curs_ins_wstr.3x14
-rw-r--r--man/curs_insch.3x20
-rw-r--r--man/curs_insstr.3x17
-rw-r--r--man/curs_instr.3x27
-rw-r--r--man/curs_inwstr.3x52
-rw-r--r--man/curs_kernel.3x137
-rw-r--r--man/curs_legacy.3x85
-rw-r--r--man/curs_memleaks.3x67
-rw-r--r--man/curs_mouse.3x165
-rw-r--r--man/curs_move.3x12
-rw-r--r--man/curs_opaque.3x20
-rw-r--r--man/curs_outopts.3x39
-rw-r--r--man/curs_overlay.3x16
-rw-r--r--man/curs_pad.3x114
-rw-r--r--man/curs_print.3x17
-rw-r--r--man/curs_printw.3x45
-rw-r--r--man/curs_refresh.3x62
-rw-r--r--man/curs_scanw.3x71
-rw-r--r--man/curs_scr_dump.3x48
-rw-r--r--man/curs_scroll.3x16
-rw-r--r--man/curs_slk.3x151
-rw-r--r--man/curs_sp_funcs.3x67
-rw-r--r--man/curs_termattrs.3x26
-rw-r--r--man/curs_termcap.3x87
-rw-r--r--man/curs_terminfo.3x366
-rw-r--r--man/curs_threads.3x15
-rw-r--r--man/curs_touch.3x40
-rw-r--r--man/curs_trace.3x235
-rw-r--r--man/curs_util.3x212
-rw-r--r--man/curs_variables.3x63
-rw-r--r--man/curs_window.3x140
-rw-r--r--man/default_colors.3x59
-rw-r--r--man/define_key.3x16
-rw-r--r--man/form.3x57
-rw-r--r--man/form_cursor.3x18
-rw-r--r--man/form_data.3x20
-rw-r--r--man/form_driver.3x321
-rw-r--r--man/form_field.3x13
-rw-r--r--man/form_field_attributes.3x29
-rw-r--r--man/form_field_buffer.3x29
-rw-r--r--man/form_field_info.3x28
-rw-r--r--man/form_field_just.3x22
-rw-r--r--man/form_field_new.3x25
-rw-r--r--man/form_field_opts.3x88
-rw-r--r--man/form_field_userptr.3x17
-rw-r--r--man/form_field_validation.3x147
-rw-r--r--man/form_fieldtype.3x20
-rw-r--r--man/form_hook.3x28
-rw-r--r--man/form_new.3x14
-rw-r--r--man/form_new_page.3x25
-rw-r--r--man/form_opts.3x16
-rw-r--r--man/form_page.3x26
-rw-r--r--man/form_post.3x21
-rw-r--r--man/form_requestname.3x20
-rw-r--r--man/form_userptr.3x12
-rw-r--r--man/form_variables.3x5
-rw-r--r--man/form_win.3x22
-rw-r--r--man/infocmp.1m230
-rw-r--r--man/infotocap.1m12
-rw-r--r--man/key_defined.3x13
-rw-r--r--man/keybound.3x10
-rw-r--r--man/keyok.3x16
-rw-r--r--man/legacy_coding.3x10
-rwxr-xr-xman/make_sed.sh6
-rw-r--r--man/man_db.renames18
-rw-r--r--man/manhtml.aliases50
-rw-r--r--man/manhtml.externs46
-rw-r--r--man/menu.3x57
-rw-r--r--man/menu_attributes.3x46
-rw-r--r--man/menu_cursor.3x18
-rw-r--r--man/menu_driver.3x31
-rw-r--r--man/menu_format.3x30
-rw-r--r--man/menu_hook.3x24
-rw-r--r--man/menu_items.3x17
-rw-r--r--man/menu_mark.3x17
-rw-r--r--man/menu_new.3x16
-rw-r--r--man/menu_opts.3x22
-rw-r--r--man/menu_pattern.3x30
-rw-r--r--man/menu_post.3x29
-rw-r--r--man/menu_requestname.3x17
-rw-r--r--man/menu_spacing.3x23
-rw-r--r--man/menu_userptr.3x12
-rw-r--r--man/menu_win.3x22
-rw-r--r--man/mitem_current.3x24
-rw-r--r--man/mitem_name.3x11
-rw-r--r--man/mitem_new.3x28
-rw-r--r--man/mitem_opts.3x21
-rw-r--r--man/mitem_userptr.3x17
-rw-r--r--man/mitem_value.3x16
-rw-r--r--man/mitem_visible.3x11
-rw-r--r--man/ncurses.3x477
-rw-r--r--man/new_pair.3x165
-rw-r--r--man/panel.3x122
-rw-r--r--man/resizeterm.3x71
-rw-r--r--man/scr_dump.5428
-rw-r--r--man/tabs.1140
-rw-r--r--man/term.5163
-rw-r--r--man/term.781
-rw-r--r--man/term_variables.3x98
-rw-r--r--man/terminfo.head164
-rw-r--r--man/terminfo.tail449
-rw-r--r--man/tic.1m233
-rw-r--r--man/toe.1m91
-rw-r--r--man/tput.1400
-rw-r--r--man/tset.1266
-rw-r--r--man/user_caps.5425
-rw-r--r--man/wresize.3x14
141 files changed, 8490 insertions, 2843 deletions
diff --git a/man/MKada_config.in b/man/MKada_config.in
index 2be3c419ec8f..86db2ec9e42f 100644
--- a/man/MKada_config.in
+++ b/man/MKada_config.in
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2010,2011 Free Software Foundation, Inc. *
+.\" Copyright (c) 2010-2016,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,30 +26,96 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: MKada_config.in,v 1.5 2011/03/26 14:44:51 tom Exp $
+.\" $Id: MKada_config.in,v 1.11 2019/09/07 20:22:51 tom Exp $
+.ds C adacurses@USE_CFG_SUFFIX@\-config
.TH ADACURSES "1" "" "" "User Commands"
.SH NAME
-adacurses\-config \- helper script for AdaCurses libraries
+adacurses@USE_CFG_SUFFIX@\-config \- helper script for @ADA_LIBNAME@ libraries
.SH SYNOPSIS
-.B adacurses\-config
+.B \*C
[\fIoptions\fR]
.SH DESCRIPTION
This is a shell script which simplifies configuring an application to use
-the AdaCurses library binding to ncurses.
+the @ADA_LIBNAME@ library binding to ncurses.
.SH OPTIONS
.TP
\fB\-\-cflags\fR
-echos the gnat (Ada compiler) flags needed to compile with AdaCurses.
+echos the gnat (Ada compiler) flags needed to compile with @ADA_LIBNAME@.
.TP
\fB\-\-libs\fR
-echos the gnat libraries needed to link with AdaCurses.
+echos the gnat libraries needed to link with @ADA_LIBNAME@.
.TP
\fB\-\-version\fR
echos the release+patchdate version of the ncurses libraries used
-to configure and build AdaCurses.
+to configure and build @ADA_LIBNAME@.
.TP
\fB\-\-help\fR
-prints a list of the \fBadacurses\-config\fP script's options.
+prints a list of the \fB\*C\fP script's options.
+.PP
+If no options are given, \fB\*C\fP prints the combination
+of
+\fB\-\-cflags\fR and
+\fB\-\-libs\fR
+that \fBgnatmake\fP expects (see example).
+.SH EXAMPLE
+.PP
+For example, supposing that you want to compile the "Hello World!"
+program for @ADA_LIBNAME@.
+Make a file named "hello.adb":
+.RS
+.nf
+.ft CW
+with Terminal_Interface.Curses; use Terminal_Interface.Curses;
+
+procedure Hello is
+
+ Visibility : Cursor_Visibility := Invisible;
+ 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!");
+
+ while not done loop
+
+ c := Get_Keystroke (Standard_Window);
+ case c is
+ when Character'Pos ('q') => done := True;
+ when others => null;
+ end case;
+
+ Nap_Milli_Seconds (50);
+ end loop;
+
+ End_Windows;
+
+end Hello;
+.fi
+.RE
+.PP
+Then, using
+.RS
+.ft CW
+gnatmake `adacurses-config --cflags` hello -largs `adacurses-config --libs`
+.ft
+.RE
+.PP
+or (simpler):
+.RS
+.ft CW
+gnatmake hello `adacurses-config`
+.ft
+.RE
+.PP
+you will compile and link the program.
.SH "SEE ALSO"
\fBcurses\fR(3X)
.PP
diff --git a/man/MKterminfo.sh b/man/MKterminfo.sh
index 3a9960956567..7c0378cdcfdd 100755
--- a/man/MKterminfo.sh
+++ b/man/MKterminfo.sh
@@ -1,10 +1,10 @@
#!/bin/sh
-# $Id: MKterminfo.sh,v 1.12 2003/01/11 21:42:12 tom Exp $
+# $Id: MKterminfo.sh,v 1.17 2019/03/02 22:18:27 tom Exp $
#
# MKterminfo.sh -- generate terminfo.5 from Caps tabular data
#
#***************************************************************************
-# Copyright (c) 1998,2002,2003 Free Software Foundation, Inc. *
+# Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
# *
# Permission is hereby granted, free of charge, to any person obtaining a *
# copy of this software and associated documentation files (the *
@@ -50,25 +50,34 @@ 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.
+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
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
@@ -105,6 +114,7 @@ done <$unsorted
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.in b/man/Makefile.in
index ad40bc53a2c2..8f6b27126fa7 100644
--- a/man/Makefile.in
+++ b/man/Makefile.in
@@ -1,6 +1,6 @@
-# $Id: Makefile.in,v 1.47 2013/08/04 20:23:20 tom Exp $
+# $Id: Makefile.in,v 1.49 2019/03/02 22:18:27 tom Exp $
##############################################################################
-# Copyright (c) 1998-2010,2013 Free Software Foundation, Inc. #
+# Copyright (c) 1998-2015,2019 Free Software Foundation, Inc. #
# #
# Permission is hereby granted, free of charge, to any person obtaining a #
# copy of this software and associated documentation files (the "Software"), #
@@ -34,7 +34,7 @@
# 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
+SHELL = @SHELL@
VPATH = @srcdir@
DESTDIR = @DESTDIR@
@@ -62,15 +62,20 @@ $(DESTDIR)$(mandir) :
EDITARGS = $(DESTDIR)$(mandir) $(srcdir) terminfo.5 *-config.1 $(srcdir)/*.[0-9]*
install install.man : terminfo.5 $(DESTDIR)$(mandir)
- sh ../edit_man.sh normal installing $(EDITARGS)
+ $(SHELL) ../edit_man.sh normal installing $(EDITARGS)
uninstall uninstall.man :
- -sh ../edit_man.sh normal removing $(EDITARGS)
+ -$(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
- sh $(srcdir)/MKterminfo.sh $(srcdir)/terminfo.head $(CAPLIST) $(srcdir)/terminfo.tail >terminfo.5
+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 :
-rm -f core tags TAGS *~ *.bak *.ln *.atac trace
@@ -79,7 +84,7 @@ clean: mostlyclean
rm -f terminfo.5
../edit_man.sed : make_sed.sh @MANPAGE_RENAMES@
- sh $(srcdir)/make_sed.sh @MANPAGE_RENAMES@ >../edit_man.sed
+ $(SHELL) $(srcdir)/make_sed.sh @MANPAGE_RENAMES@ >../edit_man.sed
distclean realclean: clean
rm -f Makefile *-config.1 ../edit_man.* ../man_alias.*
diff --git a/man/captoinfo.1m b/man/captoinfo.1m
index c7a33643f706..4fa155e40c85 100644
--- a/man/captoinfo.1m
+++ b/man/captoinfo.1m
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,14 +27,14 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: captoinfo.1m,v 1.25 2010/12/04 18:36:44 tom Exp $
+.\" $Id: captoinfo.1m,v 1.29 2019/10/12 21:10:00 tom Exp $
.TH @CAPTOINFO@ 1M ""
.ds n 5
.ds d @TERMINFO@
.SH NAME
\fB@CAPTOINFO@\fR \- convert a \fItermcap\fR description into a \fIterminfo\fR 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 . . .
+\fB@CAPTOINFO@\fR [\fB\-v\fR\fIn\fR \fIwidth\fR] [\fB\-V\fR] [\fB\-1\fR] [\fB\-w\fR \fIwidth\fR] \fIfile\fR ...
.SH DESCRIPTION
\fB@CAPTOINFO@\fR looks in each given text
\fIfile\fR for \fBtermcap\fR descriptions.
@@ -152,7 +152,7 @@ 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.
+be composed into an \fBacsc\fR string.
The double-line capabilities and
\fBGG\fR are discarded with a warning message.
.PP
@@ -174,18 +174,24 @@ font3 s3ds
.TE
.PP
Additionally, the AIX \fIbox1\fR capability will be automatically translated to
-an \fIacsc\fR string.
+an \fBacsc\fR string.
.PP
Hewlett-Packard's terminfo library supports two nonstandard terminfo
-capabilities \fImeml\fR (memory lock) and \fImemu\fR (memory unlock).
+capabilities \fBmeml\fR (memory lock) and \fBmemu\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.
.PP
-The trace option is not identical to SVr4's.
+The verbose 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 PORTABILITY
+X/Open Curses, Issue 7 (2009) describes \fBtic\fP briefly,
+but omits this program.
+SVr4 systems provide \fBcaptoinfo\fP as a separate application from \fBtic\fP.
+.PP
+NetBSD does not provide this application.
.SH SEE ALSO
\fB@INFOCMP@\fR(1M),
\fBcurses\fR(3X),
diff --git a/man/clear.1 b/man/clear.1
index d8e24e5bb926..21ce43c2c32e 100644
--- a/man/clear.1
+++ b/man/clear.1
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2013 Free Software Foundation, Inc. *
+.\" Copyright (c) 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,21 +26,135 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: clear.1,v 1.10 2013/06/22 22:22:11 tom Exp $
+.\" $Id: clear.1,v 1.22 2018/07/28 21:45:40 tom Exp $
.TH @CLEAR@ 1 ""
+.\" these would be fallbacks for DS/DE,
+.\" but groff changed the meaning of the macros.
+.de NS
+.ie n .sp
+.el .sp .5
+.ie n .in +4
+.el .in +2
+.nf
+.ft C \" Courier
+..
+.de NE
+.fi
+.ft R
+.ie n .in -4
+.el .in -2
+..
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.ds n 5
.SH NAME
\fB@CLEAR@\fR \- clear the terminal screen
.SH SYNOPSIS
-\fB@CLEAR@\fR
+\fB@CLEAR@\fR [\fB\-T\fR\fItype\fR] [\fB\-V\fP] [\fB\-x\fP]
.br
.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
+including its scrollback buffer
+(if the extended \*(``E3\*('' capability is defined).
+\fB@CLEAR@\fR looks in the environment for the terminal type
+given by the environment variable \fBTERM\fP,
+and then in the
\fBterminfo\fR database to determine how to clear the screen.
.PP
-\fB@CLEAR@\fR ignores any command-line parameters that may be present.
+\fB@CLEAR@\fR writes to the standard output.
+You can redirect the standard output to a file (which prevents
+\fB@CLEAR@\fR from actually clearing the screen),
+and later \fBcat\fP the file to the screen, clearing it at that point.
+.SH OPTIONS
+.PP
+.TP 5
+.B \-T \fItype\fP
+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
+.B \-V
+reports the version of ncurses which was used in this program, and exits.
+The options are as follows:
+.TP
+.B \-x
+do not attempt to clear the terminal's scrollback buffer
+using the extended \*(``E3\*('' capability.
+.SH HISTORY
+A \fBclear\fP command appeared in 2.79BSD dated February 24, 1979.
+Later that was provided in Unix 8th edition (1985).
+.PP
+AT&T adapted a different BSD program (\fBtset\fP) to make
+a new command (\fBtput\fP),
+and used this to replace the \fBclear\fP command with a shell script
+which calls \fBtput clear\fP, e.g.,
+.NS
+/usr/bin/tput ${1:+-T$1} clear 2> /dev/null
+exit
+.NE
+.PP
+In 1989, when Keith Bostic revised the BSD \fBtput\fP command
+to make it similar to the AT&T \fBtput\fP,
+he added a shell script for the \fBclear\fP command:
+.NS
+exec tput clear
+.NE
+.PP
+The remainder of the script in each case is a copyright notice.
+.PP
+The ncurses \fBclear\fP command began in 1995 by adapting the original
+BSD \fBclear\fP command (with terminfo, of course).
+.PP
+The \fBE3\fP extension came later:
+.bP
+In June 1999, xterm provided an extension to the standard control
+sequence for clearing the screen.
+Rather than clearing just the visible part of the screen using
+.NS
+printf '\\033[2J'
+.NE
+.IP
+one could clear the \fIscrollback\fP using
+.NS
+printf '\\033[\fB3\fPJ'
+.NE
+.IP
+This is documented in \fIXTerm Control Sequences\fP as a feature originating
+with xterm.
+.bP
+A few other terminal developers adopted the feature, e.g., 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.
+The Linux change, part of the 3.0 release, did not mention xterm,
+although it was cited in the Red Hat bug report (#683733)
+which led to the change.
+.bP
+Again, a few other terminal developers adopted the feature.
+But the
+next relevant step was a change to the \fBclear\fP program in 2013
+to incorporate this extension.
+.bP
+In 2013, the \fBE3\fP extension was overlooked in \fB@TPUT@\fP with
+the \*(``clear\*('' parameter.
+That was addressed in 2016 by reorganizing \fB@TPUT@\fP to share
+its logic with \fB@CLEAR@\fP and \fB@TSET@\fP.
+.SH PORTABILITY
+Neither IEEE Std 1003.1/The Open Group Base Specifications Issue 7
+(POSIX.1-2008) nor X/Open Curses Issue 7 documents @TSET@ or @RESET@.
+.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 SEE ALSO
\fB@TPUT@\fR(1), \fBterminfo\fR(\*n)
.PP
diff --git a/man/curs_add_wch.3x b/man/curs_add_wch.3x
index b7164ada0e2b..245cc17e0cae 100644
--- a/man/curs_add_wch.3x
+++ b/man/curs_add_wch.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2001-2011,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 2001-2017,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,10 +26,15 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_add_wch.3x,v 1.15 2012/11/03 23:03:59 tom Exp $
+.\" $Id: curs_add_wch.3x,v 1.25 2019/10/27 00:07:13 tom Exp $
.TH curs_add_wch 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.SH NAME
\fBadd_wch\fP,
@@ -55,6 +60,7 @@
.B "int wecho_wchar( WINDOW *\fIwin\fP, const cchar_t *\fIwch\fB );"
.br
.SH DESCRIPTION
+.SS add_wch
.PP
The
\fBadd_wch\fP,
@@ -83,12 +89,13 @@ and the rendition specified by \fIwch\fP is ignored.
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.
+.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.
+\fBrefresh\fP(3X).
Similarly, the
\fBwecho_wchar\fP
is functionally equivalent to a call to
@@ -107,80 +114,104 @@ These symbols correspond to the same VT100 line-drawing set as
\fBaddch\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
+l l l l l
+l l l l l
+_ _ _ _ _
+lw(1.5i) lw5 lw5 lw5 lw20.
+\fBACS\fR \fBUnicode\fP \fBASCII\fR \fBacsc\fP \fBGlyph\fR
+\fBName\fR \fBDefault\fP \fBDefault\fR \fBchar\fP \fBName\fR
+WACS_BLOCK 0x25ae # 0 solid square block
+WACS_BOARD 0x2592 # h board of squares
+WACS_BTEE 0x2534 + v bottom tee
+WACS_BULLET 0x00b7 o ~ bullet
+WACS_CKBOARD 0x2592 : a checker board (stipple)
+WACS_DARROW 0x2193 v . arrow pointing down
+WACS_DEGREE 0x00b0 ' f degree symbol
+WACS_DIAMOND 0x25c6 + ` diamond
+WACS_GEQUAL 0x2265 > > greater-than-or-equal-to
+WACS_HLINE 0x2500 \- q horizontal line
+WACS_LANTERN 0x2603 # i lantern symbol
+WACS_LARROW 0x2190 < , arrow pointing left
+WACS_LEQUAL 0x2264 < y less-than-or-equal-to
+WACS_LLCORNER 0x2514 + m lower left-hand corner
+WACS_LRCORNER 0x2518 + j lower right-hand corner
+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 > + arrow pointing right
+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 } pound-sterling symbol
+WACS_TTEE 0x252c + w top tee
+WACS_UARROW 0x2191 ^ \- arrow pointing up
+WACS_ULCORNER 0x250c + l upper left-hand corner
+WACS_URCORNER 0x2510 + k upper right-hand corner
+WACS_VLINE 0x2502 | x vertical line
.TE
.PP
The wide-character configuration of ncurses also defines symbols
-for thick- and double-lines:
+for thick lines (\fBacsc\fP \*(``J\*('' to \*(``V\*(''):
+.TS
+l l l l l
+l l l l l
+_ _ _ _ _
+lw(1.5i) lw5 lw5 lw5 lw20.
+\fBACS\fR \fBUnicode\fP \fBASCII\fR \fBacsc\fP \fBGlyph\fR
+\fBName\fR \fBDefault\fP \fBDefault\fR \fBchar\fP \fBName\fR
+WACS_T_BTEE 0x253b + V thick tee pointing up
+WACS_T_HLINE 0x2501 - Q thick horizontal line
+WACS_T_LLCORNER 0x2517 + M thick lower left corner
+WACS_T_LRCORNER 0x251b + J thick lower right corner
+WACS_T_LTEE 0x252b + T thick tee pointing right
+WACS_T_PLUS 0x254b + N thick large plus
+WACS_T_RTEE 0x2523 + U thick tee pointing left
+WACS_T_TTEE 0x2533 + W thick tee pointing down
+WACS_T_ULCORNER 0x250f + L thick upper left corner
+WACS_T_URCORNER 0x2513 + K thick upper right corner
+WACS_T_VLINE 0x2503 | X thick vertical line
+.TE
+.PP
+and for double-lines (\fBacsc\fP \*(``A\*('' to \*(``I\*(''):
.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
+l l l l l
+l l l l l
+_ _ _ _ _
+lw(1.5i) lw5 lw5 lw5 lw20.
+\fBACS\fR \fBUnicode\fP \fBASCII\fR \fBacsc\fP \fBGlyph\fR
+\fBName\fR \fBDefault\fP \fBDefault\fR \fBchar\fP \fBName\fR
+WACS_D_BTEE 0x2569 + H double tee pointing up
+WACS_D_HLINE 0x2550 - R double horizontal line
+WACS_D_LLCORNER 0x255a + D double lower left corner
+WACS_D_LRCORNER 0x255d + A double lower right corner
+WACS_D_LTEE 0x2560 + F double tee pointing right
+WACS_D_PLUS 0x256c + E double large plus
+WACS_D_RTEE 0x2563 + G double tee pointing left
+WACS_D_TTEE 0x2566 + I double tee pointing down
+WACS_D_ULCORNER 0x2554 + C double upper left corner
+WACS_D_URCORNER 0x2557 + B double upper right corner
+WACS_D_VLINE 0x2551 | Y double vertical line
.TE
+.PP
+Unicode's descriptions for these characters differs slightly from ncurses,
+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
.PP
All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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 NOTES
@@ -213,7 +244,66 @@ 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.
+.PP
+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, HPUX, 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.
+Ncurses 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 ncurses(3X)
+for the environment variable \fBNCURSES_NO_UTF8_ACS\fP.
+In contrast, for the same cases, the line-drawing characters
+described in \fBcurs_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).
.SH SEE ALSO
+.na
.PP
\fBcurses\fR(3X),
\fBcurs_addch\fR(3X),
diff --git a/man/curs_add_wchstr.3x b/man/curs_add_wchstr.3x
index 37e3df614b16..ccc077b3ac16 100644
--- a/man/curs_add_wchstr.3x
+++ b/man/curs_add_wchstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2017,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,10 +26,15 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_add_wchstr.3x,v 1.10 2012/11/03 22:54:43 tom Exp $
+.\" $Id: curs_add_wchstr.3x,v 1.12 2019/11/30 21:06:30 tom Exp $
.TH curs_add_wchstr 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.na
.hy 0
@@ -101,7 +106,7 @@ X/Open does not define 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
+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 NOTES
diff --git a/man/curs_addch.3x b/man/curs_addch.3x
index 1ad071a8a8a0..ee980aac5435 100644
--- a/man/curs_addch.3x
+++ b/man/curs_addch.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2011 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,8 +27,16 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addch.3x,v 1.32 2011/01/15 14:15:10 tom Exp $
+.\" $Id: curs_addch.3x,v 1.50 2019/11/30 20:07:00 tom Exp $
.TH curs_addch 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
\fBaddch\fR,
\fBwaddch\fR,
@@ -52,93 +60,118 @@
\fBint wechochar(WINDOW *win, const chtype ch);\fR
.br
.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, the cursor automatically wraps to the
-beginning of the next line. At the bottom of the current scrolling region, if
-\fBscrollok\fR is enabled, the scrolling region is scrolled up one line.
+which is then advanced.
+They are analogous to \fBputchar\fR(3) 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
.PP
-If \fIch\fR is a tab, newline, or backspace,
-the cursor is moved appropriately within the window.
+If \fIch\fR is a tab, newline, carriage return or backspace,
+the cursor is moved appropriately within the window:
+.bP
Backspace moves the cursor one character left; at the left
edge of a window it does nothing.
+.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.
.PP
-If \fIch\fR is any control character other than tab, newline, or backspace, it
-is drawn in \fB^\fR\fIX\fR notation. Calling \fBwinch\fR after adding a
+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.
.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
+using \fBinch\fR(3X) 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
.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
+\fBaddch\fR followed by a call to \fBrefresh\fR(3X), 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
+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.
+replacement for it,
+or if the terminal and locale configuration requires Unicode but the
+library is unable to use Unicode.
+.PP
The names are taken from VT100 nomenclature.
.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
+l l l l
+l l l l
+_ _ _ _
+l l l l.
+\fBACS\fR \fBACS\fR \fBacsc\fP \fBGlyph\fR
+\fBName\fR \fBDefault\fR \fBchar\fP \fBName\fR
+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 + ` 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.
+(the SVr4 manuals specify only
+\*(``an integer value other than \fBERR\fR\*('') upon successful completion,
+unless otherwise noted in the preceding routine descriptions.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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 NOTES
@@ -147,10 +180,36 @@ Note that \fBaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR, and
.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.
+.SS ACS Symbols
.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.
+Some implementations are problematic:
+.bP
+Some implementations define the ACS symbols to a constant
+(such as Solaris), while others define those to entries in an array.
+.IP
+This implementation uses an array \fBacs_map\fP, as done in SVr4 curses.
+NetBSD also uses an array, actually named \fB_acs_char\fP, with a \fB#define\fP
+for compatibility.
+.bP
+HPUX curses equates some of the \fIACS_\fP symbols
+to the analogous \fIWACS_\fP symbols as if the \fIACS_\fP symbols were
+wide characters.
+The misdefined symbols are the arrows
+and other symbols which are not used for line-drawing.
+.bP
+X/Open Curses (issues 2 through 7) has a typographical error
+for the ACS_LANTERN symbol, equating its \*(``VT100+ Character\*(''
+to \fBI\fP (capital I), while the header files for SVr4 curses
+and the various implementations use \fBi\fP (lowercase).
+.IP
+None of the terminal descriptions on Unix platforms use uppercase-I,
+except for Solaris (i.e., \fIscreen\fP's terminal description,
+apparently based on the X/Open documentation around 1995).
+On the other hand, the terminal description \fIgs6300\fP
+(AT&T PC6300 with EMOTS Terminal Emulator) uses lowercase-i.
.LP
Some ACS symbols
(ACS_S3,
@@ -161,13 +220,66 @@ ACS_PI,
ACS_NEQUAL,
ACS_STERLING)
were not documented in
-any publicly released System V. However, many publicly available terminfos
+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).
+to light.
+The ACS-prefixed names for them were invented for \fBncurses\fR(3X).
+.LP
+The \fIdisplayed\fP values for the \fIACS_\fP and \fIWACS_\fP constants
+depend on
+.bP
+the library configuration, i.e., \fBncurses\fP versus \fBncursesw\fP,
+where the latter is capable of displaying Unicode while the former is not, and
+.bP
+whether the \fIlocale\fP uses UTF-8 encoding.
+.LP
+In certain cases, the terminal is unable to display line-drawing characters
+except by using UTF-8 (see the discussion of \fBNCURSES_NO_UTF8_ACS\fP in
+ncurses(3X)).
+.SS Character Set
+X/Open Curses assumes that the parameter passed to \fBwaddch\fP contains
+a single character.
+As discussed in \fBcurs_attr\fP(3X), that character may have been
+more than eight bits in an SVr3 or SVr4 implementation,
+but in the X/Open Curses model, the details are not given.
+The important distinction between SVr4 curses and X/Open Curses is
+that the non-character information (attributes and color) was
+separated from the character information which is packed in a \fBchtype\fP
+to pass to \fBwaddch\fP.
+.PP
+In this implementation, \fBchtype\fP holds an eight-bit character.
+But ncurses allows multibyte characters to be passed in a succession
+of calls to \fBwaddch\fP.
+The other implementations do not do this;
+a call to \fBwaddch\fP passes exactly one character
+which may be rendered as one or more cells on the screen
+depending on whether it is printable.
+.PP
+Depending on the locale settings,
+ncurses will inspect the byte passed in each call to \fBwaddch\fP,
+and check if the latest call will continue a multibyte sequence.
+When a character is \fIcomplete\fP,
+ncurses displays the character and moves to the next position in the screen.
+.PP
+If the calling application interrupts the succession of bytes in
+a multibyte character by moving the current location (e.g., using \fBwmove\fP),
+ncurses discards the partially built character,
+starting over again.
+.PP
+For portability to other implementations,
+do not rely upon this behavior:
+.bP
+check if a character can be represented as a single byte in the current locale
+before attempting call \fBwaddch\fP, and
+.bP
+call \fBwadd_wch\fP for characters which cannot be handled by \fBwaddch\fP.
+.SS TABSIZE
.LP
-The \fBTABSIZE\fR variable is implemented in some versions of curses,
-but is not part of X/Open curses.
+The \fBTABSIZE\fR variable is implemented in SVr4 and other versions of curses,
+but is not part of X/Open curses
+(see \fBcurs_variables\fR(3X) for more details).
.LP
If \fIch\fR is a carriage return,
the cursor is moved to the beginning of the current row of the window.
diff --git a/man/curs_addchstr.3x b/man/curs_addchstr.3x
index 08536e330260..a2f701ce4884 100644
--- a/man/curs_addchstr.3x
+++ b/man/curs_addchstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2017,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,10 +26,15 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addchstr.3x,v 1.16 2012/11/03 22:54:43 tom Exp $
+.\" $Id: curs_addchstr.3x,v 1.18 2019/11/30 21:06:30 tom Exp $
.TH curs_addchstr 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.na
.hy 0
@@ -95,7 +100,7 @@ X/Open does not define 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
+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 NOTES
diff --git a/man/curs_addstr.3x b/man/curs_addstr.3x
index b1cb1cc25c15..87d6b5c5c654 100644
--- a/man/curs_addstr.3x
+++ b/man/curs_addstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2017,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,10 +26,15 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addstr.3x,v 1.17 2012/11/03 22:57:31 tom Exp $
+.\" $Id: curs_addstr.3x,v 1.19 2019/11/30 21:06:30 tom Exp $
.TH curs_addstr 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.na
.hy 0
@@ -89,7 +94,7 @@ if the string pointer is null or
.bP
if the corresponding calls to \fBwaddch\fP return an error.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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 NOTES
diff --git a/man/curs_addwstr.3x b/man/curs_addwstr.3x
index 835cb34010fc..b7576220615e 100644
--- a/man/curs_addwstr.3x
+++ b/man/curs_addwstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2017,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,10 +26,15 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addwstr.3x,v 1.11 2012/11/03 22:57:31 tom Exp $
+.\" $Id: curs_addwstr.3x,v 1.13 2019/11/30 21:06:30 tom Exp $
.TH curs_addwstr 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.na
.hy 0
@@ -91,7 +96,7 @@ if the string pointer is null or
.bP
if the corresponding calls to \fBwadd_wch\fP return an error.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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 NOTES
diff --git a/man/curs_attr.3x b/man/curs_attr.3x
index 7a0d1588d516..cfa04964c71d 100644
--- a/man/curs_attr.3x
+++ b/man/curs_attr.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2013 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,146 +27,256 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_attr.3x,v 1.39 2013/09/21 20:39:49 Sven.Joachim Exp $
+.\" $Id: curs_attr.3x,v 1.65 2019/11/30 21:06:30 tom Exp $
.TH curs_attr 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de NS
+.ie n .sp
+.el .sp .5
+.ie n .in +4
+.el .in +2
+.nf
+.ft C \" Courier
+..
+.de NE
+.fi
+.ft R
+.ie n .in -4
+.el .in -2
+..
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.na
.hy 0
+.\" ---------------------------------------------------------------------------
.SH NAME
+.\" attr_get
+\fBattr_get\fR,
+\fBwattr_get\fR,
+\fBattr_set\fR,
+\fBwattr_set\fR,
+.\" .br
+\fBattr_off\fR,
+\fBwattr_off\fR,
+\fBattr_on\fR,
+\fBwattr_on\fR,
+.\" .br
\fBattroff\fR,
\fBwattroff\fR,
\fBattron\fR,
\fBwattron\fR,
\fBattrset\fR,
\fBwattrset\fR,
+.\" .br
+\fBchgat\fR,
+\fBwchgat\fR,
+\fBmvchgat\fR,
+\fBmvwchgat\fR,
+.\" .br
\fBcolor_set\fR,
\fBwcolor_set\fR,
+.\" .br
\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
+\fBwstandout\fR \- \fBcurses\fR character and window attribute control routines
.ad
.hy
+.\" ---------------------------------------------------------------------------
.SH SYNOPSIS
\fB#include <curses.h>\fR
+.sp
+\fBint attr_get(attr_t *\fP\fIattrs\fP\fB, short *\fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fR
.br
-\fBint attroff(int attrs);\fR
-.br
-\fBint wattroff(WINDOW *win, int attrs);\fR
+\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 attron(int attrs);\fR
+\fBint attr_set(attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fR
.br
-\fBint wattron(WINDOW *win, int attrs);\fR
+\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
+.sp
+\fBint attr_off(attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR
.br
-\fBint attrset(int attrs);\fR
+\fBint wattr_off(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR
.br
-\fBint wattrset(WINDOW *win, int attrs);\fR
+\fBint attr_on(attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR
.br
-\fBint color_set(short color_pair_number, void* opts);\fR
+\fBint wattr_on(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR
+.sp
+\fBint attroff(int \fP\fIattrs);\fR
.br
-\fBint wcolor_set(WINDOW *win, short color_pair_number,\fR
- \fBvoid* opts);\fR
+\fBint wattroff(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR
.br
-\fBint standend(void);\fR
-.br
-\fBint wstandend(WINDOW *win);\fR
-.br
-\fBint standout(void);\fR
-.br
-\fBint wstandout(WINDOW *win);\fR
-.br
-\fBint attr_get(attr_t *attrs, short *pair, void *opts);\fR
-.br
-\fBint wattr_get(WINDOW *win, attr_t *attrs, short *pair,\fR
- \fBvoid *opts);\fR
+\fBint attron(int \fP\fIattrs\fP\fB);\fR
.br
-\fBint attr_off(attr_t attrs, void *opts);\fR
+\fBint wattron(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR
.br
-\fBint wattr_off(WINDOW *win, attr_t attrs, void *opts);\fR
+\fBint attrset(int \fP\fIattrs\fP\fB);\fR
.br
-\fBint attr_on(attr_t attrs, void *opts);\fR
+\fBint wattrset(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR
+.sp
+\fBint chgat(int \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB, short \fP\fIpair\fP\fB,\fR \fBconst void *\fP\fIopts\fP\fB);\fR
.br
-\fBint wattr_on(WINDOW *win, attr_t attrs, void *opts);\fR
+\fBint wchgat(WINDOW *\fP\fIwin\fP\fB,\fP
+ \fBint \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB,\fR \fBshort \fP\fIpair\fP\fB, const void *\fP\fIopts\fP\fB);\fR
.br
-\fBint attr_set(attr_t attrs, short pair, void *opts);\fR
+\fBint mvchgat(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB,\fP
+ \fBint \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB,\fR \fBshort \fP\fIpair\fP\fB, const void *\fP\fIopts\fP\fB);\fR
.br
-\fBint wattr_set(WINDOW *win, attr_t attrs, short pair, void *opts);\fR
+\fBint mvwchgat(WINDOW *\fP\fIwin, int \fP\fIy, int \fP\fIx\fP\fB,\fP
+ \fBint \fP\fIn,\fR \fBattr_t \fP\fIattr\fP\fB, short \fP\fIpair\fP\fB, const void *\fP\fIopts\fP\fB);\fR
+.sp
+\fBint color_set(short \fP\fIpair\fP\fB, void* \fP\fIopts\fP\fB);\fR
.br
-\fBint chgat(int n, attr_t attr, short color,\fR
- \fBconst void *opts)\fR
-.br
-\fBint wchgat(WINDOW *win, int n, attr_t attr,\fR
- \fBshort color, const void *opts)\fR
+\fBint wcolor_set(WINDOW *\fP\fIwin\fP\fB, short \fP\fIpair\fP\fB,\fR \fBvoid* \fP\fIopts);\fR
+.sp
+\fBint standend(void);\fR
.br
-\fBint mvchgat(int y, int x, int n, attr_t attr,\fR
- \fBshort color, const void *opts)\fR
+\fBint wstandend(WINDOW *\fP\fIwin\fP\fB);\fR
.br
-\fBint mvwchgat(WINDOW *win, int y, int x, int n,\fR
- \fBattr_t attr, short color, const void *opts)\fR
+\fBint standout(void);\fR
.br
+\fBint wstandout(WINDOW *\fP\fIwin\fP\fB);\fR
+.\" ---------------------------------------------------------------------------
.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. Attributes are
+.PP
+These routines manipulate the current attributes of the named window,
+which then apply to all characters that are written into
+the window with \fBwaddch\fR, \fBwaddstr\fR and \fBwprintw\fR.
+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
+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.
.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
erasing and clearing.
.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.
+Routines which do not have a \fBWINDOW*\fP parameter apply to \fBstdscr\fP.
+For example,
+\fBattr_set\fP is the \fBstdscr\fP variant of \fBwattr_set\fP.
+.\" ---------------------------------------------------------------------------
+.SS Window attributes
+.PP
+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 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.
-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.
+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:
+.NS
+attrset(A_BOLD | COLOR_PAIR(\fIpair\fP));
+attr_set(A_BOLD, \fIpair\fP, NULL);
+.NE
+.PP
+However, if the value does not fit, then the \fBCOLOR_PAIR\fP macro
+uses only the bits that fit.
+For example, because in ncurses \fBA_COLOR\fP has eight (8) bits,
+then \fBCOLOR_PAIR(\fP\fI259\fP\fB)\fP 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:
+.NS
+int value = A_BOLD | COLOR_PAIR(\fIinput\fP);
+int \fIoutput\fP = PAIR_NUMBER(value);
+.NE
+.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:
+compatibility.
+.PP
+The remaining \fBattr\fR* functions operate exactly like the corresponding
+\fBattr_\fR* functions, except that they take arguments of type \fBint\fR
+rather than \fBattr_t\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 Change character rendition
.PP
The routine \fBchgat\fR changes the attributes of a given number of characters
-starting at the current cursor location of \fBstdscr\fR. It does not update
-the cursor and does not perform wrapping. A character count of \-1 or greater
+starting at the current cursor location of \fBstdscr\fR.
+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
+end of the current line.
+The \fBwchgat\fR function generalizes this to any window;
+the \fBmvwchgat\fR 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\fR, see \fBcurs_color\fR(3X)).
+.\" ---------------------------------------------------------------------------
+.SS Change window color
+The routine \fBcolor_set\fR sets the current color of the given window to the
+foreground/background combination described by the color \fIpair\fP parameter.
+.\" ---------------------------------------------------------------------------
+.SS Standout
+.PP
+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
+X/Open 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.
+.\" ---------------------------------------------------------------------------
+.SH VIDEO 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.
+characters passed to \fBaddch\fR (see \fBcurs_addch\fR(3X)).
.PP
.RS
.TS
-l l
+l l
_ _ _
l l .
\fIName\fR \fIDescription\fR
@@ -182,7 +292,7 @@ l l .
\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
+\fBA_COLOR\fR Bit-mask to extract a color (legacy routines)
.TE
.RE
.PP
@@ -190,7 +300,7 @@ These video attributes are supported by \fBattr_on\fP and related functions
(which also support the attributes recognized by \fBattron\fP, etc.):
.RS
.TS
-l l
+l l
_ _ _
l l .
\fIName\fR \fIDescription\fR
@@ -203,59 +313,226 @@ l l .
.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.
+These functions may be macros:
+.sp
+.RS
+\fBattroff\fR, \fBwattroff\fR, \fBattron\fR, \fBwattron\fR,
+\fBattrset\fR, \fBwattrset\fR, \fBstandend\fR and \fBstandout\fR.
+.RE
.PP
-\fBCOLOR_PAIR\fP values can only be OR'd with attributes if the pair
+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.
+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 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
+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
+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
+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.
+.RS
+.TS
+l l l l l l
+_ _ _ _ _ _
+l l l l l l .
+\fIYear\fR \fISystem\fR \fIArch\fP \fIColor\fR \fIChar\fR \fINotes\fR
+1992 Solaris 5.2 32 6 17 SVr4 curses
+1992 HPUX 9 32 no 8 SVr2 curses
+1992 AIX 3.2 32 no 23 SVr2 curses
+1994 OSF/1 r3 32 no 23 SVr2 curses
+1995 HP-UX 10.00 32 6 16 SVr3 \*(``curses_colr\*(''
+1995 HP-UX 10.00 32 6 8 SVr4, X/Open curses
+1995 Solaris 5.4 32/64 7 16 X/Open curses
+1996 AIX 4.2 32 7 16 X/Open curses
+1996 OSF/1 r4 32 6 16 X/Open curses
+1997 HP-UX 11.00 32 6 8 X/Open curses
+2000 U/Win 32/64 7/31 16 uses \fBchtype\fP
+.TE
+.RE
+.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 ncurses, 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.
+He moved \fIstandout\fP attribute to a structure member.
+.IP
+The resulting 4.4BSD curses was replaced by ncurses over the next ten years.
+.bP
+U/Win is rarely used now.
+.\" ---------------------------------------------------------------------------
+.SH EXTENSIONS
+.PP
+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
+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,
+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
+retrieving it via the standard pointer to \fBshort\fP parameter.
+.PP
+The remaining functions which have \fIopts\fP,
+but do not manipulate color,
+e.g., \fBwattr_on\fP and \fBwattr_off\fP
+are not used by this implementation except to check that they are \fBNULL\fP.
+.\" ---------------------------------------------------------------------------
.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.
+These functions are supported in the XSI Curses standard, Issue 4.
+The standard defined the dedicated type for highlights,
+\fBattr_t\fR, which was not defined in SVr4 curses.
+The functions taking \fBattr_t\fR 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\fR to force the screen to match the updated attributes.
.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". Under this implementation as well as
+\fBA_UNDERLINE\fR 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).
.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.
-.PP
-XSI Curses added the new entry points, \fBattr_get\fR, \fBattr_on\fR,
+XSI Curses added these entry points:
+.sp
+.RS
+\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
+\fBwattr_get\fR, \fBwattr_set\fR
+.RE
+.PP
+The new functions are intended to work with
a new series of highlight macros prefixed with \fBWA_\fR.
The older macros have direct counterparts in the newer set of names:
.PP
.RS
.ne 9
.TS
-l l
+l l
_ _ _
l l .
\fIName\fR \fIDescription\fR
@@ -270,13 +547,26 @@ l l .
.TE
.RE
.PP
-Older 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
+XSI 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
The XSI curses standard specifies that each pair of corresponding \fBA_\fR
and \fBWA_\fR-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.
.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,
@@ -284,23 +574,28 @@ The XSI standard extended conformance level adds new highlights
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.
.PP
X/Open does not define any error conditions.
.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.
+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 with a "mv" prefix first perform a cursor movement using
+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 SEE ALSO
+.na
\fBcurses\fR(3X),
\fBcurs_addch\fR(3X),
\fBcurs_addstr\fR(3X),
diff --git a/man/curs_beep.3x b/man/curs_beep.3x
index c6af6f09e647..a2a24933df3e 100644
--- a/man/curs_beep.3x
+++ b/man/curs_beep.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2005,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2010,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,7 +26,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_beep.3x,v 1.12 2010/12/04 18:36:44 tom Exp $
+.\" $Id: curs_beep.3x,v 1.13 2018/07/28 21:34:06 tom Exp $
.TH curs_beep 3X ""
.SH NAME
\fBbeep\fR, \fBflash\fR \- \fBcurses\fR bell and screen flash routines
@@ -40,9 +40,12 @@
.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
+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
(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,
diff --git a/man/curs_bkgd.3x b/man/curs_bkgd.3x
index 67e2ab8fc54a..c973b98ae6e7 100644
--- a/man/curs_bkgd.3x
+++ b/man/curs_bkgd.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2003,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,7 +26,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_bkgd.3x,v 1.22 2010/12/04 18:36:44 tom Exp $
+.\" $Id: curs_bkgd.3x,v 1.29 2019/07/13 21:01:06 tom Exp $
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.TH curs_bkgd 3X ""
.SH NAME
\fBbkgdset\fR, \fBwbkgdset\fR,
@@ -35,57 +39,121 @@
.SH SYNOPSIS
\fB#include <curses.h>\fR
.PP
-\fBvoid bkgdset(chtype ch);\fR
+\fBvoid bkgdset(chtype \fP\fIch\fP\fB);\fR
.br
-\fBvoid wbkgdset(WINDOW *win, chtype ch);\fR
+\fBvoid wbkgdset(WINDOW *\fP\fIwin, chtype \fP\fIch\fP\fB);\fR
.br
-\fBint bkgd(chtype ch);\fR
+\fBint bkgd(chtype \fP\fIch\fP\fB);\fR
.br
-\fBint wbkgd(WINDOW *win, chtype ch);\fR
+\fBint wbkgd(WINDOW *\fP\fIwin\fP\fB, chtype \fP\fIch\fP\fB);\fR
.br
-\fBchtype getbkgd(WINDOW *win);\fR
+\fBchtype getbkgd(WINDOW *\fP\fIwin\fP\fB);\fR
.br
.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
+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.
.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
.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:
+and then apply this setting to every character position in that window.
+According to X/Open Curses, it should do this:
.PP
-.RS
+.bP
The rendition of every character on the screen is changed to
the new background rendition.
-.PP
+.bP
Wherever the former background character
appears, it is changed to the new background character.
-.RE
+.PP
+Neither X/Open Curses nor the SVr4 manual pages give details about
+the way the rendition of characters on the screen is updated when
+\fBbkgd\fP or \fBwbkgd\fP is used to change the background character.
+.PP
+This implementation, like SVr4 curses, does not store the background
+and window attribute contributions to each cell separately.
+It updates the rendition by comparing the character, non-color attributes and
+colors contained in the background.
+For each cell in the window, whether or not it is blank:
+.bP
+The library first compares the \fIcharacter\fP,
+and if it matches the current character part of the background,
+it replaces that with the new background character.
+.bP
+The library then checks if the cell uses color,
+i.e., 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 that matches the color in the current background,
+the library removes attributes
+which may have come from the current background
+and adds attributes from the new background.
+It finishes by setting the cell
+to use the color from the new background.
+.bP
+If the cell uses color,
+and that does not match the color in the current background,
+the library updates only the non-color attributes,
+first removing those which may have come from the current background,
+and then adding attributes from the new background.
+.PP
+If the background's character value is zero, a space is assumed.
+.PP
+If the terminal does not support color,
+or if color has not been started with \fBstart_color\fP,
+the new background character's color attribute will be ignored.
+.SS getbkgd
.PP
The \fBgetbkgd\fR function returns the given window's current background
character/attribute pair.
.SH RETURN VALUE
-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.
-.SH NOTES
-Note that \fBbkgdset\fR and \fBbkgd\fR may be macros.
-.SH PORTABILITY
+.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.
+.PP
+The routines \fBbkgd\fR and \fBwbkgd\fR return the integer \fBOK\fR,
+unless the library has not been initialized.
+.PP
+In contrast,
+the SVr4.0 manual says \fBbkgd\fR and \fBwbkgd\fR may return \fBOK\fP
+"or a non-negative integer if \fBimmedok\fR is set",
+which refers to the return value from \fBwrefresh\fP
+(used to implement the immediate repainting).
+The SVr4 curses \fBwrefresh\fP returns the number of characters
+written to the screen during the refresh.
+This implementation does not do that.
+.SH NOTES
+.PP
+Note that \fBbkgdset\fR and \fBbkgd\fR may be macros.
+.PP
+X/Open Curses mentions that the character part of the background must
+be a single-byte value.
+This implementation, like SVr4, checks to ensure that,
+and will reuse the old background character if the check fails.
+.SH PORTABILITY
+.PP
+These functions are described in the XSI Curses standard, Issue 4
+(X/Open Curses).
.SH SEE ALSO
+.na
+.PP
\fBcurses\fR(3X),
\fBcurs_addch\fR(3X),
\fBcurs_attr\fR(3X),
diff --git a/man/curs_bkgrnd.3x b/man/curs_bkgrnd.3x
index 08ea59f10217..78ee92e18e32 100644
--- a/man/curs_bkgrnd.3x
+++ b/man/curs_bkgrnd.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-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,7 +26,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_bkgrnd.3x,v 1.5 2012/11/03 23:03:59 tom Exp $
+.\" $Id: curs_bkgrnd.3x,v 1.10 2018/12/09 00:50:50 tom Exp $
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.TH curs_bkgrnd 3X ""
.SH NAME
\fBbkgrnd\fR,
@@ -52,12 +56,15 @@
\fBint wgetbkgrnd(WINDOW *\fR\fIwin\fR\fB, cchar_t *\fR\fIwch\fR\fB);\fR
.br
.SH DESCRIPTION
+.SS bkgrndset
+.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
+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
@@ -67,34 +74,47 @@ insert/delete line/character operations.
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
.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:
-.RS
-.PP
+.bP
The rendition of every character on the screen is changed to
the new background rendition.
-.PP
+.bP
Wherever the former background character
appears, it is changed to the new background character.
-.RE
+.SS getbkgrnd
.PP
The \fBgetbkgrnd\fR function returns the given window's current background
character/attribute pair via the \fBwch\fR pointer.
-.
+If the given window pointer is null,
+the character is not updated (but no error returned).
.SH NOTES
Note that
\fBbkgrnd\fR,
\fBbkgrndset\fR, and
\fBgetbkgrnd\fR
may be macros.
+.PP
+X/Open Curses does not provide details on how the rendition is changed.
+This implementation follows the approach used in SVr4 curses,
+which is explained in the manual page for \fBwbkgd\fP.
.SH RETURN VALUE
+.PP
The \fBbkgrndset\fR and \fBwbkgrndset\fR routines do not return a value.
.PP
Upon successful completion, the other functions return \fBOK\fR.
-Otherwise, they return \fBERR\fR.
+Otherwise, they return \fBERR\fR:
+.bP
A null window pointer is treated as an error.
+.bP
+A null character pointer is treated as an error.
+.SH PORTABILITY
+.PP
+These functions are described in the XSI Curses standard, Issue 4
+(X/Open Curses).
.SH SEE ALSO
\fBcurses\fR(3X),
\fBcurs_bkgd\fR(3X)
diff --git a/man/curs_border.3x b/man/curs_border.3x
index 5a58e9db5583..bbd9d8f325b0 100644
--- a/man/curs_border.3x
+++ b/man/curs_border.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_border.3x,v 1.22 2010/12/04 18:36:44 tom Exp $
+.\" $Id: curs_border.3x,v 1.24 2019/11/30 21:06:30 tom Exp $
.TH curs_border 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.na
.hy 0
.SH NAME
@@ -121,23 +125,28 @@ 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.
.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
+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
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
+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
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
+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.
.PP
X/Open does not define 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
+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 NOTES
diff --git a/man/curs_border_set.3x b/man/curs_border_set.3x
index c9621ac74b35..77e6cc3f79fa 100644
--- a/man/curs_border_set.3x
+++ b/man/curs_border_set.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2011,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2012,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_border_set.3x,v 1.11 2012/11/03 23:03:59 tom Exp $
+.\" $Id: curs_border_set.3x,v 1.12 2019/11/30 21:06:30 tom Exp $
.TH curs_border_set 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.na
.hy 0
.SH NAME
@@ -196,7 +200,7 @@ Otherwise, they return
.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
+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 SEE ALSO
diff --git a/man/curs_clear.3x b/man/curs_clear.3x
index 305c608a49ca..8668feb8225d 100644
--- a/man/curs_clear.3x
+++ b/man/curs_clear.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2016,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,7 +26,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_clear.3x,v 1.14 2010/12/04 18:36:44 tom Exp $
+.\" $Id: curs_clear.3x,v 1.16 2018/07/28 21:34:06 tom Exp $
.TH curs_clear 3X ""
.na
.hy 0
@@ -70,7 +70,8 @@ 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.
+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
@@ -90,18 +91,20 @@ functions using a window pointer parameter return an error if it is null.
Note that \fBerase\fR, \fBwerase\fR, \fBclear\fR, \fBwclear\fR,
\fBclrtobot\fR, and \fBclrtoeol\fR may be macros.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4. The
+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.
.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
+\fBtouchwin(stdscr)\fR or \fBclear(stdscr)\fR.
+This will not work under
ncurses.
.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.
diff --git a/man/curs_color.3x b/man/curs_color.3x
index 2f63c848bc1a..965af772af65 100644
--- a/man/curs_color.3x
+++ b/man/curs_color.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2009,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,197 +26,444 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_color.3x,v 1.35 2010/12/20 00:50:58 tom Exp $
+.\" $Id: curs_color.3x,v 1.61 2019/01/20 17:04:08 tom Exp $
.TH curs_color 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.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,
+\fBinit_pair\fR,
+\fBinit_color\fR,
+\fBinit_extended_pair\fR,
+\fBinit_extended_color\fR,
\fBcolor_content\fR,
\fBpair_content\fR,
-\fBCOLOR_PAIR\fR \- \fBcurses\fR color manipulation routines
+\fBextended_color_content\fR,
+\fBextended_pair_content\fR,
+\fBreset_color_pairs\fR,
+\fBCOLOR_PAIR\fR,
+\fBPAIR_NUMBER\fR \- \fBcurses\fR color manipulation routines
.ad
.hy
.SH SYNOPSIS
-\fB# include <curses.h>\fR
+\fB#include <curses.h>\fR
.sp
\fBint start_color(void);\fR
+.sp
+\fBbool has_colors(void);\fR
.br
+\fBbool can_change_color(void);\fR
+.sp
\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
+/* extensions */
.br
-\fBbool can_change_color(void);\fR
+\fBint init_extended_pair(int pair, int f, int b);\fR
.br
+\fBint init_extended_color(int color, int r, int g, int b);\fR
+.sp
\fBint color_content(short color, short *r, short *g, short *b);\fR
.br
\fBint pair_content(short pair, short *f, short *b);\fR
.br
+/* extensions */
+.br
+\fBint extended_color_content(int color, int *r, int *g, int *b);\fR
+.br
+\fBint extended_pair_content(int pair, int *f, int *b);\fR
+.sp
+/* extensions */
+.br
+\fBvoid reset_color_pairs(void);\fR
+.sp
+\fBint COLOR_PAIR(int n);\fR
+.br
+\fBPAIR_NUMBER(\fR\fIattrs\fR\fB);\fP
+.br
.SH DESCRIPTION
.SS Overview
-\fBcurses\fR support 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).
+\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.
+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)
+can be used to 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,
+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
-programmer can change the colors. The routine \fBcolor_content\fR allows a
+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
+initialized color.
+The routine \fBpair_content\fR allows a programmer to find
out how a given color-pair is currently defined.
-.SS Routine Descriptions
-The \fBstart_color\fR 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 initializes
-eight basic colors (black, red, green, yellow, blue, magenta, cyan,
-and white), and two global variables, \fBCOLORS\fR and
+.SS Color Rendering
+The \fBcurses\fP library combines these inputs to produce the
+actual foreground and background colors shown on the screen:
+.bP
+per-character video attributes (e.g., via \fBwaddch\fP),
+.bP
+the window attribute (e.g., by \fBwattrset\fP), and
+.bP
+the background character (e.g., \fBwbkgdset\fP).
+.PP
+Per-character and window attributes are usually set by a parameter containing
+video attributes including a color pair value.
+Some functions such as \fBwattr_set\fP use a separate parameter which
+is the color pair number.
+.PP
+The background character is a special case: it includes a character value,
+just as if it were passed to \fBwaddch\fP.
+.PP
+The \fBcurses\fP library does the actual work of combining these color
+pairs in an internal function called from \fBwaddch\fP:
+.bP
+If the parameter passed to \fBwaddch\fP is \fIblank\fP,
+and it uses the special color pair 0,
+.RS
+.bP
+\fBcurses\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.
+.bP
+Otherwise, \fBcurses\fP uses the background character.
+.RE
+.bP
+If the parameter passed to \fBwaddch\fP is \fInot blank\fP,
+or it does not use the special color pair 0,
+\fBcurses\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.
+Those do not combine its parameter with a color pair.
+Consequently those calls use only the window attribute or
+the background character.
+.SH CONSTANTS
+.PP
+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
+.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 \fBstart_color\fP to the maximum number of colors
+the terminal can support.
+.SS COLOR_PAIRS
+is initialized by \fBstart_color\fP to the maximum number of color pairs
+the terminal can support.
+.SH FUNCTIONS
+.SS start_color
+The \fBstart_color\fR 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:
+.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 also restores the
-colors on the terminal to the values they had when the terminal was
-just turned on.
+and color-pairs the terminal can support).
+.bP
+It initializes the special color pair \fB0\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
+initializes its internal table representing the
+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).
+The table is initialized first for eight basic colors
+(black, red, green, yellow, blue, magenta, cyan, and white),
+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
+to match its built-in table.
+An application may use \fBinit_color\fP to alter the internal table
+along with the terminal's color.
.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
+These limits apply to color values and color pairs.
+Values outside these limits are not legal, and may result in a runtime error:
+.bP
+\fBCOLORS\fP corresponds to the terminal database's \fBmax_colors\fR capability,
+(see \fBterminfo\fR(\*n)).
+.bP
+color values are expected to be in the range \fB0\fP to \fBCOLORS\-1\fP,
+inclusive (including \fB0\fP and \fBCOLORS\-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(3X)).
+.bP
+\fBCOLOR_PAIRS\fP corresponds to
+the terminal database's \fBmax_pairs\fP capability,
+(see \fBterminfo\fR(\*n)).
+.bP
+legal color pair values are in the range \fB1\fP to \fBCOLOR_PAIRS\-1\fP,
+inclusive.
+.bP
+color pair \fB0\fP is special; it denotes \*(``no color\*(''.
+.IP
+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.
+.SS has_colors
+.PP
+The \fBhas_colors\fR routine requires no arguments.
+It returns \fBTRUE\fR if
+the terminal can manipulate colors; otherwise, it returns \fBFALSE\fR.
+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.
+.SS can_change_color
+.PP
+The \fBcan_change_color\fR routine requires no arguments.
+It returns \fBTRUE\fR if the terminal supports colors
+and can change their definitions;
+other, it returns \fBFALSE\fR.
+This routine facilitates writing terminal-independent programs.
+.SS init_pair
+.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 value of the first argument
-must be between \fB1\fR and \fBCOLOR_PAIRS\-1\fR,
-except that if default colors are used (see \fBuse_default_colors\fP)
+The first argument must be a legal color pair value.
+If default colors are used (see \fBuse_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 value of the second and
-third arguments must be between 0 and \fBCOLORS\fR.
-Color pair 0 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.
+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
+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 0 via
-the \fBassume_default_colors\fR routine, or to specify the use of
+As an extension, ncurses allows you to set color pair \fB0\fP via
+the \fBassume_default_colors\fR(3X) 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 value of the first
-argument must be between \fB0\fR and \fBCOLORS\fR. (See the section
-\fBColors\fR for the default color index.) Each of the last three arguments
-must be a value between 0 and 1000. When \fBinit_color\fR is used, all
+\fBuse_default_colors\fR(3X) routine.
+.SS init_extended_pair
+.PP
+Because \fBinit_pair\fP uses signed \fBshort\fPs for its parameters,
+that limits color-pairs and color-values
+to 32767 on modern hardware.
+The extension \fBinit_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
+.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).
+.bP
+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.)
+.bP
+Each of the last three arguments
+must be a value in the range \fB0\fP through \fB1000\fP.
+.PP
+When \fBinit_color\fR is used, all
occurrences of that color on the screen immediately change to the new
definition.
+.SS init_extended_color
.PP
-The \fBhas_colors\fR routine requires no arguments. It returns \fBTRUE\fR if
-the terminal can manipulate colors; otherwise, it returns \fBFALSE\fR. 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 and can change their definitions;
-other, it returns \fBFALSE\fR. This routine facilitates writing
-terminal-independent programs.
+Because \fBinit_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 \fBinit_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
.PP
The \fBcolor_content\fR 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
+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 value of the first argument must be between 0 and
-\fBCOLORS\fR. The values that are stored at the addresses pointed to by the
-last three arguments are between 0 (no component) and 1000 (maximum amount of
-component).
+given color.
+.bP
+The first argument must be a legal color value, i.e.,
+\fB0\fP through \fBCOLORS\-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.
+.SS extended_color_content
+.PP
+Because \fBcolor_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 \fBextended_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
.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
+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 value of the first argument must be between 1
-and \fBCOLOR_PAIRS\-1\fR. The values that are stored at the addresses pointed
-to by the second and third arguments are between 0 and \fBCOLORS\fR.
-.SS Colors
-In \fB<curses.h>\fR the following macros are defined. These are the default
-colors. \fBcurses\fR also assumes that \fBCOLOR_BLACK\fR is the default
-background color for all terminals.
+background color numbers.
+.bP
+The first argument must be a legal color value,
+i.e., in the range \fB1\fP through \fBCOLOR_PAIRS\-1\fR, 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 extended_pair_content
.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
+Because \fBpair_content\fP uses signed \fBshort\fPs for its parameters,
+that limits color-pair and color-values to 32767 on modern hardware.
+The extension \fBextended_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
+.PP
+The extension \fBreset_color_pairs\fP tells ncurses to discard all
+of the color-pair information which was set with \fBinit_pair\fP.
+It also touches the current- and standard-screens, allowing an application to
+switch color palettes rapidly.
+.SS PAIR_NUMBER
+.PP
+\fBPAIR_NUMBER(\fR\fIattrs\fR) extracts the color
+value from its \fIattrs\fP parameter and returns it as a color pair number.
+.SS COLOR_PAIR
+Its inverse \fBCOLOR_PAIR(\fR\fIn\fR\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 \fBattr_set\fP (which pass the color pair as a separate parameter)
+rather than the legacy functions such as \fBattrset\fP.
.SH RETURN VALUE
-The routines \fBcan_change_color()\fR and \fBhas_colors()\fR return \fBTRUE\fR
+The routines \fBcan_change_color\fR and \fBhas_colors\fR return \fBTRUE\fR
or \fBFALSE\fR.
.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.
+(SVr4 specifies only \*(``an integer value
+other than \fBERR\fR\*('') upon successful completion.
.PP
X/Open defines no error conditions.
+SVr4 does document some error conditions which apply in general:
+.bP
This implementation will return \fBERR\fR on attempts to
-use color values outside the range 0 to COLORS\-1
+use color values outside the range \fB0\fP to \fBCOLORS\fP\-1
(except for the default colors extension),
-or use color pairs outside the range 0 to COLOR_PAIRS\-1.
-Color values used in \fBinit_color\fP must be in the range 0 to 1000.
+or use color pairs outside the range \fB0\fP to \fBCOLOR_PAIRS\-1\fP.
+.IP
+Color values used in \fBinit_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.
+.IP
An error is returned from secondary functions such as \fBinit_pair\fP
if \fBstart_color\fP was not called.
+.bP
+SVr4 does much the same, except that
+it returns \fBERR\fP from \fBpair_content\fP if the pair was not initialized
+using \fBinit_pairs\fP
+and
+it returns \fBERR\fP from \fBcolor_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
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 \fBinitialize_color\fP capability is absent
from the terminal description.
.TP 5
\fBstart_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
+In the \fBncurses\fR implementation, there is a separate color activation flag,
+color palette, color pairs table,
+and associated \fBCOLORS\fP and \fBCOLOR_PAIRS\fP counts
for each screen; the \fBstart_color\fR function only affects the current
-screen. The SVr4/XSI interface is not really designed with this in mind, and
+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
-character cells that a character write operation explicitly touches. To change
+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).
.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.
+COLOR_YELLOW is actually brown.
+To get yellow, use COLOR_YELLOW combined with the \fBA_BOLD\fR 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
+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 PORTABILITY
@@ -224,17 +471,28 @@ This implementation satisfies XSI Curses's minimum maximums
for \fBCOLORS\fR and \fBCOLOR_PAIRS\fR.
.PP
The \fBinit_pair\fP routine accepts negative values of foreground
-and background color to support the \fBuse_default_colors\fP extension,
+and background color to support the \fBuse_default_colors\fR(3X) extension,
but only if that routine has been first invoked.
.PP
The assumption that \fBCOLOR_BLACK\fR is the default
background color for all terminals can be modified using the
-\fBassume_default_colors\fP extension.
+\fBassume_default_colors\fR(3X) extension.
.PP
This implementation checks the pointers,
e.g., for the values returned by
\fBcolor_content\fP and \fBpair_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 \fBreset_color_pairs\fP function is an extension of ncurses.
.SH SEE ALSO
\fBcurses\fR(3X),
\fBcurs_initscr\fR(3X),
diff --git a/man/curs_delch.3x b/man/curs_delch.3x
index 6dfc0a05896d..04b9044aad5e 100644
--- a/man/curs_delch.3x
+++ b/man/curs_delch.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_delch.3x,v 1.11 2010/12/04 18:36:44 tom Exp $
+.\" $Id: curs_delch.3x,v 1.13 2019/11/30 21:06:30 tom Exp $
.TH curs_delch 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.SH NAME
\fBdelch\fR,
\fBwdelch\fR,
@@ -47,21 +51,24 @@
.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
+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.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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 NOTES
Note that \fBdelch\fR, \fBmvdelch\fR, and \fBmvwdelch\fR may be macros.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4. The
+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 SEE ALSO
diff --git a/man/curs_deleteln.3x b/man/curs_deleteln.3x
index 83cbdec7e9a8..91415ac8a764 100644
--- a/man/curs_deleteln.3x
+++ b/man/curs_deleteln.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2010,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,7 +26,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_deleteln.3x,v 1.13 2010/12/04 18:36:44 tom Exp $
+.\" $Id: curs_deleteln.3x,v 1.14 2018/07/28 21:34:06 tom Exp $
.TH curs_deleteln 3X ""
.SH NAME
\fBdeleteln\fR,
@@ -53,13 +53,18 @@
.SH DESCRIPTION
The \fBdeleteln\fR and \fBwdeleteln\fR 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.
+\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.
.PP
The \fBinsertln\fR and \fBwinsertln\fR routines insert a blank line above the
current line and the bottom line is lost.
@@ -72,14 +77,16 @@ 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
+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.
.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
+terminal.
+In fact, they will not use hardware line delete/insert unless
\fBidlok(..., TRUE)\fR has been set on the current window.
.SH SEE ALSO
\fBcurses\fR(3X)
diff --git a/man/curs_extend.3x b/man/curs_extend.3x
index 9a52f93080f4..77960c8d436b 100644
--- a/man/curs_extend.3x
+++ b/man/curs_extend.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1999-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1999-2016,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 *
@@ -28,7 +28,7 @@
.\"
.\" Author: Thomas E. Dickey 1999-on
.\"
-.\" $Id: curs_extend.3x,v 1.19 2010/12/04 18:36:44 tom Exp $
+.\" $Id: curs_extend.3x,v 1.22 2018/07/28 21:34:06 tom Exp $
.TH curs_extend 3X ""
.SH NAME
\fBcurses_version\fP,
@@ -43,14 +43,14 @@
.SH DESCRIPTION
These functions are extensions to the curses library
which do not fit easily into other categories.
+.SS curses_version
.PP
-Use
-.I curses_version()
+Use \fBcurses_version\fP
to get the version number, including patch level of the library, e.g.,
.B 5.0.19991023
+.SS use_extended_names
.PP
-The
-.I 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,9 +60,18 @@ is made by using the \fB\-x\fP option of \fB@TIC@\fP to compile
extended terminal definitions.
However you can disable this feature
to ensure compatibility with other implementations of curses.
+.SH RETURN VALUE
+.PP
+\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 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 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),
diff --git a/man/curs_get_wch.3x b/man/curs_get_wch.3x
index df9bc6a6e6c6..52c57c93baf4 100644
--- a/man/curs_get_wch.3x
+++ b/man/curs_get_wch.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,14 +26,26 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_get_wch.3x,v 1.8 2012/11/03 23:03:59 tom Exp $
+.\" $Id: curs_get_wch.3x,v 1.12 2019/11/30 21:06:30 tom Exp $
.TH curs_get_wch 3X ""
+.na
+.hy 0
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.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
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
.sp
@@ -76,13 +88,8 @@ 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
-in
-\fB<curses.h>\fR
-and returning
-\fBKEY_CODE_YES\fR.
+to the keycode assigned to the function key,
+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
@@ -92,6 +99,18 @@ 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 keycodes returned by these functions are the same as those
+returned by \fBwgetch\fP:
+.bP
+The predefined function
+keys are listed in \fB<curses.h>\fR as macros with values outside the range
+of 8-bit characters.
+Their names begin with \fBKEY_\fR.
+.bP
+Other (user-defined) function keys
+which may be defined using \fBdefine_key\fP(3X) have no names,
+but also are expected to have values outside the range of 8-bit characters.
+.PP
The
\fBunget_wch\fR
function pushes the wide character
@@ -153,7 +172,7 @@ returns
Otherwise, the function returns
\fBERR\fR.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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 SEE ALSO
diff --git a/man/curs_get_wstr.3x b/man/curs_get_wstr.3x
index 2a3fb3ce27bf..23ddb6dc6d81 100644
--- a/man/curs_get_wstr.3x
+++ b/man/curs_get_wstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,16 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_get_wstr.3x,v 1.9 2012/11/03 23:03:59 tom Exp $
+.\" $Id: curs_get_wstr.3x,v 1.19 2019/11/30 20:59:22 tom Exp $
.TH curs_get_wstr 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.na
.hy 0
.SH NAME
@@ -66,18 +74,23 @@ 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.
+\fBget_wch\fR(3X)
+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.
.PP
-The user's erase and kill characters are interpreted. If keypad
+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.
.PP
-Characters input are echoed only if \fBecho\fR is currently on. In that case,
+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
@@ -155,20 +168,49 @@ Functions using a window parameter return an error if it is null.
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
+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 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.
+This implementation returns \fBERR\fP if the window pointer is null,
+or if the lower-level \fBwget_wch\fR call returns an \fBERR\fP.
In the latter case,
-an ERR return without other data is treated as an end-of-file condition,
+an \fBERR\fP 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.
+X/Open curses documented these functions to pass an array of \fBwchar_t\fR
+in 1997, but that was an error because of this part of the description:
+.RS
+.PP
+The effect of \fIget_wstr()\fP is as though a series of calls to
+\fIget_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\fR, following the standard.
+.PP
+X/Open Curses, Issue 7 (2009) is unclear regarding whether
+the terminating \fInull \fP\fBwchar_t\fP
+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,
+ncurses 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 ncurses 6.1 in this regard,
+treating a \fB\-1\fP as an indefinite number of characters.
.SH SEE ALSO
Functions:
\fBcurses\fR(3X),
diff --git a/man/curs_getcchar.3x b/man/curs_getcchar.3x
index a974c738a8c3..43f97fd43411 100644
--- a/man/curs_getcchar.3x
+++ b/man/curs_getcchar.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2001-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 2001-2017,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,10 +26,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getcchar.3x,v 1.16 2012/11/03 23:03:59 tom Exp $
+.\" $Id: curs_getcchar.3x,v 1.23 2019/11/30 22:22:32 tom Exp $
.TH curs_getcchar 3X ""
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.SH NAME
\fBgetcchar\fP,
@@ -59,8 +60,9 @@
.br
.B " short \fIcolor_pair\fP,"
.br
-.B " void *\fIopts\fP );"
+.B " const void *\fIopts\fP );"
.SH DESCRIPTION
+.SS getcchar
.PP
The \fBgetcchar\fP function gets a wide-character string
and rendition from a \fBcchar_t\fP argument.
@@ -88,6 +90,7 @@ 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
by using:
@@ -108,10 +111,23 @@ Additional nonspacing characters are ignored.
.IP
The string may contain a single control character instead.
In that case, no nonspacing characters are allowed.
-.SH NOTES
+.SH EXTENSIONS
.PP
-The \fIopts\fP argument is reserved for future use.
-Currently, an application must provide a null pointer as \fIopts\fP.
+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 NOTES
.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.
@@ -129,6 +145,53 @@ and \fBERR\fP otherwise.
.PP
Upon successful completion, \fBsetcchar\fP returns \fBOK\fP.
Otherwise, it returns \fBERR\fP.
+.SH PORTABILITY
+The \fBCCHARW_MAX\fP symbol is specific to ncurses.
+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
+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 xpg4 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
.PP
Functions:
diff --git a/man/curs_getch.3x b/man/curs_getch.3x
index a8b2ffea1868..fbebd45d0b15 100644
--- a/man/curs_getch.3x
+++ b/man/curs_getch.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2011,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,12 +27,17 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getch.3x,v 1.37 2012/07/07 20:04:56 tom Exp $
+.\" $Id: curs_getch.3x,v 1.54 2019/11/30 21:06:30 tom Exp $
.TH curs_getch 3X ""
.na
.hy 0
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.SH NAME
\fBgetch\fR,
@@ -48,17 +53,18 @@
.PP
\fBint getch(void);\fR
.br
-\fBint wgetch(WINDOW *win);\fR
+\fBint wgetch(WINDOW *\fP\fIwin);\fR
.br
-\fBint mvgetch(int y, int x);\fR
+\fBint mvgetch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR
.br
-\fBint mvwgetch(WINDOW *win, int y, int x);\fR
+\fBint mvwgetch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR
.br
-\fBint ungetch(int ch);\fR
+\fBint ungetch(int \fP\fIch\fP\fB);\fR
.br
-\fBint has_key(int ch);\fR
+\fBint has_key(int \fP\fIch\fP\fB);\fR
.br
.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.
@@ -71,25 +77,42 @@ In half-delay mode,
the program waits until a character is typed or the
specified timeout has been reached.
.PP
-Unless \fBnoecho\fR has been set,
+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:
-if the character is the current erase character, left arrow, or backspace,
+.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.
+.bP
If the character value is any other \fBKEY_\fR define, the user is alerted
with a \fBbeep\fR call.
+.bP
+If the character is a carriage-return,
+and if \fBnl\fP is enabled,
+it is translated to a line-feed after echoing.
+.bP
Otherwise the character is simply output to the screen.
.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
.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
+that function key is returned instead of the raw characters:
+.bP
+The predefined function
+keys are listed in \fB<curses.h>\fR as macros with values outside the range
+of 8-bit characters.
+Their names begin with \fBKEY_\fR.
+.bP
+Other (user-defined) function keys which may be defined
+using \fBdefine_key\fP(3X)
+have no names, but also are expected to have values outside the range of
+8-bit characters.
+.PP
+Thus, a variable
intended to hold the return value of a function key must be of short size or
larger.
.PP
@@ -102,21 +125,37 @@ 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.
.PP
+In \fBncurses\fP, the timer normally expires after
+the value in \fBESCDELAY\fP (see \fBcurs_variables\fP(3X)).
+If \fBnotimeout\fP is \fBTRUE\fP, the timer does not expire;
+it is an infinite (or very large) value.
+Because function keys usually begin with an escape character,
+the terminal may appear to hang in notimeout mode after pressing the escape key
+until another key is pressed.
+.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 Function Keys
-The following function keys, defined in \fB<curses.h>\fR, might be returned by
-\fBgetch\fR if \fBkeypad\fR has been enabled.
-Note that not all of these are
-necessarily supported on any particular terminal.
-.sp
+.SS Predefined key-codes
+The following special keys are defined in \fB<curses.h>\fR.
+.bP
+Except for the special case \fBKEY_RESIZE\fP,
+it is necessary to enable \fBkeypad\fR for \fBgetch\fP to return these codes.
+.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 long terminfo capability names for the keys,
+and were defined long ago, in the 1980s.
+.PP
.TS
center tab(/) ;
-l l
l l .
\fIName\fR/\fIKey\fR \fIname\fR
+_
KEY_BREAK/Break key
KEY_DOWN/The four arrow keys ...
KEY_UP
@@ -216,7 +255,7 @@ KEY_UNDO/Undo key
.TE
.PP
Keypad is arranged like this:
-.sp
+.br
.TS
center allbox tab(/) ;
c c c .
@@ -225,31 +264,55 @@ c c c .
\fBC1\fR/\fBdown\fR/\fBC3\fR
.TE
.sp
-The \fBhas_key\fR routine takes a key value from the above list, and
-returns TRUE or FALSE according to whether
+A few of these predefined values do \fInot\fP correspond to a real key:
+.bP
+.B KEY_RESIZE
+is returned when the \fBSIGWINCH\fP signal has been detected
+(see \fBinitscr\fP(3X) and \fBresizeterm\fR(3X)).
+This code is returned whether or not \fBkeypad\fP has been enabled.
+.bP
+.B KEY_MOUSE
+is returned for mouse-events (see \fBcurs_mouse\fR(3X)).
+This code relies upon whether or not \fBkeypad\fP(3X) has been enabled,
+because (e.g., with \fIxterm\fP mouse prototocol) ncurses must
+read escape sequences,
+just like a function key.
+.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.
-Note that a few values do not correspond to a real key,
-e.g., \fBKEY_RESIZE\fP and \fBKEY_MOUSE\fP.
-See \fBresizeterm\fR(3X) for more details about \fBKEY_RESIZE\fP, and
-\fBcurs_mouse\fR(3X) for a discussion of \fBKEY_MOUSE\fP.
+.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
.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
+other than \fBERR\fR (\fBOK\fR in the case of \fBungetch\fP) upon successful
completion.
.RS 3
.TP 5
\fBungetch\fP
-returns ERR
+returns \fBERR\fP
if there is no more room in the FIFO.
.TP
\fBwgetch\fP
-returns ERR
+returns \fBERR\fP
if the window pointer is null, or
-if its timeout expires without having any data.
+if its timeout expires without having any data, or
+if the execution was interrupted by a signal (\fBerrno\fR will be set to
+\fBEINTR\fR).
.RE
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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 NOTES
@@ -257,8 +320,10 @@ 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.
.PP
-Note that 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 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.
@@ -276,10 +341,10 @@ the \fIEnter\fP key on the regular keyboard is already handled by
the standard ASCII characters for carriage-return and line-feed,
.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
+pressing \*(``Enter\*('' on the regular keyboard
+may return either a carriage-return or line-feed, and finally
.bP
-"Enter or send" is the standard description for this key.
+\*(``Enter or send\*('' is the standard description for this key.
.PP
When using \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR, or
\fBmvwgetch\fR, nocbreak mode (\fBnocbreak\fR) and echo mode
@@ -320,12 +385,17 @@ 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.
.PP
+\fBKEY_MOUSE\fP is mentioned in XSI Curses, along with a few related
+terminfo capabilities, but no higher-level functions use the feature.
+The implementation in ncurses is an extension.
+.PP
+\fBKEY_RESIZE\fP is an extension first implemented for ncurses.
+NetBSD curses later added this extension.
+.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
+interrupts \fBgetch\fR and causes it to return \fBERR\fP with \fBerrno\fR set to
\fBEINTR\fR.
-Under the \fBncurses\fR implementation, handled signals never
-interrupt \fBgetch\fR.
.PP
The \fBhas_key\fR function is unique to \fBncurses\fR.
We recommend that
@@ -337,6 +407,7 @@ any code using it be conditionalized on the \fBNCURSES_VERSION\fR feature macro.
\fBcurs_mouse\fR(3X),
\fBcurs_move\fR(3X),
\fBcurs_refresh\fR(3X),
+\fBcurs_variables\fR(3X),
\fBresizeterm\fR(3X).
.PP
Comparable functions in the wide-character (ncursesw) library are
diff --git a/man/curs_getstr.3x b/man/curs_getstr.3x
index e548cf145c25..818dc9035a0e 100644
--- a/man/curs_getstr.3x
+++ b/man/curs_getstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2005,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,16 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getstr.3x,v 1.19 2010/12/04 18:36:44 tom Exp $
+.\" $Id: curs_getstr.3x,v 1.28 2019/07/20 19:14:56 tom Exp $
.TH curs_getstr 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.na
.hy 0
.SH NAME
@@ -63,25 +71,35 @@
.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.
+not included in the returned string).
+.\" X/Open says also until EOf
+.\" X/Open says then an EOS is added to the result
+.\" X/Open doesn't mention n<0
+The resulting value is placed in the
+area pointed to by the character pointer \fIstr\fR,
+followed by a NUL.
.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
+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.
.PP
-The user's erase and kill characters are interpreted. If keypad
+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.
.PP
-Characters input are echoed only if \fBecho\fR is currently on. In that case,
+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).
.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
+specifies only \*(``an integer value other than \fBERR\fR\*('') upon successful
completion.
.PP
X/Open defines no error conditions.
@@ -92,10 +110,10 @@ if the window pointer is null, or
if its timeout expires without having any data.
.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
+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 NOTES
@@ -104,18 +122,70 @@ Note that \fBgetstr\fR, \fBmvgetstr\fR, and \fBmvwgetstr\fR may be macros.
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.
+This implementation returns \fBERR\fP if the window pointer is null,
+or if the lower-level \fBwgetch\fR(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\fR.) 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
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 do, some do not count it:
+.bP
+ncurses 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
+ncurses (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
+ncurses 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,
+ncurses uses the POSIX value for \fBLINE_MAX\fP (a 2048 byte limit).
+In either case, it reserves a byte for the terminating NUL.
.SH SEE ALSO
\fBcurses\fR(3X),
\fBcurs_getch\fR(3X),
diff --git a/man/curs_in_wch.3x b/man/curs_in_wch.3x
index 5f50e5a89fde..84294d8014ef 100644
--- a/man/curs_in_wch.3x
+++ b/man/curs_in_wch.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_in_wch.3x,v 1.5 2010/12/04 18:36:44 tom Exp $
+.\" $Id: curs_in_wch.3x,v 1.8 2019/11/30 21:06:30 tom Exp $
.TH curs_in_wch 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.SH NAME
\fBin_wch\fR,
\fBmvin_wch\fR,
@@ -49,12 +53,12 @@ the current position in the named window into the \fBcchar_t\fR object
referenced by wcval.
.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
+This implementation checks for null pointers, returns \fBERR\fP in that case.
+Also, the \fImv\fR 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
+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 NOTES
diff --git a/man/curs_in_wchstr.3x b/man/curs_in_wchstr.3x
index f92968779623..dda9f2487311 100644
--- a/man/curs_in_wchstr.3x
+++ b/man/curs_in_wchstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_in_wchstr.3x,v 1.9 2012/11/03 23:03:59 tom Exp $
+.\" $Id: curs_in_wchstr.3x,v 1.12 2019/11/30 21:06:30 tom Exp $
.TH curs_in_wchstr 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.na
.hy 0
.SH NAME
@@ -92,7 +96,8 @@ with
\fBmvwin_wchstr\fR
or
\fBwin_wchstr\fR
-causes undefined results. Therefore, the use of
+causes undefined results.
+Therefore, the use of
\fBin_wchnstr\fR,
\fBmvin_wchnstr\fR,
\fBmvwin_wchnstr\fR, or
@@ -104,13 +109,13 @@ Upon successful completion, these functions return
Otherwise, they return
\fBERR\fR.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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 PORTABILITY
The XSI 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),
diff --git a/man/curs_inch.3x b/man/curs_inch.3x
index 7e1e3b439177..15698c8c6637 100644
--- a/man/curs_inch.3x
+++ b/man/curs_inch.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,8 +27,16 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inch.3x,v 1.17 2010/12/04 18:36:44 tom Exp $
+.\" $Id: curs_inch.3x,v 1.22 2019/11/30 21:06:30 tom Exp $
.TH curs_inch 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
\fBinch\fR,
\fBwinch\fR,
@@ -47,8 +55,10 @@
.br
.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
+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
extract the character or attributes alone.
.
@@ -62,16 +72,47 @@ l l .
\fBA_COLOR\fR Bit-mask to extract color-pair field information
.TE
.SH RETURN VALUE
-Functions with a "mv" prefix first perform a cursor movement using
+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.
+.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).
.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
+.TP 5
+\fBcurses\fR(3X)
+gives an overview of the WINDOW and \fBchtype\fP data types.
+.TP 5
+\fBcurs_attr\fR(3X)
+goes into more detail, pointing out portability problems and
+constraints on the use of \fBchtype\fP for returning window information.
+.TP 5
+\fBcurs_in_wch\fR(3X)
+describes comparable functions for the wide-character (ncursesw) library.
diff --git a/man/curs_inchstr.3x b/man/curs_inchstr.3x
index 2dc7673c3768..b7ba45071774 100644
--- a/man/curs_inchstr.3x
+++ b/man/curs_inchstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 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,8 +26,16 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inchstr.3x,v 1.15 2010/12/04 18:36:44 tom Exp $
+.\" $Id: curs_inchstr.3x,v 1.18 2018/07/28 21:34:06 tom Exp $
.TH curs_inchstr 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.na
.hy 0
.SH NAME
@@ -63,7 +71,8 @@
.SH DESCRIPTION
These routines return a NULL-terminated array of \fBchtype\fR 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
+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
(exclusive of the trailing (chtype)0).
Constants defined in \fB<curses.h>\fR can be used with the \fB&\fR (logical
@@ -74,22 +83,27 @@ All routines return the integer \fBERR\fR upon failure and an integer value
other than \fBERR\fR 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.
+In this implementation:
+.bP
+If the \fIwin\fP parameter is null, an error is returned,
+.bP
+If the \fIchstr\fP parameter is null, an error is returned,
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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 NOTES
-Note that all routines except \fBwinchnstr\fR may be macros. SVr4 does not
+Note that all routines except \fBwinchnstr\fR may be macros.
+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
+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).
diff --git a/man/curs_initscr.3x b/man/curs_initscr.3x
index 0dceb973d1e6..d08043dc192b 100644
--- a/man/curs_initscr.3x
+++ b/man/curs_initscr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2012,2013 Free Software Foundation, Inc. *
+.\" Copyright (c) 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,8 +26,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_initscr.3x,v 1.19 2013/07/20 19:34:14 tom Exp $
+.\" $Id: curs_initscr.3x,v 1.31 2018/07/28 22:15:59 tom Exp $
.TH curs_initscr 3X ""
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.ie \n(.g .ds '' \(rq
@@ -52,57 +56,91 @@
.br
\fBbool isendwin(void);\fR
.br
-\fBSCREEN *newterm(char *type, FILE *outfd, FILE *infd);\fR
+\fBSCREEN *newterm(const char *\fP\fItype\fP\fB, FILE *\fP\fIoutfd\fP\fB, FILE *\fP\fIinfd\fP\fB);\fR
.br
-\fBSCREEN *set_term(SCREEN *new);\fR
+\fBSCREEN *set_term(SCREEN *\fP\fInew\fP\fB);\fR
.br
-\fBvoid delscreen(SCREEN* sp);\fR
+\fBvoid delscreen(SCREEN* \fP\fIsp\fP\fB);\fR
.br
.SH DESCRIPTION
+.SS initscr
\fBinitscr\fR is normally the first \fBcurses\fR 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. For multiple-terminal applications, \fBnewterm\fR may be
-called before \fBinitscr\fR.
+initializing a program.
+A few special routines sometimes need to be called before it;
+these are \fBslk_init\fR(3X), \fBfilter\fR, \fBripoffline\fR,
+\fBuse_env\fR.
+For multiple-terminal applications,
+\fBnewterm\fR may be called before \fBinitscr\fR.
.PP
The initscr code determines the terminal type and initializes all \fBcurses\fR
-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
-message to standard error and exits; otherwise, a pointer is returned to
-\fBstdscr\fR.
+data structures.
+\fBinitscr\fR also causes the first call to \fBrefresh\fR(3X)
+to clear the screen.
+If errors occur, \fBinitscr\fR writes an appropriate error
+message to standard error and exits;
+otherwise, a pointer is returned to \fBstdscr\fR.
+.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 needs to
-inspect capabilities, so it can continue to run in a line-oriented mode if the
+routine for each terminal instead of \fBinitscr\fR.
+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
-as a reference to that terminal. The arguments are the \fItype\fR of the
-terminal to be used in place of \fB$TERM\fR, a file pointer for output to the
-terminal, and another file pointer for input from the terminal (if \fItype\fR
-is \fBNULL\fR, \fB$TERM\fR will be used). The program must also call
+\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
+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,
+.bP
+a file pointer for output to the terminal, and
+.bP
+another file pointer for input from the terminal
+.PP
+If the \fItype\fR parameter is \fBNULL\fR, \fB$TERM\fR will be used.
+.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.
.PP
A program should always call \fBendwin\fR before exiting or escaping from
-\fBcurses\fR mode temporarily. This routine restores tty modes, moves the
-cursor to the lower left-hand corner of the screen and resets the terminal into
-the proper non-visual mode. Calling \fBrefresh\fR or \fBdoupdate\fR after a
+\fBcurses\fR mode temporarily.
+This routine
+.bP
+resets colors to correspond with the default color pair 0,
+.bP
+moves the cursor to the lower left-hand corner of the screen,
+.bP
+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(3X) or \fBdoupdate\fR(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.
+called without any subsequent calls to \fBwrefresh\fR,
+and \fBFALSE\fR 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 previous terminal is returned by the routine. This is
-the only routine which manipulates \fBSCREEN\fR pointers; all other
-routines affect only the current terminal.
+The \fBset_term\fR routine is used to switch between different terminals.
+The screen reference \fBnew\fR becomes the new current terminal.
+The previous terminal is returned by the routine.
+This is the only routine which manipulates \fBSCREEN\fR 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
+\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.
.SH RETURN VALUE
@@ -113,26 +151,104 @@ Routines that return pointers always return \fBNULL\fR on error.
.PP
X/Open defines no error conditions.
In this implementation
+.bP
\fBendwin\fP returns an error if the terminal was not initialized.
-.SH NOTES
-Note that \fBinitscr\fR and \fBnewterm\fR may be macros.
+.bP
+\fBnewterm\fP
+returns an error if it cannot allocate the data structures for the screen,
+or for the top-level windows within the screen,
+i.e.,
+\fBcurscr\fP, \fBnewscr\fP, or \fBstdscr\fP.
+.bP
+\fBset_term\fP
+returns no error.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4. It
-specifies that portable applications must not call \fBinitscr\fR more than
-once.
+These functions were described in the XSI Curses standard, 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:
+.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.
+.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
.PP
If the TERM 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(3X) and cannot be
-used for full-screen operation.
+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:
+.RS 5
+.PP
+\fICurses implementations may provide for special handling of the \fBSIGINT\fP,
+\fBSIGQUIT\fP and \fBSIGTSTP\fP signals
+if their disposition is \fBSIG_DFL\fP at the time
+\fBinitscr\fP is called \fP...
+.PP
+\fIAny 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
+.PP
+\fINone of the Curses functions are required to be safe
+with respect to signals \fP...
+.RE
+.PP
+This implementation establishes signal handlers during initialization,
+e.g., \fBinitscr\fP or \fBnewterm\fP.
+Applications which must handle these signals should set up the corresponding
+handlers \fIafter\fP initializing the library:
+.TP 5
+.B SIGINT
+The handler \fIattempts\fP to cleanup 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
+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.
+.RE
+.TP 5
+.B SIGTERM
+This uses the same handler as \fBSIGINT\fP, with the same limitations.
+It is not mentioned in X/Open Curses, but is more suitable for this
+purpose than \fBSIGQUIT\fP (which is used in debugging).
+.TP 5
+.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
+assuming that it has been completely altered.
+It also updates the saved terminal modes with \fBdef_shell_mode\fP
+(see \fBcurs_kernel\fR(3X)).
+.TP 5
+.B SIGWINCH
+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)).
+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),
diff --git a/man/curs_inopts.3x b/man/curs_inopts.3x
index 2e637ce30b64..214edd748edc 100644
--- a/man/curs_inopts.3x
+++ b/man/curs_inopts.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2012,2013 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,7 +26,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inopts.3x,v 1.18 2013/07/20 19:42:02 tom Exp $
+.\" $Id: curs_inopts.3x,v 1.28 2019/01/20 20:39:35 tom Exp $
.TH curs_inopts 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
@@ -92,122 +92,184 @@
\fBint typeahead(int fd);\fR
.br
.SH DESCRIPTION
+The \fBncurses\fP library provides several functions which 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.
+.\"
+.SS cbreak
Normally, the tty driver buffers typed characters until a newline or carriage
-return is typed. The \fBcbreak\fR routine disables line buffering and
+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
-program. The \fBnocbreak\fR routine returns the terminal to normal (cooked)
+program.
+The \fBnocbreak\fR 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.
+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.]
+.\"
+.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
+the user are echoed by \fBgetch\fR(3X) 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. Authors of most interactive programs prefer to do
+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.]
+.\"
+.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
+available to the program.
+However, after blocking for \fItenths\fR tenths of
+seconds, \fBERR\fP is returned if nothing has been typed.
+The value of \fItenths\fR
+must be a number between 1 and 255.
+Use \fBnocbreak\fR 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
+If the \fBintrflush\fR option is enabled (\fIbf\fR is \fBTRUE\fR), and 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 screen.
+Disabling the option (\fIbf\fR is \fBFALSE\fR) prevents the
+flush.
+The default for the option is inherited from the tty driver settings.
The window argument is ignored.
+.\"
+.SS keypad
.PP
-The \fBkeypad\fR option enables the keypad of the user's terminal. If
+The \fBkeypad\fR 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. If disabled
+(such as an arrow key) and \fBwgetch\fR(3X) returns a single value
+representing the function key, as in \fBKEY_LEFT\fR.
+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
+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. The default value for keypad is false.
+causes the terminal keypad to be turned on when \fBwgetch\fR(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)].
+input depends on the control mode of the tty driver [see \fBtermios\fP(3)].
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
+on the terminal.
+To force 7 bits to be returned, invoke
\fBmeta\fR(\fIwin\fR, \fBFALSE\fR); 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
+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.
+.\"
+.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. If disabled
+If no input is ready, \fBgetch\fR returns \fBERR\fR.
+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
-while waiting for the next character. If \fBnotimeout(\fR\fIwin\fR,
-\fBTRUE\fR) is called, then \fBwgetch\fR does not set a timer. The
+While interpreting an input escape sequence, \fBwgetch\fR(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
+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
+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
+\fBSUSP\fR characters will not be done [see \fBtermios\fP(3)].
+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
+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,
+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
+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,
plus the additional capability of being able to block for only
\fIdelay\fR milliseconds (where \fIdelay\fR 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,
the current update is postponed until
-\fBrefresh\fR or \fBdoupdate\fR is called again.
+\fBrefresh\fR(3X) or \fBdoupdate\fR 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
+\fIfd\fR is to be used to check for typeahead instead.
+If \fIfd\fR 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\fR upon failure and \fBOK\fP
+(SVr4 specifies only \*(``an integer value other than \fBERR\fR\*('')
+upon successful completion,
+unless otherwise noted in the preceding routine descriptions.
.PP
X/Open does not define any error conditions.
In this implementation,
@@ -225,27 +287,29 @@ These functions are described in the XSI Curses standard, Issue 4.
.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
-initializes the terminal state. BSD curses differed from this slightly; it
+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
+off as a side-effect.
+For best portability, set echo or noecho 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.
If the terminal description includes extended string capabilities,
-e.g., from using the \fB\-x\fP option of @TIC@,
+e.g., from using the \fB\-x\fP option of \fB@TIC@\fP,
then ncurses also defines keys for the capabilities whose names
-begin with "k".
+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).
+(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
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 \fBtigetstr\fP,
and reassign the keycode to match its own needs.
.PP
Low-level applications can use \fBtigetstr\fP to obtain the definition
@@ -271,8 +335,9 @@ Note that \fBecho\fR, \fBnoecho\fR, \fBhalfdelay\fR, \fBintrflush\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
+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 SEE ALSO
\fBcurses\fR(3X),
@@ -280,4 +345,4 @@ control states that are hard to predict or understand; it is not recommended.
\fBcurs_initscr\fR(3X),
\fBcurs_util\fR(3X),
\fBdefine_key\fR(3X),
-\fBtermio\fR(7)
+\fBtermios\fR(3)
diff --git a/man/curs_ins_wch.3x b/man/curs_ins_wch.3x
index 4c6a925e9963..5873f48e4066 100644
--- a/man/curs_ins_wch.3x
+++ b/man/curs_ins_wch.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2017,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_ins_wch.3x,v 1.5 2010/12/04 18:38:55 tom Exp $
+.\" $Id: curs_ins_wch.3x,v 1.7 2019/11/30 21:06:30 tom Exp $
.TH curs_ins_wch 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.SH NAME
\fBins_wch\fR,
\fBmvins_wch\fR,
@@ -50,10 +54,10 @@ 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.
+If successful, these functions return \fBOK\fP.
+If not, they return \fBERR\fP.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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
diff --git a/man/curs_ins_wstr.3x b/man/curs_ins_wstr.3x
index 12479b0d9306..595748ac3b65 100644
--- a/man/curs_ins_wstr.3x
+++ b/man/curs_ins_wstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2017,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_ins_wstr.3x,v 1.7 2012/11/03 23:03:59 tom Exp $
+.\" $Id: curs_ins_wstr.3x,v 1.9 2019/11/30 21:06:30 tom Exp $
.TH curs_ins_wstr 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.na
.hy 0
.SH NAME
@@ -93,10 +97,10 @@ functions will fail.
XSI does not define what will happen if a nonspacing character follows
a control character.
.SH RETURN VALUE
-Upon successful completion, these functions return OK.
-Otherwise, they return ERR.
+Upon successful completion, these functions return \fBOK\fP.
+Otherwise, they return \fBERR\fP.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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 SEE ALSO
diff --git a/man/curs_insch.3x b/man/curs_insch.3x
index 77e92ec0bed7..2cd69aac08e7 100644
--- a/man/curs_insch.3x
+++ b/man/curs_insch.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_insch.3x,v 1.13 2010/12/04 18:38:55 tom Exp $
+.\" $Id: curs_insch.3x,v 1.16 2019/11/30 21:06:30 tom Exp $
.TH curs_insch 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.SH NAME
\fBinsch\fR,
\fBwinsch\fR,
@@ -46,15 +50,17 @@
.br
.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
+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.
+All routines that return an integer return \fBERR\fR upon failure and \fBOK\fP
+(SVr4 specifies only "an integer value other than \fBERR\fR")
+upon successful completion,
+unless otherwise noted in the preceding routine descriptions.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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 NOTES
diff --git a/man/curs_insstr.3x b/man/curs_insstr.3x
index 3e38a531d5fb..93142d769898 100644
--- a/man/curs_insstr.3x
+++ b/man/curs_insstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2017,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_insstr.3x,v 1.21 2010/12/04 18:38:55 tom Exp $
+.\" $Id: curs_insstr.3x,v 1.23 2019/11/30 21:06:30 tom Exp $
.TH curs_insstr 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.SH NAME
\fBinsstr\fR,
\fBinsnstr\fR,
@@ -70,16 +74,17 @@ If \fIn\fR<=0, then the entire string is inserted.
.PP
Special characters are handled as in \fBaddch\fP.
.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\fR upon failure and \fBOK\fP
+(SVr4 specifies only "an integer value other than \fBERR\fR")
+upon successful completion,
+unless otherwise noted in the preceding routine descriptions.
.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.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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 NOTES
diff --git a/man/curs_instr.3x b/man/curs_instr.3x
index 1b17db952d11..2c148bc404dd 100644
--- a/man/curs_instr.3x
+++ b/man/curs_instr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 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,8 +26,16 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_instr.3x,v 1.16 2010/12/04 18:38:55 tom Exp $
+.\" $Id: curs_instr.3x,v 1.19 2018/07/28 21:34:06 tom Exp $
.TH curs_instr 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
\fBinstr\fR,
\fBinnstr\fR,
@@ -59,19 +67,22 @@
.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
+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).
.SH RETURN VALUE
All of the functions return \fBERR\fR 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.
+In this implementation:
+.bP
+If the \fIwin\fP parameter is null, an error is returned,
+.bP
+If the \fIchstr\fP parameter is null, an error is returned,
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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 NOTES
diff --git a/man/curs_inwstr.3x b/man/curs_inwstr.3x
index 0cdf4d8df65b..a2779aca1d3b 100644
--- a/man/curs_inwstr.3x
+++ b/man/curs_inwstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inwstr.3x,v 1.8 2012/11/03 23:03:59 tom Exp $
+.\" $Id: curs_inwstr.3x,v 1.12 2019/11/30 21:06:30 tom Exp $
.TH curs_inwstr 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.SH NAME
\fBinwstr\fR,
\fBinnwstr\fR,
@@ -41,48 +45,58 @@
.nf
\fB#include <curses.h> \fR
.sp
-\fBint inwstr(\fR\fBwchar_t *\fR\fIstr\fR\fB);\fR
+\fBint inwstr(\fR\fBwchar_t *\fR\fIwstr\fR\fB);\fR
.br
-\fBint innwstr(\fR\fBwchar_t *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
+\fBint innwstr(\fR\fBwchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
.br
-\fBint winwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, wchar_t *\fR\fIstr\fR\fB);\fR
+\fBint winwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, wchar_t *\fR\fIwstr\fR\fB);\fR
.br
-\fBint winnwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, wchar_t *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
+\fBint winnwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, wchar_t *\fR\fIwstr\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
+\fBint mvinwstr(\fR\fBint \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIwstr\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
+\fBint mvinnwstr(\fR\fBint \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIwstr\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
+\fBint mvwinwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIwstr\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
+\fBint mvwinnwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
.fi
.SH DESCRIPTION
-These routines return a string of \fBwchar_t\fR characters in \fIwstr\fR,
+.PP
+These routines return a string of \fBwchar_t\fR wide 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
+.PP
+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).
+Transfer stops at the end of the current line, or when \fIn\fR characters have
been stored at the location referenced by \fIwstr\fR.
.PP
-If the size \fIn\fR is not large enough to store a complete character,
+If the size \fIn\fR is not large enough to store a complete complex character,
an error is generated.
.SH NOTES
-Note that all routines except
+.PP
+All routines except
\fBwinnwstr\fR
may be macros.
+.PP
+Each cell in the window holds a complex character (i.e., base-
+and combining-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.
.SH RETURN VALUE
All routines return
\fBERR\fR
-upon failure. Upon
+upon failure.
+Upon
successful completion, the *\fBinwstr\fR
routines return
\fBOK\fR, and the *\fBinnwstr\fR
routines return the
number of characters read into the string.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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 SEE ALSO
diff --git a/man/curs_kernel.3x b/man/curs_kernel.3x
index d81b134b8d81..144854c6d529 100644
--- a/man/curs_kernel.3x
+++ b/man/curs_kernel.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2005,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,7 +26,15 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_kernel.3x,v 1.19 2010/12/04 18:38:55 tom Exp $
+.\" $Id: curs_kernel.3x,v 1.27 2019/11/30 21:06:30 tom Exp $
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.TH curs_kernel 3X ""
.na
.hy 0
@@ -59,79 +67,111 @@
.br
\fBint savetty(void);\fR
.br
-\fBvoid getsyx(int y, int x);\fR
+\fBvoid getsyx(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR
.br
-\fBvoid setsyx(int y, int x);\fR
+\fBvoid setsyx(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR
.br
-\fBint ripoffline(int line, int (*init)(WINDOW *, int));\fR
+\fBint ripoffline(int \fP\fIline\fP\fB, int (*\fP\fIinit\fP\fB)(WINDOW *, int));\fR
.br
-\fBint curs_set(int visibility);\fR
+\fBint curs_set(int \fP\fIvisibility\fP\fB);\fR
.br
-\fBint napms(int ms);\fR
+\fBint napms(int \fP\fIms\fP\fB);\fR
.br
.SH DESCRIPTION
-The following routines give low-level access to various \fBcurses\fR
-capabilities. These routines typically are used inside library
-routines.
+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"
+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.
+\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.
+the terminal to \*(``program\*('' (in \fBcurses\fR) or \*(``shell\*('' (out of
+\fBcurses\fR) state.
+These are done automatically by \fBendwin\fR(3X) 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
+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.
+.SS getsyx
.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
+The \fBgetsyx\fR routine returns the current coordinates
+of the \fIvirtual screen\fP 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.
.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
+Few applications will use this feature,
+most use \fBgetyx\fP instead.
+.SS setsyx
+.PP
+The \fBsetsyx\fR routine sets
+the \fIvirtual screen\fP 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
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
+of the program's cursor.
+The library routine would call \fBgetsyx\fR
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.
.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. If \fIline\fR is positive, a line is removed
-from the top of \fBstdscr\fR; if \fIline\fR is negative, a line is
-removed from the bottom. When this is done inside \fBinitscr\fR, the
+screen.
+\fBripoffline\fR must be called before \fBinitscr\fR or
+\fBnewterm\fR is called, to prepare these initial actions:
+.bP
+If \fIline\fR is positive, a line is removed from the top of \fBstdscr\fR.
+.bP
+if \fIline\fR 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
-arguments: a window pointer to the one-line window that has been
-allocated and an integer with the number of columns in the window.
+arguments:
+.bP
+a window pointer to the one-line window that has been
+allocated and
+.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.
+accurate and \fBwrefresh\fR or \fBdoupdate\fR must not be called.
+It is allowable to call \fBwnoutrefresh\fR during the initialization routine.
.PP
\fBripoffline\fR can be called up to five times before calling \fBinitscr\fR or
\fBnewterm\fR.
+.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.
+\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.
+.SS napms
.PP
The \fBnapms\fR routine is used to sleep for \fIms\fR milliseconds.
.SH RETURN VALUE
@@ -143,9 +183,12 @@ requested \fIvisibility\fR is not supported.
.PP
X/Open defines no error conditions.
In this implementation
-.RS
.TP 5
+.na
+.hy 0
\fBdef_prog_mode\fR, \fBdef_shell_mode\fR, \fBreset_prog_mode\fR, \fBreset_shell_mode\fR
+.hy
+.ad
return an error
if the terminal was not initialized, or
if the I/O call to obtain the terminal settings fails.
@@ -153,13 +196,13 @@ if the I/O call to obtain the terminal settings fails.
\fBripoffline\fP
returns an error if the maximum number of ripped-off lines
exceeds the maximum (NRIPS = 5).
-.RE
.SH NOTES
Note that \fBgetsyx\fR is a macro, so \fB&\fR is not necessary before
the variables \fIy\fR and \fIx\fR.
.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\fR \*(``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
@@ -169,11 +212,13 @@ invisible or very visible.
There is no way for ncurses 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\fR and \fBgetsyx\fR
+are not described in the XSI Curses standard, Issue 4.
+All other functions are as described in XSI 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\fR and \fBgetsyx\fR
+as having return type int.
+This is misleading, as they are macros with no documented semantics
for the return value.
.SH SEE ALSO
\fBcurses\fR(3X),
diff --git a/man/curs_legacy.3x b/man/curs_legacy.3x
index febaf294174f..9851b9dece08 100644
--- a/man/curs_legacy.3x
+++ b/man/curs_legacy.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2007,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 2007-2017,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,57 +26,82 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_legacy.3x,v 1.5 2010/12/04 18:38:55 tom Exp $
+.\" $Id: curs_legacy.3x,v 1.9 2019/03/23 21:51:12 tom Exp $
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.TH curs_legacy 3X ""
.SH NAME
-getattrs \- get \fBcurses\fR cursor and window coordinates, attributes
+curs_legacy \- get \fBcurses\fP cursor and window coordinates, attributes
.SH SYNOPSIS
-\fB#include <curses.h>\fR
+\fB#include <curses.h>\fP
.sp
-\fBint getattrs(WINDOW *win);\fR
+\fBint getattrs(const WINDOW *win);\fP
.br
-\fBint getbegx(WINDOW *win);\fR
+\fBint getbegx(const WINDOW *win);\fP
.br
-\fBint getbegy(WINDOW *win);\fR
+\fBint getbegy(const WINDOW *win);\fP
.br
-\fBint getcurx(WINDOW *win);\fR
+\fBint getcurx(const WINDOW *win);\fP
.br
-\fBint getcury(WINDOW *win);\fR
+\fBint getcury(const WINDOW *win);\fP
.br
-\fBint getmaxx(WINDOW *win);\fR
+\fBint getmaxx(const WINDOW *win);\fP
.br
-\fBint getmaxy(WINDOW *win);\fR
+\fBint getmaxy(const WINDOW *win);\fP
.br
-\fBint getparx(WINDOW *win);\fR
+\fBint getparx(const WINDOW *win);\fP
.br
-\fBint getpary(WINDOW *win);\fR
+\fBint getpary(const WINDOW *win);\fP
.br
.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 Curses functions:
+.bP
+The \fBgetattrs\fP function returns the same attribute data as \fBwattr_get\fP.
+.IP
+However, \fBgetattrs\fP returns an integer (actually a \fBchtype\fP),
+while \fBwattr_get\fP returns the current color pair in a separate parameter.
+In the wide-character library configuration,
+color pairs may not fit into a \fBchtype\fP,
+so \fBwattr_get\fP is the only way to obtain the color information.
+.IP
+Because \fBgetattrs\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, \fBgetattrs\fP returns \fBA_NORMAL\fP (zero).
+.bP
+The \fBgetbegy\fP and \fBgetbegx\fP functions return the same
+data as \fBgetbegyx\fP.
+.bP
+The \fBgetcury\fP and \fBgetcurx\fP functions return the same
+data as \fBgetyx\fP.
+.bP
+The \fBgetmaxy\fP and \fBgetmaxx\fP functions return the same
+data as \fBgetmaxyx\fP.
+.bP
+The \fBgetpary\fP and \fBgetparx\fP functions return the same
+data as \fBgetparyx\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.
+when \fBNCURSES_OPAQUE\fP 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.
.SH PORTABILITY
These functions were supported on Version 7, BSD or System V implementations.
+None of those implementations checked the window parameter.
+.PP
+The \fBgetattrs\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)
+\fBcurses\fP(3X),
+\fBcurs_getyx\fP(3X),
+\fBcurs_opaque\fP(3X)
diff --git a/man/curs_memleaks.3x b/man/curs_memleaks.3x
index 5ebc0d066fa5..8cea74256378 100644
--- a/man/curs_memleaks.3x
+++ b/man/curs_memleaks.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2008,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 2008-2017,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,44 +26,79 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_memleaks.3x,v 1.3 2010/12/04 18:40:45 tom Exp $
+.\" $Id: curs_memleaks.3x,v 1.7 2019/12/14 23:21:32 tom Exp $
.TH curs_memleaks 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.na
.hy 0
.SH NAME
-\fB_nc_freeall\fP
-\fB_nc_free_and_exit\fP \- \fBcurses\fR memory-leak checking
+\fB_nc_freeall\fP,
+\fB_nc_free_and_exit\fP,
+\fB_nc_free_tinfo\fP \- \fBcurses\fR memory-leak checking
.ad
.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
.sp
+\fBvoid exit_curses(int);\fR
+.br
+\fBvoid exit_terminfo(int);\fR
+.sp
+/* deprecated */
+.br
\fBvoid _nc_freeall(void);\fR
.br
\fBvoid _nc_free_and_exit(int);\fR
+.br
+\fBvoid _nc_free_tinfo(int);\fR
.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.
.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.
+for use in the next call to \fBrefresh\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 ncurses library,
+applications can call functions which free those chunks of memory,
+simplifying the process of memory-leak checking.
+.PP
+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 ncurses.
+.TP 5
+\fB_nc_free_and_exit\fP
+This frees the memory allocated by ncurses (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 \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.
+The \fBexit_curses\fP and \fBexit_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.
.SH SEE ALSO
\fBcurses\fR(3X).
diff --git a/man/curs_mouse.3x b/man/curs_mouse.3x
index 1de85e510851..5e4bc10e9694 100644
--- a/man/curs_mouse.3x
+++ b/man/curs_mouse.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2013 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,7 +27,29 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_mouse.3x,v 1.39 2013/06/22 18:09:42 tom Exp $
+.\" $Id: curs_mouse.3x,v 1.51 2019/07/13 23:45:12 tom Exp $
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de NS
+.ie n .sp
+.el .sp .5
+.ie n .in +4
+.el .in +2
+.nf
+.ft C \" Courier
+..
+.de NE
+.fi
+.ft R
+.ie n .in -4
+.el .in -2
+..
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.TH curs_mouse 3X ""
.na
.hy 0
@@ -54,27 +76,28 @@
.PP
\fBbool has_mouse(void);\fR
.br
-\fBint getmouse(MEVENT *event);\fR
+\fBint getmouse(MEVENT *\fP\fIevent\fP\fB);\fR
.br
-\fBint ungetmouse(MEVENT *event);\fR
+\fBint ungetmouse(MEVENT *\fP\fIevent\fP\fB);\fR
.br
-\fBmmask_t mousemask(mmask_t newmask, mmask_t *oldmask);\fR
+\fBmmask_t mousemask(mmask_t \fP\fInewmask\fP\fB, mmask_t *\fP\fIoldmask\fP\fB);\fR
.br
-\fBbool wenclose(const WINDOW *win, int y, int x);\fR
+\fBbool wenclose(const WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR
.br
-\fBbool mouse_trafo(int* pY, int* pX, bool to_screen);\fR
+\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* win, int* pY, int* pX,\fR
+\fBbool wmouse_trafo(const WINDOW* \fP\fIwin\fP\fB, int* \fP\fIpY\fP\fB, int* \fP\fIpX\fP\fB,\fR
.br
- \fBbool to_screen);\fR
+ \fBbool \fP\fIto_screen\fP\fB);\fR
.br
-\fBint mouseinterval(int erval);\fR
+\fBint mouseinterval(int \fP\fIerval\fP\fB);\fR
.br
.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.
+pseudo-key values in the \fBwgetch\fR(3X) input stream.
+.SS mousemask
.PP
To make mouse events visible, use the \fBmousemask\fR function.
This will set
@@ -89,6 +112,7 @@ window's mouse event mask.
As a side effect, setting a zero mousemask may turn off the mouse pointer;
setting a nonzero mask may turn it on.
Whether this happens is device-dependent.
+.SS Mouse events
.PP
Here are the mouse event type masks which may be defined:
.PP
@@ -134,8 +158,9 @@ ALL_MOUSE_EVENTS report all button state changes
REPORT_MOUSE_POSITION report mouse movement
_
.TE
+.SS getmouse
.PP
-Once a class of mouse events have been made visible in a window,
+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.
To read the event data and pop the event off the queue, call
@@ -150,48 +175,57 @@ indicate the event type.
The corresponding data in the queue is marked invalid.
A subsequent call to \fBgetmouse\fP will retrieve the next older
item from the queue.
+.SS ungetmouse
.PP
The \fBungetmouse\fR function behaves analogously to \fBungetch\fR.
It pushes
a \fBKEY_MOUSE\fR 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
-character-cell coordinates is enclosed by a given window, returning TRUE
-if it is and FALSE otherwise.
+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
to coordinates relative to the given window or vice versa.
-Please remember, that stdscr-relative coordinates are not always identical
+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).
+(see the \fBripoffline\fP and \fBslk_init\fR(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
through the pointers.
If the conversion was successful, the function returns \fBTRUE\fR.
+.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.
-Please notice, that the referenced coordinates
+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.
+.SS mouseinterval
.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
@@ -200,8 +234,9 @@ Use \fBmouseinterval(0)\fR to disable click resolution.
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
.PP
-The \fBhas_mouse\fP function returns TRUE if the mouse driver has been
+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
@@ -211,14 +246,16 @@ termination.
.SH RETURN VALUE
\fBgetmouse\fR and \fBungetmouse\fR
return the integer \fBERR\fR upon failure or \fBOK\fR
-upon successful completion.
-.RS
+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,
-it also returns an error if no more events remain in the queue.
+.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.
@@ -239,13 +276,59 @@ on their test result.
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
+SVr4 curses had support for the mouse in a variant of \fBxterm\fP.
+It is mentioned in a few places, but with no supporting documentation:
+.bP
+the \*(``libcurses\*('' manual page lists functions for this feature
+which are prototyped in \fBcurses.h\fP:
+.NS
+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);
+.NE
+.bP
+the \*(``terminfo\*('' manual page lists capabilities for the feature
+.NS
+buttons btns BT Number of buttons on the mouse
+get_mouse getm Gm Curses should get button events
+key_mouse kmous Km 0631, Mouse event has occurred
+mouse_info minfo Mi Mouse status information
+req_mouse_pos reqmp RQ Request mouse position report
+.NE
+.bP
+the interface made assumptions (as does ncurses) about the escape sequences
+sent to and received from the terminal.
+.IP
+For instance
+the SVr4 curses library used the \fBget_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 \fBreq_mouse_pos\fP capability.
+.IP
+Those features required a terminal which had been modified to work with curses.
+They were not part of the X Consortium's xterm.
+.PP
+When developing the xterm mouse support for 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
+PDCurses 2.3 using the SVr4 interface.
+PDCurses, however, does not use video terminals,
+making it unnecessary to be concerned about compatibility with the
+escape sequences.
+.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
+.RS 3
.TP 3
1
has definitions for reserved events.
@@ -263,13 +346,15 @@ Additional fields may be added to the structure in the future.
Under \fBncurses\fR(3X), these calls are implemented using either
xterm's built-in mouse-tracking API or
platform-specific drivers including
-.RS
+.RS 3
+.bP
Alessandro Rubini's gpm server
-.br
+.bP
FreeBSD sysmouse
-.br
+.bP
OS/2 EMX
.RE
+.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
@@ -280,13 +365,27 @@ this is used in the 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:
-.RS
+.PP
+.RS 3
\\E[?1000%?%p1%{1}%=%th%el%;
.RE
-The z member in the event structure is not presently used.
+.PP
+The mouse driver also recognizes a newer xterm private mode 1006, e.g.,
+.PP
+.RS 3
+\\E[?1006;1000%?%p1%{1}%=%th%el%;
+.RE
+.PP
+The \fIz\fP member in the event structure is not presently used.
It is intended
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.
+They are distinct.
+For example, in xterm,
+wheel/scrolling mice send position reports as a sequence of
+presses of buttons 4 or 5 without matching button-releases.
.SH BUGS
Mouse events under xterm will not in fact be ignored during cooked mode,
if they have been enabled by \fBmousemask\fR.
@@ -295,7 +394,7 @@ report sequence will appear 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"
+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,
@@ -303,9 +402,13 @@ i.e., it is the beginning of the response.
.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.
+if \fBkmous\fR is defined in the terminal description,
+or if the terminal description's primary name or aliases
+contain the string \*(``xterm\*('',
+then the terminal may send mouse events.
+The \fBkmous\fP capability is checked first,
+allowing the use of newer xterm mouse protocols
+such as xterm's private mode 1006.
.SH SEE ALSO
\fBcurses\fR(3X),
\fBcurs_kernel\fR(3X),
diff --git a/man/curs_move.3x b/man/curs_move.3x
index 226595cca6d7..02e733eb8e2b 100644
--- a/man/curs_move.3x
+++ b/man/curs_move.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 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,7 +26,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_move.3x,v 1.14 2010/12/04 18:40:45 tom Exp $
+.\" $Id: curs_move.3x,v 1.17 2018/07/28 21:34:56 tom Exp $
.TH curs_move 3X ""
.na
.hy 0
@@ -44,11 +44,13 @@
.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
+column \fIx\fR.
+This routine does not move the physical cursor of the terminal
+until \fBrefresh\fR(3X) 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
+These routines return \fBERR\fR upon failure and \fBOK\fP (SVr4
specifies only "an integer value other than \fBERR\fR") upon successful
completion.
.PP
diff --git a/man/curs_opaque.3x b/man/curs_opaque.3x
index 8c315ddda432..1596bfff4405 100644
--- a/man/curs_opaque.3x
+++ b/man/curs_opaque.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2007-2010,2013 Free Software Foundation, Inc. *
+.\" Copyright (c) 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,7 +26,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_opaque.3x,v 1.10 2013/07/20 19:42:29 tom Exp $
+.\" $Id: curs_opaque.3x,v 1.13 2015/12/05 20:05:45 tom Exp $
.TH curs_opaque 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
@@ -46,7 +46,10 @@
\fBis_pad\fR,
\fBis_scrollok\fR,
\fBis_subwin\fR,
-\fBis_syncok\fR \- \fBcurses\fR window properties
+\fBis_syncok\fR,
+\fBwgetdelay\fR,
+\fBwgetparent\fR,
+\fBwgetscrreg\fR \- \fBcurses\fR window properties
.ad
.hy
.SH SYNOPSIS
@@ -78,6 +81,8 @@
.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
.SH DESCRIPTION
@@ -110,19 +115,22 @@ returns the value set in \fBnodelay\fR
returns the value set in \fBnotimeout\fR
.TP 5
\fBis_pad\fR
-returns TRUE if the window is a pad
+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
-returns TRUE if the window is a subwindow,
+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.
@@ -131,7 +139,7 @@ or NULL for windows having no parent.
returns the top and bottom rows for the scrolling margin
as set in \fBwsetscrreg\fP.
.SH RETURN VALUE
-These functions all return TRUE or FALSE, except as noted.
+These functions all return \fBTRUE\fP or \fBFALSE\fP, except as noted.
.SH NOTES
Both a macro and a function are provided for each name.
.SH PORTABILITY
diff --git a/man/curs_outopts.3x b/man/curs_outopts.3x
index 52c04cddcf03..828076c22fa4 100644
--- a/man/curs_outopts.3x
+++ b/man/curs_outopts.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 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,7 +26,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_outopts.3x,v 1.25 2010/12/04 18:38:55 tom Exp $
+.\" $Id: curs_outopts.3x,v 1.29 2018/07/28 22:59:02 tom Exp $
.TH curs_outopts 3X ""
.na
.hy 0
@@ -46,21 +46,21 @@
.SH SYNOPSIS
\fB#include <curses.h>\fR
.sp
-\fBint clearok(WINDOW *win, bool bf);\fR
+\fBint clearok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
.br
-\fBint idlok(WINDOW *win, bool bf);\fR
+\fBint idlok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
.br
-\fBvoid idcok(WINDOW *win, bool bf);\fR
+\fBvoid idcok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
.br
-\fBvoid immedok(WINDOW *win, bool bf);\fR
+\fBvoid immedok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
.br
-\fBint leaveok(WINDOW *win, bool bf);\fR
+\fBint leaveok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
.br
-\fBint setscrreg(int top, int bot);\fR
+\fBint setscrreg(int \fP\fItop\fP\fB, int \fP\fIbot\fP\fB);\fR
.br
-\fBint wsetscrreg(WINDOW *win, int top, int bot);\fR
+\fBint wsetscrreg(WINDOW *\fP\fIwin\fP\fB, int \fP\fItop\fP\fB, int \fP\fIbot\fP\fB);\fR
.br
-\fBint scrollok(WINDOW *win, bool bf);\fR
+\fBint scrollok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
.br
\fBint nl(void);\fR
.br
@@ -70,7 +70,8 @@
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.
+It is not necessary to turn these options off before calling \fBendwin\fR(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
@@ -81,6 +82,7 @@ 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
and repainted from scratch.
+.SS idlok
.PP
If \fBidlok\fR is called with \fBTRUE\fR as second argument, \fBcurses\fR
considers using the hardware insert/delete line feature of terminals so
@@ -94,6 +96,7 @@ 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.
+.SS idcok
.PP
If \fBidcok\fR is called with \fBFALSE\fR as second argument, \fBcurses\fR
no longer considers using the hardware insert/delete character feature of
@@ -101,6 +104,7 @@ terminals so equipped.
Use of character insert/delete is enabled by default.
Calling \fBidcok\fR with \fBTRUE\fR 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,
@@ -108,6 +112,7 @@ 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.
+.SS leaveok
.PP
Normally, the hardware cursor is left at the location of the window cursor
being refreshed.
@@ -115,6 +120,7 @@ The \fBleaveok\fR 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
programmer to set a software scrolling region in a window.
@@ -133,6 +139,7 @@ terminal, like that in the VT100.
If \fBidlok\fR 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
@@ -143,12 +150,13 @@ 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).
+\fIvirtual screen\fP).
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
@@ -161,7 +169,7 @@ and \fBERR\fR upon failure.
All other routines that return an integer always
return \fBOK\fR.
.PP
-X/Open does not define any error conditions.
+X/Open Curses does not define any error conditions.
.PP
In this implementation, those functions that have a window pointer
will return an error if the window pointer is null.
@@ -181,8 +189,8 @@ if the window pointer is null.
.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().
+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
@@ -213,6 +221,7 @@ Note that \fBclearok\fR, \fBleaveok\fR, \fBscrollok\fR, \fBidcok\fR, \fBnl\fR,
The \fBimmedok\fR routine is useful for windows that are used as terminal
emulators.
.SH SEE ALSO
+.na
\fBcurses\fR(3X),
\fBcurs_addch\fR(3X),
\fBcurs_clear\fR(3X),
diff --git a/man/curs_overlay.3x b/man/curs_overlay.3x
index 972a95774b14..e3ed63f89f26 100644
--- a/man/curs_overlay.3x
+++ b/man/curs_overlay.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2013 Free Software Foundation, Inc. *
+.\" 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 *
@@ -26,7 +26,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_overlay.3x,v 1.17 2013/04/06 23:48:51 tom Exp $
+.\" $Id: curs_overlay.3x,v 1.18 2015/07/21 00:51:31 tom Exp $
.TH curs_overlay 3X ""
.na
.hy 0
@@ -39,20 +39,22 @@
.SH SYNOPSIS
\fB#include <curses.h>\fR
.sp
-\fBint overlay(const WINDOW *srcwin, WINDOW *dstwin);\fR
+\fBint overlay(const WINDOW *\fP\fIsrcwin\fP\fB, WINDOW *\fP\fIdstwin\fP\fB);\fR
.br
-\fBint overwrite(const WINDOW *srcwin, WINDOW *dstwin);\fR
+\fBint overwrite(const WINDOW *\fP\fIsrcwin\fP\fB, WINDOW *\fP\fIdstwin\fP\fB);\fR
.br
-\fBint copywin(const WINDOW *srcwin, WINDOW *dstwin, int sminrow,\fR
- \fBint smincol, int dminrow, int dmincol, int dmaxrow,\fR
- \fBint dmaxcol, int overlay);\fR
+\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
.PP
The \fBcopywin\fR routine provides a finer granularity of control over the
\fBoverlay\fR and \fBoverwrite\fR routines.
diff --git a/man/curs_pad.3x b/man/curs_pad.3x
index 6ce640b7f691..64cf0081f9c5 100644
--- a/man/curs_pad.3x
+++ b/man/curs_pad.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2005,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 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,7 +26,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_pad.3x,v 1.17 2010/12/04 18:41:07 tom Exp $
+.\" $Id: curs_pad.3x,v 1.25 2018/07/28 22:20:54 tom Exp $
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.TH curs_pad 3X ""
.na
.hy 0
@@ -42,21 +46,22 @@
.SH SYNOPSIS
\fB#include <curses.h>\fR
.sp
-\fBWINDOW *newpad(int nlines, int ncols);\fR
+\fBWINDOW *newpad(int \fP\fInlines\fP\fB, int \fP\fIncols\fP\fB);\fR
.br
-\fBWINDOW *subpad(WINDOW *orig, int nlines, int ncols,\fR
- \fBint begin_y, int begin_x);\fR
+\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 *pad, int pminrow, int pmincol,\fR
- \fBint sminrow, int smincol, int smaxrow, int smaxcol);\fR
+\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 *pad, int pminrow, int pmincol,\fR
- \fBint sminrow, int smincol, int smaxrow, int smaxcol);\fR
+\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 *pad, chtype ch);\fR
+\fBint pechochar(WINDOW *\fP\fIpad\fP\fB, chtype \fP\fIch\fP\fB);\fR
.br
-\fBint pecho_wchar(WINDOW *pad, const cchar_t *wch);\fR
+\fBint pecho_wchar(WINDOW *\fP\fIpad\fP\fB, const cchar_t *\fP\fIwch\fP\fB);\fR
.SH DESCRIPTION
+.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.
@@ -67,12 +72,14 @@ 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.
+.PP
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.
+.SS subpad
.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.
@@ -84,18 +91,22 @@ 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.
+.bP
The \fIpminrow\fR and \fIpmincol\fR parameters specify the upper
left-hand corner of the rectangle to be displayed in the pad.
+.bP
The \fIsminrow\fR,
\fIsmincol\fR, \fIsmaxrow\fR, and \fIsmaxcol\fR
parameters specify the edges of the
rectangle to be displayed on the screen.
+.PP
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.
@@ -104,9 +115,11 @@ contained within their respective structures.
Negative values of
\fIpminrow\fR, \fIpmincol\fR, \fIsminrow\fR, or \fIsmincol\fR are treated as if
they were 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
+followed by a call to \fBrefresh\fR(3X),
+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
@@ -115,6 +128,7 @@ 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.
+.SS pecho_wchar
.PP
The \fBpecho_wchar\fR function is the analogous wide-character
form of \fBpechochar\fR.
@@ -130,7 +144,7 @@ to \fBENOMEM\fR.
.PP
X/Open does not define any error conditions.
In this implementation
-.RS
+.RS 3
.TP 5
\fBprefresh\fP and \fBpnoutrefresh\fP
return an error
@@ -152,6 +166,76 @@ to \fBwecho_wchar\fP returns an error.
.SH NOTES
Note that \fBpechochar\fR may be a macro.
.SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions.
+BSD curses has no \fIpad\fP feature.
+.PP
+SVr2 curses (1986) provided the \fBnewpad\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
+The XSI Curses standard, Issue 4 describes these functions,
+without significant change from the SVr3 documentation.
+It describes no error conditions.
+The behavior of \fBsubpad\fP if the parent window is not
+a pad is undocumented,
+and is not checked by the vendor Unix implementations:
+.bP
+SVr4 curses sets a flag in the \fBWINDOW\fP structure in \fBnewpad\fP
+which tells if the window is a \fIpad\fP.
+.IP
+However, it uses this information only in
+\fBwaddch\fP (to decide if it should call \fBwrefresh\fP) and
+\fBwscrl\fP (to avoid scrolling a pad),
+and does not check in \fBwrefresh\fP to ensure that the pad
+is refreshed properly.
+.bP
+Solaris X/Open Curses checks if a window is a pad in \fBwnoutrefresh\fP,
+returning \fBERR\fP in that case.
+.IP
+However, it only sets the flag for subwindows if the parent window is a pad.
+Its \fBnewpad\fP function does not set this information.
+Consequently, the check will never fail.
+.IP
+It makes no comparable check in \fBpnoutrefresh\fP,
+though interestingly enough, a comment in the source code
+states that the lack of a check was an MKS extension.
+.bP
+NetBSD 7 curses
+sets a flag in the \fBWINDOW\fP structure for \fBnewpad\fP and \fBsubpad\fP,
+using this to help with the distinction between \fBwnoutrefresh\fP
+and \fBpnoutrefresh\fP.
+.IP
+It does not check for the case where a subwindow is created in
+a pad using \fBsubwin\fP or \fBderwin\fP.
+.IP
+The \fBdupwin\fP function returns a regular window when duplicating a pad.
+Likewise, \fBgetwin\fP always returns a window, even if the saved
+data was from a pad.
+.PP
+This implementation
+.bP
+sets a flag in the \fBWINDOW\fP structure for \fBnewpad\fP and \fBsubpad\fP,
+.bP
+allows a \fBsubwin\fP or \fBderwin\fP call to succeed having a pad parent by
+forcing the subwindow to be a pad,
+.bP
+checks in both \fBwnoutrefresh\fP and \fBpnoutrefresh\fP to ensure
+that pads and windows are handled distinctly, and
+.bP
+ensures that \fBdupwin\fP and \fBgetwin\fP treat
+pads versus windows consistently.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_refresh\fR(3X), \fBcurs_touch\fR(3X), \fBcurs_addch\fR(3X).
+\fBcurses\fR(3X),
+\fBcurs_refresh\fR(3X),
+\fBcurs_touch\fR(3X),
+\fBcurs_addch\fR(3X).
diff --git a/man/curs_print.3x b/man/curs_print.3x
index 31a453565059..ba793ec3319a 100644
--- a/man/curs_print.3x
+++ b/man/curs_print.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 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,7 +26,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_print.3x,v 1.10 2010/12/04 18:40:45 tom Exp $
+.\" $Id: curs_print.3x,v 1.13 2018/07/28 21:34:56 tom Exp $
.TH curs_print 3X ""
.SH NAME
\fBmcprint\fR \- ship binary data to printer
@@ -39,16 +39,19 @@ This function uses the \fBmc5p\fR or \fBmc4\fR and \fBmc5\fR 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
+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:
+for some reason.
+In this case, errno will contain either an error associated
+with \fBwrite\fP(2) or one of the following:
.TP 5
ENODEV
Capabilities for printer redirection do not exist.
@@ -65,4 +68,4 @@ in SVr4 curses, 4.4BSD curses, or any other previous version of curses.
Padding in the \fBmc5p\fR, \fBmc4\fR and \fBmc5\fR capabilities will not be
interpreted.
.SH SEE ALSO
-\fBcurses\fR(3X)\fR
+\fBcurses\fR(3X)
diff --git a/man/curs_printw.3x b/man/curs_printw.3x
index 9918f9df9a71..bd5ad9a16059 100644
--- a/man/curs_printw.3x
+++ b/man/curs_printw.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,16 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_printw.3x,v 1.20 2010/12/04 18:40:45 tom Exp $
+.\" $Id: curs_printw.3x,v 1.24 2019/11/30 21:06:30 tom Exp $
.TH curs_printw 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.na
.hy 0
.SH NAME
@@ -49,13 +57,15 @@
.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
+.sp
+/* obsolete */
.br
+\fBint vwprintw(WINDOW *win, const char *fmt, va_list varglist);\fR
.SH DESCRIPTION
The \fBprintw\fR, \fBwprintw\fR, \fBmvprintw\fR and \fBmvwprintw\fR
-routines are analogous to \fBprintf\fR [see \fBprintf\fR(3)]. In
+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.
.PP
@@ -75,18 +85,33 @@ 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.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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 PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions. The function
+In this implementation, \fBvw_printw\fP and \fBvwprintw\fP are equivalent,
+to support legacy applications.
+However, the latter (\fBvwprintw\fP) is obsolete:
+.bP
+The XSI Curses standard, Issue 4 described 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.
+.bP
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>.
+This implementation uses \fB<stdarg.h>\fR for both,
+because that header is included in \fB<curses.h\fR>.
+.bP
+X/Open Curses, Issue 5 (December 2007) marked \fBvwprintw\fP (along with
+\fBvwscanw\fP and the termcap interface) as withdrawn.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBprintf\fR(3), \fBvprintf(3)\fR
+.na
+\fBcurses\fR(3X),
+\fBcurs_addstr\fR(3X),
+\fBcurs_scanw\fR(3X),
+\fBcurs_termcap\fP(3X),
+\fBprintf\fR(3),
+\fBvprintf\fR(3).
diff --git a/man/curs_refresh.3x b/man/curs_refresh.3x
index e1552c37cb48..038206f38561 100644
--- a/man/curs_refresh.3x
+++ b/man/curs_refresh.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2005,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,16 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_refresh.3x,v 1.15 2010/12/04 18:38:55 tom Exp $
+.\" $Id: curs_refresh.3x,v 1.20 2019/11/30 21:06:30 tom Exp $
.TH curs_refresh 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.na
.hy 0
.SH NAME
@@ -55,29 +63,39 @@
\fBint wredrawln(WINDOW *win, int beg_line, int num_lines);\fR
.br
.SH DESCRIPTION
+.SS refresh/wrefresh
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.
+\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 named window to the \fIphysical screen\fP,
+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
enabled, the physical cursor of the terminal is left at the location of the
cursor for that window.
+.SS wnoutrefresh/doupdate
.PP
The \fBwnoutrefresh\fR and \fBdoupdate\fR routines allow multiple updates with
more efficiency than \fBwrefresh\fR 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.
+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
+.bP
+first calling \fBwnoutrefresh\fR,
+which copies the named window to the \fIvirtual screen\fP, and
+.bP
+then calling \fBdoupdate\fR, which compares
+the \fIvirtual screen\fP to the \fIphysical screen\fP
+and does the actual update.
.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.
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.
@@ -85,11 +103,14 @@ 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
characters transmitted and less CPU time used.
+.PP
If the \fIwin\fR argument to
-\fBwrefresh\fR is the global variable \fBcurscr\fR, the screen is immediately
-cleared and repainted from scratch.
+\fBwrefresh\fR is the \fIphysical screen\fP
+(i.e., 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.
+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
are copied to the virtual screen.
This affects programs that use overlapping
@@ -98,11 +119,12 @@ 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
exploiting this behavior.)
+.SS wredrawln/redrawwin
.PP
The \fBwredrawln\fR routine indicates to \fBcurses\fR 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\fR 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
@@ -110,7 +132,7 @@ completion.
.PP
X/Open does not define any error conditions.
In this implementation
-.RS
+.RS 3
.TP 5
\fBwnoutrefresh\fP
returns an error
@@ -126,14 +148,14 @@ Note that \fBrefresh\fR and \fBredrawwin\fR may be macros.
.SH PORTABILITY
The XSI Curses standard, Issue 4 describes these functions.
.PP
-Whether \fBwnoutrefresh()\fR copies to the virtual screen the entire contents
+Whether \fBwnoutrefresh\fR 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\fR before the
+\fBwnoutrefresh\fR call to guarantee an entire-contents copy anywhere.
.SH SEE ALSO
\fBcurses\fR(3X),
\fBcurs_outopts\fR(3X)
diff --git a/man/curs_scanw.3x b/man/curs_scanw.3x
index a3208f5627c8..ccbe8af32bbb 100644
--- a/man/curs_scanw.3x
+++ b/man/curs_scanw.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,16 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_scanw.3x,v 1.17 2010/12/04 18:40:45 tom Exp $
+.\" $Id: curs_scanw.3x,v 1.25 2019/11/30 21:06:30 tom Exp $
.TH curs_scanw 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
\fBscanw\fR,
\fBwscanw\fR,
@@ -37,25 +45,29 @@
.SH SYNOPSIS
\fB#include <curses.h>\fR
.sp
-\fBint scanw(char *fmt, ...);\fR
+\fBint scanw(const char *fmt, ...);\fR
.br
-\fBint wscanw(WINDOW *win, char *fmt, ...);\fR
+\fBint wscanw(WINDOW *win, const char *fmt, ...);\fR
.br
-\fBint mvscanw(int y, int x, char *fmt, ...);\fR
+\fBint mvscanw(int y, int x, const char *fmt, ...);\fR
.br
-\fBint mvwscanw(WINDOW *win, int y, int x, char *fmt, ...);\fR
+\fBint mvwscanw(WINDOW *win, int y, int x, const char *fmt, ...);\fR
.br
-\fBint vw_scanw(WINDOW *win, char *fmt, va_list varglist);\fR
+\fBint vw_scanw(WINDOW *win, const char *fmt, va_list varglist);\fR
+.sp
+/* obsolete */
.br
-\fBint vwscanw(WINDOW *win, char *fmt, va_list varglist);\fR
+\fBint vwscanw(WINDOW *win, const char *fmt, va_list varglist);\fR
.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
+\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
+for \fBsscanf\fR(3).
+Fields which do not map to a variable in the \fIfmt\fR
field are lost.
.PP
-The \fBvwscanw\fR and \fBvw_scanw\fR routines are analogous to \fBvscanf\fR.
+The \fBvwscanw\fR and \fBvw_scanw\fR routines are analogous to \fBvscanf\fR(3).
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.
@@ -67,29 +79,52 @@ 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.
.PP
-Functions with a "mv" prefix first perform a cursor movement using
+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 PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions. The function
+In this implementation, \fBvw_scanw\fP and \fBvwscanw\fP are equivalent,
+to support legacy applications.
+However, the latter (\fBvwscanw\fP) is obsolete:
+.bP
+The XSI Curses standard, Issue 4 described these functions,
+noting that 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.
+.bP
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>.
+.bP
+X/Open Curses, Issue 5 (December 2007) marked \fBvwscanw\fP (along with
+\fBvwprintw\fP and the termcap interface) as withdrawn.
.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,
+functions return \fBERR\fP or \fBOK\fP.
+.bP
+Since the underlying \fBscanf\fR(3) 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.
+.bP
+This implementation returns the number of items scanned,
+for compatibility with SVr4 curses.
+As of 2018, NetBSD curses also returns the number of items scanned.
+Both ncurses and NetBSD curses call \fBvsscanf\fP to scan the string,
+which returns \fBEOF\fP on error.
+.bP
+Portable applications should only test if the return value is \fBERR\fP,
+since the \fBOK\fP value (zero) is likely to be misleading.
+.IP
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.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_getstr\fR(3X), \fBcurs_printw\fR(3X), \fBscanf\fR(3)
+.na
+\fBcurses\fR(3X),
+\fBcurs_getstr\fR(3X),
+\fBcurs_printw\fR(3X),
+\fBcurs_termcap\fP(3X),
+\fBscanf\fR(3).
diff --git a/man/curs_scr_dump.3x b/man/curs_scr_dump.3x
index df3e79c1ffee..960317541487 100644
--- a/man/curs_scr_dump.3x
+++ b/man/curs_scr_dump.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,16 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_scr_dump.3x,v 1.9 2010/12/04 18:40:45 tom Exp $
+.\" $Id: curs_scr_dump.3x,v 1.14 2019/11/30 21:06:30 tom Exp $
.TH curs_scr_dump 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.na
.hy 0
.SH NAME
@@ -49,24 +57,30 @@
\fBint scr_set(const char *filename);\fR
.br
.SH DESCRIPTION
-The \fBscr_dump\fR routine dumps the current contents of the virtual screen
+The \fBscr_dump\fR routine dumps the current contents
+of the \fIvirtual screen\fP
to the file \fIfilename\fR.
.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 \fBscr_restore\fR routine sets the \fIvirtual screen\fP to the contents
+of \fIfilename\fR, which must have been written using \fBscr_dump\fR.
+The next call to \fBdoupdate\fR restores
+the \fIphysical screen\fP to the way it looked in the dump file.
.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,
+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
+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.
+\fBendwin\fR(3X) call.
+The data is declared invalid
+.bP
+if the terminfo capabilities \fBrmcup\fR and \fBnrrmc\fR exist, also
+.bP
+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
@@ -90,7 +104,11 @@ qualifiers).
.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".
+\*(``old\*(''.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_refresh\fR(3X),
-\fBcurs_util\fR(3X), \fBsystem\fR(3)
+\fBcurses\fR(3X),
+\fBcurs_initscr\fR(3X),
+\fBcurs_refresh\fR(3X),
+\fBcurs_util\fR(3X),
+\fBscr_dump\fR(5),
+\fBsystem\fR(3)
diff --git a/man/curs_scroll.3x b/man/curs_scroll.3x
index 2cb152d865c7..55cfa3fd8eaa 100644
--- a/man/curs_scroll.3x
+++ b/man/curs_scroll.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_scroll.3x,v 1.15 2010/12/04 18:40:45 tom Exp $
+.\" $Id: curs_scroll.3x,v 1.17 2019/11/30 21:06:30 tom Exp $
.TH curs_scroll 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.na
.hy 0
.SH NAME
@@ -50,8 +54,8 @@ 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.
+region of the window is the entire screen,
+the \fIphysical screen\fP may be scrolled at the same time.
.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
@@ -74,8 +78,8 @@ if scrolling is not enabled in the window, e.g., with \fBscrollok\fP.
Note that \fBscrl\fR and \fBscroll\fR may be macros.
.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.
+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.
diff --git a/man/curs_slk.3x b/man/curs_slk.3x
index e8f7afbdbfd9..6d7a2aa37126 100644
--- a/man/curs_slk.3x
+++ b/man/curs_slk.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2020 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,8 +26,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_slk.3x,v 1.22 2010/12/04 18:38:55 tom Exp $
+.\" $Id: curs_slk.3x,v 1.35 2020/01/18 22:49:38 tom Exp $
.TH curs_slk 3X ""
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.na
.hy 0
.SH NAME
@@ -47,46 +51,50 @@
\fBslk_attr_set\fR,
\fBslk_attr_off\fR,
\fBslk_attr\fR,
-\fBslk_color\fR \- \fBcurses\fR soft label routines
+\fBslk_color\fR,
+\fBextended_slk_color\fR \- \fBcurses\fR soft label routines
.ad
.hy
.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
+\fBint slk_init(int \fP\fIfmt\fP\fB);\fR
+.sp
+\fBint slk_set(int \fP\fIlabnum\fP\fB, const char *\fP\fIlabel\fP\fB, int \fP\fIfmt\fP\fB);\fR
.br
+\fBint slk_wset(int \fP\fIlabnum\fP\fB, const wchar_t *\fP\fIlabel\fP\fB, int \fP\fIfmt\fP\fB);\fR
+.sp
+\fBchar *slk_label(int \fP\fIlabnum\fP\fB);\fR
+.sp
\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
+.sp
+\fBint slk_attron(const chtype \fP\fIattrs\fP\fB);\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
+\fBint slk_attroff(const chtype \fP\fIattrs\fP\fB);\fR
.br
-\fBint slk_attr_on(attr_t attrs, void* opts);\fR
+\fBint slk_attrset(const chtype \fP\fIattrs\fP\fB);\fR
.br
-\fBint slk_attr_off(const attr_t attrs, void * opts);\fR
+\fBint slk_attr_on(attr_t \fP\fIattrs\fP\fB, void* \fP\fIopts\fP\fB);\fR
.br
-\fBint slk_attr_set(const attr_t attrs, short color_pair, void* opts);\fR
+\fBint slk_attr_off(const attr_t \fP\fIattrs\fP\fB, void * \fP\fIopts\fP\fB);\fR
.br
+\fBint slk_attr_set(const attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void* \fP\fIopts\fP\fB);\fR
+.sp
\fBattr_t slk_attr(void);\fR
+.sp
+\fBint slk_color(short \fP\fIpair\fP\fB);\fR
.br
-\fBint slk_color(short color_pair);\fR
-.br
-\fBint slk_wset(int labnum, const wchar_t *label, int fmt);\fR
+/* extension */
.br
+\fBint extended_slk_color(int \fP\fIpair\fP\fB);\fR
.SH DESCRIPTION
The slk* functions manipulate the set of soft function-key labels that exist on
many terminals.
@@ -98,18 +106,19 @@ 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.
+This is useful for PC-like enduser devices.
ncurses 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.
+.SS Initialization
.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
emulate the soft labels,
then \fIfmt\fR determines how the labels are arranged on the screen:
-.RS
+.RS 3
.TP 3
.B 0
indicates a 3\-2\-3 arrangement of
@@ -126,11 +135,12 @@ 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
+.SS Labels
.PP
The \fBslk_set\fR routine
(and the \fBslk_wset\fR routine for the wide-character library)
has three parameters:
-.RS
+.RS 3
.TP 5
.I labnum
is the label number, from \fB1\fR to \fB8\fR
@@ -150,11 +160,12 @@ left-justified, centered, or right-justified, respectively, within the
label.
.RE
.PP
-The \fBslk_refresh\fR and \fBslk_noutrefresh\fR routines correspond to
-the \fBwrefresh\fR and \fBwnoutrefresh\fR routines.
-.PP
The \fBslk_label\fR routine returns the current label for label number
\fIlabnum\fR, with leading and trailing blanks stripped.
+.SS Screen updates
+.PP
+The \fBslk_refresh\fR and \fBslk_noutrefresh\fR routines correspond to
+the \fBwrefresh\fR and \fBwnoutrefresh\fR routines.
.PP
The \fBslk_clear\fR routine clears the soft labels from the screen.
.PP
@@ -163,25 +174,34 @@ 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.
+.SS Video attributes
.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.
+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, respectively.
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).
+.SS Colors
.PP
The \fBslk_color\fR routine corresponds to \fBcolor_set\fR.
It has an effect only
if soft labels are simulated on the bottom line of the screen.
+.PP
+Because \fBslk_color\fR accepts only \fBshort\fP (signed 16-bit integer) values,
+this implementation provides
+\fBextended_slk_color\fR which accepts an integer value, e.g., 32-bits.
.
.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.
+These routines return \fBERR\fR upon failure
+and \fBOK\fP (SVr4 specifies only "an integer value other than \fBERR\fR")
+upon successful completion.
.PP
X/Open defines no error conditions.
In this implementation
-.RS
+.RS 3
.TP 5
\fBslk_attr\fR
returns the attribute used for the soft keys.
@@ -201,8 +221,7 @@ if the terminal or the softkeys were not initialized.
\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..COLOR_PAIRS\-1.
.TP 5
\fBslk_color\fP
returns an error
@@ -223,17 +242,73 @@ the \fIlabnum\fP parameter is outside the range of label counts, or
if the format parameter is outside the range 0..2, or if
memory for the labels cannot be allocated.
.RE
+.SH HISTORY
+SVr3 introduced these functions:
+ slk_clear
+ slk_init
+ slk_label
+ slk_noutrefresh
+ slk_refresh
+ slk_restore
+ slk_set
+ slk_touch
+.PP
+SVr4 added these functions:
+ slk_attroff
+ slk_attron
+ slk_attrset
+ slk_start
+.PP
+X/Open Curses added these:
+ slk_attr_off
+ slk_attr_on
+ slk_attr_set
+ slk_color
+ slk_wset
+.SH EXTENSIONS
+.PP
+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., \fBslk_attr_set\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.
.SH NOTES
Most applications would use \fBslk_noutrefresh\fR because a
\fBwrefresh\fR is likely to follow soon.
.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
+The XSI Curses standard, Issue 4, described the soft-key functions,
+with some differences from SVr4 curses:
+.bP
+It added functions like the SVr4
+attribute-manipulation functions \fBslk_attron\fR,
+\fBslk_attroff\fR, \fBslk_attrset\fR,
+but which use \fBattr_t\fR parameters (rather than \fBchtype\fP),
+along with a reserved \fIopts\fP parameter.
+.IP
+Two of these new functions (unlike the SVr4 functions) have no provision
+for color: \fBslk_attr_on\fP and \fBslk_attr_off\fP.
+.IP
+The third function (\fBslk_attr_set\fP) has a color-pair parameter.
+.bP
+It added \fBconst\fR qualifiers to parameters (unnecessarily), and
+.bP
+It added \fBslk_color\fP.
+.PP
+The format codes \fB2\fR and \fB3\fR for \fBslk_init\fR and the
function \fBslk_attr\fR are specific to ncurses.
+.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.
.SH SEE ALSO
\fBcurses\fR(3X),
\fBcurs_attr\fR(3X),
diff --git a/man/curs_sp_funcs.3x b/man/curs_sp_funcs.3x
index c7c55ddb62fe..b369f8001127 100644
--- a/man/curs_sp_funcs.3x
+++ b/man/curs_sp_funcs.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2010,2013 Free Software Foundation, Inc. *
+.\" Copyright (c) 2010-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,18 +26,25 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_sp_funcs.3x,v 1.6 2013/06/22 17:53:59 tom Exp $
+.\" $Id: curs_sp_funcs.3x,v 1.17 2019/11/30 21:01:26 tom Exp $
.TH curs_sp_funcs 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.na
.hy 0
.SH NAME
-new_prescr \- \fBcurses\fR screen-pointer extension
+curs_sp_funcs \- \fBcurses\fR screen-pointer extension
.ad
.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
+\fB#include <term.h>\fR
.nf
.sp
+\fBint alloc_pair_sp(SCREEN*, int, int);\fR
+.br
\fBint assume_default_colors_sp(SCREEN*, int, int);\fR
.br
\fBint baudrate_sp(SCREEN*);\fR
@@ -66,9 +73,19 @@ new_prescr \- \fBcurses\fR screen-pointer extension
.br
\fBint endwin_sp(SCREEN*);\fR
.br
-\fBint erasechar_sp(SCREEN*);\fR
+\fBchar erasechar_sp(SCREEN*);\fR
+.br
+\fBint extended_color_content_sp(SCREEN *, int, int *, int *, int *);\fR
+.br
+\fBint extended_pair_content_sp(SCREEN*, int, int *, int *);\fR
+.br
+\fBint extended_slk_color_sp(SCREEN*, int);\fR
+.br
+\fBvoid filter_sp(SCREEN*);\fR
.br
-\fBint filter_sp(SCREEN*);\fR
+\fBint find_pair_sp(SCREEN*, int, int);\fR
+.br
+\fBint free_pair_sp(SCREEN*, int);\fR
.br
\fBint flash_sp(SCREEN*);\fR
.br
@@ -80,7 +97,7 @@ new_prescr \- \fBcurses\fR screen-pointer extension
.br
\fBWINDOW* getwin_sp(SCREEN*, FILE*);\fR
.br
-\fBint halfdelay_sp(SCREEN*);\fR
+\fBint halfdelay_sp(SCREEN*, int);\fR
.br
\fBbool has_colors_sp(SCREEN*);\fR
.br
@@ -94,6 +111,10 @@ new_prescr \- \fBcurses\fR screen-pointer extension
.br
\fBint init_color_sp(SCREEN*, short, short, short, short);\fR
.br
+\fBint init_extended_color_sp(SCREEN*, int, int, int, int);\fR
+.br
+\fBint init_extended_pair_sp(SCREEN*, int, int, int);\fR
+.br
\fBint init_pair_sp(SCREEN*, short, short, short);\fR
.br
\fBint intrflush_sp(SCREEN*, WINDOW*, bool);\fR
@@ -112,6 +133,8 @@ new_prescr \- \fBcurses\fR screen-pointer extension
.br
\fBchar killchar_sp(SCREEN*);\fR
.br
+\fBchar* longname_sp(SCREEN*);\fR
+.br
\fBint mcprint_sp(SCREEN*, char *, int);\fR
.br
\fBint mouseinterval_sp(SCREEN*, int);\fR
@@ -126,7 +149,7 @@ new_prescr \- \fBcurses\fR screen-pointer extension
.br
\fBSCREEN* new_prescr(void);\fR
.br
-\fBSCREEN* newterm_sp(SCREEN*, NCURSES_CONST char *, FILE *, FILE *);\fR
+\fBSCREEN* newterm_sp(SCREEN*, const char *, FILE *, FILE *);\fR
.br
\fBWINDOW* newwin_sp(SCREEN*, int, int, int, int);\fR
.br
@@ -136,7 +159,7 @@ new_prescr \- \fBcurses\fR screen-pointer extension
.br
\fBint noecho_sp(SCREEN*);\fR
.br
-\fBint nofilter_sp(SCREEN*);\fR
+\fBvoid nofilter_sp(SCREEN*);\fR
.br
\fBint nonl_sp(SCREEN*);\fR
.br
@@ -186,7 +209,7 @@ new_prescr \- \fBcurses\fR screen-pointer extension
.br
\fBint slk_attrset_sp(SCREEN*, const chtype);\fR
.br
-\fBint slk_attr_sp(SCREEN*);\fR
+\fBattr_t slk_attr_sp(SCREEN*);\fR
.br
\fBint slk_clear_sp(SCREEN*);\fR
.br
@@ -194,7 +217,7 @@ new_prescr \- \fBcurses\fR screen-pointer extension
.br
\fBint slk_init_sp(SCREEN*, int);\fR
.br
-\fBint slk_label_sp(SCREEN*, int);\fR
+\fBchar* slk_label_sp(SCREEN*, int);\fR
.br
\fBint slk_noutrefresh_sp(SCREEN*);\fR
.br
@@ -228,6 +251,8 @@ new_prescr \- \fBcurses\fR screen-pointer extension
.br
\fBvoid use_env_sp(SCREEN*, bool);\fR
.br
+\fBvoid use_tioctl_sp(SCREEN *, bool);\fR
+.br
\fBint use_legacy_coding_sp(SCREEN*, int);\fR
.br
\fBint vid_attr_sp(SCREEN*, attr_t, short, void *);\fR
@@ -242,19 +267,19 @@ new_prescr \- \fBcurses\fR screen-pointer extension
.sp
\fB#include <form.h>\fR
.sp
-\fBint new_form_sp(SCREEN*, FIELD **);\fR
+\fBFORM* new_form_sp(SCREEN*, FIELD **);\fR
.sp
\fB#include <menu.h>\fR
.sp
-\fBint new_menu_sp(SCREEN*, ITEM **);\fR
+\fBMENU* new_menu_sp(SCREEN*, ITEM **);\fR
.sp
\fB#include <panel.h>\fR
.sp
-\fBint ceiling_panel(SCREEN*);\fR
+\fBPANEL* ceiling_panel(SCREEN*);\fR
.br
\fBPANEL* ground_panel(SCREEN*);\fR
.br
-\fBint update_panels_sp(SCREEN*);\fR
+\fBvoid update_panels_sp(SCREEN*);\fR
.sp
\fB#include <term.h>\fR
.sp
@@ -262,19 +287,19 @@ new_prescr \- \fBcurses\fR screen-pointer extension
.br
\fBint putp_sp(SCREEN*, const char *);\fR
.br
-\fBint tgetflag_sp(SCREEN*, char *, const char *);\fR
+\fBint tgetflag_sp(SCREEN*, const char *);\fR
.br
\fBint tgetent_sp(SCREEN*, char *, const char *);\fR
.br
-\fBint tgetnum_sp(SCREEN*, NCURSES_CONST char *);\fR
+\fBint tgetnum_sp(SCREEN*, const char *);\fR
.br
-\fBchar* tgetstr_sp(SCREEN*, NCURSES_CONST char *, char **);\fR
+\fBchar* tgetstr_sp(SCREEN*, const char *, char **);\fR
.br
-\fBint tigetflag_sp(SCREEN*, NCURSES_CONST char *);\fR
+\fBint tigetflag_sp(SCREEN*, const char *);\fR
.br
-\fBint tigetnum_sp(SCREEN*, NCURSES_CONST char *);\fR
+\fBint tigetnum_sp(SCREEN*, const char *);\fR
.br
-\fBchar* tigetstr_sp(SCREEN*, NCURSES_CONST char *);\fR
+\fBchar* tigetstr_sp(SCREEN*, const char *);\fR
.br
\fBint tputs_sp(SCREEN*, const char *, int, NCURSES_SP_OUTC);\fR
.ad
@@ -328,7 +353,7 @@ to make it useful for checking if the extension is provided.
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
diff --git a/man/curs_termattrs.3x b/man/curs_termattrs.3x
index 0f0294cd5696..94659a2772f9 100644
--- a/man/curs_termattrs.3x
+++ b/man/curs_termattrs.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2015,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,7 +26,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_termattrs.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
+.\" $Id: curs_termattrs.3x,v 1.14 2018/07/28 21:34:06 tom Exp $
.TH curs_termattrs 3X ""
.SH NAME
\fBbaudrate\fR,
@@ -66,9 +66,12 @@
\fBchar *termname(void);\fR
.br
.SH DESCRIPTION
-The \fBbaudrate\fR routine returns the output speed of the terminal. The
+.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
integer.
+.SS erasechar, erasewchar
.PP
The \fBerasechar\fR routine returns the user's current erase character.
.PP
@@ -76,14 +79,17 @@ The \fBerasewchar\fR routine stores the current erase character
in the location referenced by \fIch\fR.
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-
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
+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
.PP
The \fBkillchar\fR routine returns the user's current line kill character.
.PP
@@ -91,15 +97,19 @@ The \fBkillwchar\fR routine stores the current line-kill character
in the location referenced by \fIch\fR.
If no line-kill character has been defined,
the routine fails and the location referenced by \fIch\fR 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
+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
terminals.
+.SS termattrs, term_attrs
.PP
If a given terminal does not support a video attribute that an
application program is trying to use, \fBcurses\fR may substitute a
@@ -109,6 +119,7 @@ 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
needs complete control over the appearance of the screen.
+.SS termname
.PP
The \fBtermname\fR routine returns the terminal name used by \fBsetupterm\fR.
.SH RETURN VALUE
@@ -120,7 +131,8 @@ completion.
.SH NOTES
Note that \fBtermattrs\fR may be a macro.
.SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions. It changes the
+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
14 characters.
diff --git a/man/curs_termcap.3x b/man/curs_termcap.3x
index f8977bebca9c..f56e3569004e 100644
--- a/man/curs_termcap.3x
+++ b/man/curs_termcap.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2012,2013 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,10 +26,15 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_termcap.3x,v 1.30 2013/01/19 15:58:48 tom Exp $
+.\" $Id: curs_termcap.3x,v 1.42 2019/11/30 21:01:40 tom Exp $
.TH curs_termcap 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.na
.hy 0
@@ -62,11 +67,11 @@
.sp
\fBint tgetent(char *bp, const char *name);\fR
.br
-\fBint tgetflag(char *id);\fR
+\fBint tgetflag(const char *id);\fR
.br
-\fBint tgetnum(char *id);\fR
+\fBint tgetnum(const char *id);\fR
.br
-\fBchar *tgetstr(char *id, char **area);\fR
+\fBchar *tgetstr(const char *id, char **area);\fR
.br
\fBchar *tgoto(const char *cap, int col, int row);\fR
.br
@@ -74,8 +79,10 @@
.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
+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
@@ -121,9 +128,24 @@ or \-1 if it is not available.
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 return value will also be copied to the buffer pointed to by \fIarea\fR,
+The \fIarea\fP 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.
+.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.
+.bP
+The return value itself is an address in the terminal description which
+is loaded into memory.
+.RE
.PP
Only the first two characters of the \fBid\fR parameter of
\fBtgetflag\fR,
@@ -131,11 +153,33 @@ Only the first two characters of the \fBid\fR parameter of
\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.
+The \fBtgoto\fR routine expands the given capability using the parameters.
+.bP
+Because the capability may have padding characters,
+the output of \fBtgoto\fP should be passed to \fBtputs\fR
+rather than some other output function such as \fBprintf\fP.
+.bP
+While \fBtgoto\fP is assumed to be used for the two-parameter
+cursor positioning capability,
+termcap applications also use it for single-parameter capabilities.
+.IP
+Doing this shows a quirk in \fBtgoto\fP: most hardware
+terminals use cursor addressing with \fIrow\fP first,
+but the original developers of the termcap interface chose to
+put the \fIcolumn\fP parameter first.
+The \fBtgoto\fP function swaps the order of parameters.
+It does this also for calls requiring only a single parameter.
+In that case, the first parameter is merely a placeholder.
+.bP
+Normally the ncurses library is compiled with terminfo support.
+In that case, \fBtgoto\fP uses \fBtparm\fP(3X) (a more capable formatter).
+.IP
+However, \fBtparm\fP is not a \fItermcap\fP feature,
+and portable \fItermcap\fP applications should not rely upon its availability.
.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.
+page.
+It can retrieve capabilities by either termcap or terminfo name.
.SS GLOBAL VARIABLES
.PP
The variables
@@ -163,7 +207,8 @@ 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
+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
@@ -172,8 +217,9 @@ if the string is indeed terminfo-style by looking for "%p" parameters or
appear to be terminfo).
.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.
+differ from termcap's, \fBtputs("50");\fR will put out a literal \*(``50\*('' rather
+than busy-waiting for 50 milliseconds.
+Cope with it.
.PP
Note that termcap has nothing analogous to terminfo's \fBsgr\fR string.
One consequence of this is that termcap applications assume \fRme\fR
@@ -181,8 +227,15 @@ One consequence of this is that termcap applications assume \fRme\fR
This implementation checks for, and modifies the data shown to the
termcap interface to accommodate termcap's limitation in this respect.
.SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions. However, they
+These functions are provided for supporting legacy applications,
+and should not be used in new programs:
+.bP
+The XSI Curses standard, Issue 4 describes these functions.
+However, they
are marked TO BE WITHDRAWN and may be removed in future versions.
+.bP
+X/Open Curses, Issue 5 (December 2007) marked the termcap interface
+(along with \fBvwprintw\fP and \fBvwscanw\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
@@ -222,4 +275,4 @@ extended capability names which are longer than two characters.
\fBterm_variables\fR(3X),
\fBputc\fR(3).
.sp
-http://invisible-island.net/ncurses/tctest.html
+https://invisible-island.net/ncurses/tctest.html
diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x
index 7d440bf53ebc..c6eac6e30536 100644
--- a/man/curs_terminfo.3x
+++ b/man/curs_terminfo.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1999-2011,2013 Free Software Foundation, Inc. *
+.\" Copyright (c) 1999-2018,2020 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,14 +26,15 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_terminfo.3x,v 1.43 2013/07/20 19:29:59 tom Exp $
+.\" $Id: curs_terminfo.3x,v 1.63 2020/01/18 23:55:46 tom Exp $
.TH curs_terminfo 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.ie \n(.g .ds '' \(rq
.el .ds '' ''
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.ds n 5
.na
@@ -63,23 +64,35 @@
\fB#include <curses.h>\fR
.br
\fB#include <term.h>\fR
-.PP
-\fBint setupterm(char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
+.sp
+\fBTERMINAL *cur_term;\fR
+.sp
+\fBconst char * const boolnames[];\fP
+\fBconst char * const boolcodes[];\fP
+\fBconst char * const boolfnames[];\fP
+\fBconst char * const numnames[];\fP
+\fBconst char * const numcodes[];\fP
+\fBconst char * const numfnames[];\fP
+\fBconst char * const strnames[];\fP
+\fBconst char * const strcodes[];\fP
+\fBconst char * const strfnames[];\fP
+.sp
+\fBint setupterm(const char *\fR\fIterm\fR\fB, int \fR\fIfiledes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
.br
-\fBint setterm(char *\fR\fIterm\fR\fB);\fR
+\fBint setterm(const 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
+\fBint restartterm(const char *\fR\fIterm\fR\fB, int \fR\fIfiledes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
+.sp
+\fBchar *tparm(const 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
+.sp
\fBint vidputs(chtype \fR\fIattrs\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
.br
\fBint vidattr(chtype \fR\fIattrs\fR\fB);\fR
@@ -87,32 +100,34 @@
\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
+.sp
\fBint mvcur(int \fR\fIoldrow\fR\fB, int \fR\fIoldcol\fR\fB, int \fR\fInewrow\fR, int \fR\fInewcol\fR\fB);\fR
+.sp
+\fBint tigetflag(const char *\fR\fIcapname\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
+\fBint tigetnum(const char *\fR\fIcapname\fR\fB);\fR
.br
+\fBchar *tigetstr(const char *\fR\fIcapname\fR\fB);\fR
+.sp
\fBchar *tiparm(const char *\fR\fIstr\fR\fB, ...);\fR
.br
.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
+capabilities, such as programming function keys.
+For all other
functionality, \fBcurses\fR routines are more suitable and their use is
recommended.
.SS Initialization
.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
+Initially, \fBsetupterm\fR should be called.
+The high-level curses functions \fBinitscr\fR and
+\fBnewterm\fR call \fBsetupterm\fP to initialize the
+low-level set of terminal-dependent variables
[listed in \fBterminfo\fR(\*n)].
.PP
-Each initialization routine provides applications with the
+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
@@ -126,14 +141,18 @@ If \fBuse_env(FALSE)\fR has been called, values for
\fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR 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, 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
+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.
.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
+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)].
@@ -156,23 +175,35 @@ call \fBreset_prog_mode\fR 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.
+output virtualization structures used by \fBcurses\fR.
+These are its parameters:
+.RS 3
+.TP 5
+\fIterm\fP
+is the terminal type, a character string.
+If \fIterm\fR is null, the environment variable \fBTERM\fR is used.
+.TP 5
+\fIfiledes\fP
+is the file descriptor used for all output.
+.TP 5
+\fIerrret\fP
+points to an optional location where an error status can be returned to
+the caller.
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
is normal.
+.IP
If \fBERR\fR is returned, examine \fIerrret\fR:
+.RS
.TP 5
.B 1
means that the terminal is hardcopy, cannot be used for curses applications.
.IP
\fBsetupterm\fP determines if the entry is a hardcopy type by
-checking the \fIhc\fP (\fIhardcopy\fP) capability.
+checking the \fBhc\fP (\fBhardcopy\fP) capability.
.TP 5
.B 0
means that the terminal could not be found,
@@ -180,18 +211,21 @@ or that it is a generic type,
having too little information for curses applications to run.
.IP
\fBsetupterm\fP determines if the entry is a generic type by
-checking the \fIgn\fP (\fIgeneric\fP) capability.
+checking the \fBgn\fP (\fBgeneric\fP) capability.
.TP 5
.B \-1
means that the \fBterminfo\fR database could not be found.
-.PP
+.RE
+.IP
If \fIerrret\fR is
null, \fBsetupterm\fR prints an error message upon finding an error
-and exits. Thus, the simplest call is:
+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.
+.RE
.PP
The \fBsetterm\fR routine was replaced by \fBsetupterm\fR. The call:
.sp
@@ -222,7 +256,8 @@ string variables use the values from \fInterm\fR.
It returns the old value of \fBcur_term\fR.
.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
+\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.
@@ -241,6 +276,13 @@ calls \fBsetupterm\fP, and then restores the bits.
The \fBtparm\fR routine instantiates the string \fIstr\fR with
parameters \fIpi\fR. A pointer is returned to the result of \fIstr\fR
with the parameters applied.
+Application developers should keep in mind these quirks of the interface:
+.bP
+Although \fBtparm\fP's actual parameters may be integers or strings,
+the prototype expects \fBlong\fP (integer) values.
+.bP
+Aside from the \fBset_attributes\fP (\fBsgr\fP) capability,
+most terminal capabilities require no more than one or two parameters.
.PP
\fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI<stdarg.h>\fP
rather than a fixed-parameter list.
@@ -249,36 +291,55 @@ Its numeric parameters are integers (int) rather than longs.
.SS Output Functions
.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
+\fIstr\fR and outputs it:
+.bP
+The \fIstr\fR parameter must be a terminfo string
+variable or the return value from
+\fBtparm\fR, \fBtiparm\fP, \fBtgetstr\fR, or \fBtgoto\fR.
+.IP
+The \fBtgetstr\fP and \fBtgoto\fP functions are part of the \fItermcap\fP
+interface,
+which happens to share this function name with the \fIterminfo\fP interface.
+.bP
+\fIaffcnt\fR is the number of lines affected, or 1 if
+not applicable.
+.bP
+\fIputc\fR is a \fBputchar\fR-like routine to which
the characters are passed, one at a time.
.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.
+The output of \fBputp\fR always goes to \fBstdout\fR, rather than
+the \fIfiledes\fR specified in \fBsetupterm\fR.
.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
+attributes listed in \fBcurses\fR(3X).
+The characters are passed to
the \fBputchar\fR-like routine \fIputc\fR.
.PP
The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except
that it outputs through \fBputchar\fR.
.PP
-The \fBvid_attr\fR and \fBvid_puts\fR routines correspond to vidattr and vidputs,
-respectively.
+The \fBvid_attr\fR and \fBvid_puts\fR routines correspond
+to vidattr and 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.
+.bP
+\fIattrs\fP of type \fBattr_t\fP for the attributes and
+.bP
+\fIpair\fP of type \fBshort\fP for the color-pair number.
+.PP
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.
.PP
-The \fBmvcur\fR routine provides low-level cursor motion. It takes
+X/Open Curses reserves the \fIopts\fP argument for future use,
+saying that applications must provide a null pointer for that argument.
+As an extension,
+this implementation allows \fIopts\fP to be used as a pointer to \fBint\fP,
+which overrides the \fIpair\fP (\fBshort\fP) argument.
+.PP
+The \fBmvcur\fR routine provides low-level cursor motion.
+It takes
effect immediately (rather than at the next refresh).
.\" ***************************************************************************
.SS Terminal Capability Functions
@@ -318,27 +379,35 @@ or
if it is canceled or absent from the terminal description.
.\" ***************************************************************************
.SS Terminal Capability Names
+.PP
These null-terminated arrays contain
-the short terminfo names ("codes"),
-the \fBtermcap\fR names, and the long terminfo names ("fnames")
+.bP
+the short terminfo names (\*(``codes\*(''),
+.bP
+the \fBtermcap\fR names (\*(``names\*('', and
+.bP
+the long terminfo names (\*(``fnames\*('')
+.PP
for each of the predefined \fBterminfo\fR variables:
-.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
+.RS
+\fBconst char *boolnames[]\fR, \fB*boolcodes[]\fR, \fB*boolfnames[]\fR
+.br
+\fBconst char *numnames[]\fR, \fB*numcodes[]\fR, \fB*numfnames[]\fR
+.br
+\fBconst char *strnames[]\fR, \fB*strcodes[]\fR, \fB*strfnames[]\fR
.RE
.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.
+(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
+.RS 3
.TP 5
\fBdel_curterm\fP
returns an error
@@ -363,40 +432,180 @@ It does not detect I/O errors:
X/Open states that \fBtputs\fP ignores the return value
of the output function \fIputc\fP.
.RE
+.SH HISTORY
+.PP
+SVr2 introduced the terminfo feature.
+Its programming manual mentioned these low-level functions:
+.TS
+l l
+_ _
+l l.
+\fBFunction\fR \fBDescription\fR
+fixterm restore tty to \*(``in curses\*('' state
+gettmode establish current tty modes
+mvcur low level cursor motion
+putp T{
+utility function that uses \fBtputs\fP to send characters via \fBputchar\fP.
+T}
+resetterm set tty modes to \*(``out of curses\*('' state
+resetty reset tty flags to stored value
+saveterm save current modes as \*(``in curses\*('' state
+savetty store current tty flags
+setterm establish terminal with given type
+setupterm establish terminal with given type
+tparm instantiate a string expression with parameters
+tputs apply padding information to a string
+vidattr like \fBvidputs\fP, but outputs through \fBputchar\fP
+vidputs T{
+output a string to put terminal in a specified video attribute mode
+T}
+.TE
+.PP
+The programming manual also mentioned
+functions provided for termcap compatibility
+(commenting that they \*(``may go away at a later date\*(''):
+.TS
+l l
+_ _
+l l.
+\fBFunction\fR \fBDescription\fR
+tgetent look up termcap 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{
+apply padding to capability, calling a function to put characters
+T}
+.TE
+.PP
+Early terminfo programs obtained capability values from the
+\fBTERMINAL\fP structure initialized by \fBsetupterm\fR.
+.PP
+SVr3 extended terminfo by adding functions to retrieve capability values
+(like the termcap interface),
+and reusing tgoto and tputs:
+.TS
+l l
+_ _
+l l.
+\fBFunction\fR \fBDescription\fR
+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 terminfo functions
+which had no counterpart in the termcap interface,
+documenting them as obsolete:
+.TS
+l l
+_ _
+l l.
+\fBFunction\fR \fBReplaced by\fP
+crmode cbreak
+fixterm reset_prog_mode
+gettmode N/A
+nocrmode nocbreak
+resetterm reset_shell_mode
+saveterm def_prog_mode
+setterm setupterm
+.TE
+.PP
+SVr3 kept the \fBmvcur\fP, \fBvidattr\fP and \fBvidputs\fP functions,
+along with \fBputp\fP, \fBtparm\fP and \fBtputs\fP.
+The latter were needed to support padding,
+and handling functions such as \fBvidattr\fP
+(which used more than the two parameters supported by \fBtgoto\fP).
+.PP
+SVr3 introduced the functions for switching between terminal
+descriptions, e.g., \fBset_curterm\fP.
+The various global variables such as \fBboolnames\fP were mentioned
+in the programming manual at this point.
+.PP
+SVr4 added the \fBvid_attr\fP and \fBvid_puts\fP functions.
+.PP
+There are other low-level functions declared in the curses header files
+on Unix systems,
+but none were documented.
+The functions marked \*(``obsolete\*('' remained in use
+by the Unix \fBvi\fP editor.
.SH PORTABILITY
+.SS Legacy functions
+.PP
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.
All other functions are as described by X/Open.
+.SS Legacy data
.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.
+Other implementions may not declare the capability name arrays.
+Some provide them without declaring them.
+X/Open does not specify them.
+.PP
+Extended terminal capability names, e.g., as defined by \fB@TIC@\ \-x\fP,
+are not stored in the arrays described here.
+.SS Output buffering
.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),
+mode on exit (like System V 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.
+.PP
+The current version (ncurses6)
+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.
+.SS Function prototypes
+.PP
+The X/Open Curses prototypes are based on the SVr4 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 \fBconst\fP less effectively than a later design might,
+in some cases applying it needlessly to values are already constant,
+and in most cases overlooking parameters which normally would use \fBconst\fP.
+Using constant parameters for functions which do not use \fBconst\fP
+may prevent the program from compiling.
+On the other hand, \fIwritable strings\fP are an obsolescent feature.
+.IP
+As an extension, this implementation can be configured to change the
+function prototypes to use the \fBconst\fP keyword.
+The ncurses ABI 6 enables this feature by default.
+.bP
+X/Open Curses prototypes \fBtparm\fR 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 9 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 \fBtiparm\fP function in mid-2009.
+.SS Special TERM treatment
+.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.
+.SS Other portability issues
.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
@@ -406,19 +615,9 @@ 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.
+other than \fBOK\fP/\fBERR\fP 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.
@@ -430,13 +629,6 @@ So though it is documented as a terminfo function,
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.
-.PP
-Other implementions may not declare the capability name arrays.
-Some provide them without declaring them.
-X/Open does not specify them.
-.PP
-Extended terminal capability names, e.g., as defined by \fB@TIC@\ \-x\fP,
-are not stored in the arrays described here.
.SH SEE ALSO
\fBcurses\fR(3X),
\fBcurs_initscr\fR(3X),
diff --git a/man/curs_threads.3x b/man/curs_threads.3x
index 5732e924c1b5..c2847f96cdf4 100644
--- a/man/curs_threads.3x
+++ b/man/curs_threads.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2008-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 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,16 +26,16 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_threads.3x,v 1.19 2012/05/26 17:03:26 tom Exp $
+.\" $Id: curs_threads.3x,v 1.24 2017/11/18 23:56:00 tom Exp $
.TH curs_threads 3X ""
.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
+\fBcurs_threads\fR \- \fBcurses\fR thread support
.ad
.hy
.SH SYNOPSIS
@@ -67,7 +67,7 @@ configuration which hide the mutex's needed to prevent concurrent
use of the global variables when configured for threading.
.PP
In addition to forcing access to members of the \fBWINDOW\fP structure
-to be via functions (see \fBcurs_opaque\fP(3x)),
+to be via functions (see \fBcurs_opaque\fP(3X)),
it makes functions of the common global variables,
e.g.,
COLORS,
@@ -540,6 +540,7 @@ 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
@@ -587,7 +588,7 @@ wvline_set/window
.TE
.\" ***************************************************************************
.SH RETURN VALUE
-These functions all return TRUE or FALSE, except as noted.
+These functions all return \fBTRUE\fP or \fBFALSE\fP, except as noted.
.SH NOTES
Both a macro and a function are provided for each name.
.SH PORTABILITY
diff --git a/man/curs_touch.3x b/man/curs_touch.3x
index 9fa6d370b9a2..1d2bb8ee7a58 100644
--- a/man/curs_touch.3x
+++ b/man/curs_touch.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 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,7 +26,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_touch.3x,v 1.14 2010/12/04 18:38:55 tom Exp $
+.\" $Id: curs_touch.3x,v 1.21 2018/07/28 21:34:56 tom Exp $
.TH curs_touch 3X ""
.na
.hy 0
@@ -57,10 +57,12 @@
.SH DESCRIPTION
The \fBtouchwin\fR and \fBtouchline\fR 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
+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.
.PP
@@ -84,13 +86,22 @@ preceding routine descriptions.
.PP
X/Open does not define any error conditions.
In this implementation
-.RS
+.RS 3
.TP 5
\fBis_linetouched\fP
returns an error
if the window pointer is null, or
if the line number is outside the window.
-Note that ERR is distinct from TRUE and FALSE, which are the normal return values of this function.
+.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 \fBis_linetouched\fP.
+The actual function returns \fBFALSE\fP when it detects an error.
.TP 5
\fBwtouchln\fP
returns an error
@@ -98,14 +109,19 @@ if the window pointer is null, or
if the line number is outside the window.
.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.
+These functions were introduced by SVr4.
+The Solaris curses header file,
+for instance, defines both an actual function and macro for each.
+The macros give the same result as the actual functions.
+SVr4 curses 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
+The XSI Curses standard, Issue 4 describes these functions,
+but defines no error conditions.
.SH NOTES
-Note that all routines except \fBwtouchln\fR may be macros.
+All of these routines except \fBwtouchln\fR may be macros.
.SH SEE ALSO
\fBcurses\fR(3X),
\fBcurs_refresh\fR(3X),
diff --git a/man/curs_trace.3x b/man/curs_trace.3x
index ef784165e168..186601c9785c 100644
--- a/man/curs_trace.3x
+++ b/man/curs_trace.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2000-2009,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 2000-2017,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,145 +26,264 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_trace.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
+.\" $Id: curs_trace.3x,v 1.20 2019/12/07 18:55:02 tom Exp $
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.TH curs_trace 3X ""
.na
.hy 0
.SH NAME
+\fBcurses_trace\fR,
+\fBtrace\fR,
\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
+\fB_nc_tracebits\fR,
+\fB_tracedump\fR,
+\fB_tracemouse\fR \- \fBcurses\fR debugging routines
.ad
.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
.sp
-\fBvoid _tracef(const char *format, ...);\fR
-.br
-\fBvoid _tracedump(const char *label, WINDOW *win);\fR
-.br
-\fBchar *_traceattr(attr_t attr);\fR
+\fBunsigned curses_trace(const unsigned \fP\fIparam\fP\fB);\fR
+.sp
+\fBvoid _tracef(const char *\fP\fIformat\fP\fB, ...);\fR
+.sp
+\fBchar *_traceattr(attr_t \fP\fIattr\fP\fB);\fR
.br
-\fBchar *_traceattr2(int buffer, chtype ch);\fR
+\fBchar *_traceattr2(int \fP\fIbuffer\fP\fB, chtype \fP\fIch\fP\fB);\fR
.br
-\fBchar *_nc_tracebits(void);\fR
+\fBchar *_tracecchar_t(const cchar_t *\fP\fIstring\fP\fB);\fR
.br
-\fBchar * _tracecchar_t(const cchar_t *string);\fR
+\fBchar *_tracecchar_t2(int \fP\fIbuffer\fP\fB, const cchar_t *\fP\fIstring\fP\fB);\fR
.br
-\fBchar * _tracecchar_t2(int buffer, const cchar_t *string);\fR
+\fBchar *_tracechar(int \fP\fIch\fP\fB);\fR
.br
-\fBchar *_tracechar(int ch);\fR
+\fBchar *_tracechtype(chtype \fP\fIch\fP\fB);\fR
.br
-\fBchar *_tracechtype(chtype ch);\fR
+\fBchar *_tracechtype2(int \fP\fIbuffer\fP\fB, chtype \fP\fIch\fP\fB);\fR
+.sp
+\fBvoid _tracedump(const char *\fP\fIlabel\fP\fB, WINDOW *\fP\fIwin\fP\fB);\fR
.br
-\fBchar *_tracechtype2(int buffer, chtype ch);\fR
+\fBchar *_nc_tracebits(void);\fR
.br
-\fBchar *_tracemouse(const MEVENT *event);\fR
+\fBchar *_tracemouse(const MEVENT *\fP\fIevent\fP\fB);\fR
+.sp
+/* deprecated */
.br
-\fBvoid trace(const unsigned int param);\fR
+\fBvoid trace(const unsigned int \fP\fIparam\fP\fB);\fR
.SH DESCRIPTION
-The \fBtrace\fR routines are used for debugging the ncurses libraries,
+The \fIcurses trace\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
-\fIlibncurses_g.a\fR, but may be compiled into any model (shared, static,
+Some limitations apply:
+.bP
+Aside from \fBcurses_trace\fP,
+the other functions are normally available only with the debugging library
+e.g., \fIlibncurses_g.a\fR.
+.IP
+All of the trace functions 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.
-.PP
-The principal parts of this interface are the \fBtrace\fR routine which
-selectively enables different tracing features, and the \fB_tracef\fR
-routine which writes formatted data to the \fItrace\fR file.
+.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
+\fBcurses_trace\fR, which selectively enables different tracing features, and
+.bP
+\fB_tracef\fR, which writes formatted data to the \fItrace\fR 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
+The \fBcurses_trace\fR function is always available,
+whether or not the other trace functions are available:
+.bP
+If tracing is available,
+calling \fBcurses_trace\fR with a nonzero parameter
+updates the trace mask,
+and returns the previous trace mask.
+.IP
+When the trace mask is nonzero,
+ncurses 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_\fP\fIxxx\fR definitions in \fB<curses.h>\fR.
These include:
.TP 5
-TRACE_DISABLE
-turn off tracing.
+.B TRACE_DISABLE
+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
-TRACE_TIMES
+.B TRACE_TIMES
trace user and system times of updates.
.TP 5
-TRACE_TPUTS
-trace tputs calls.
+.B TRACE_TPUTS
+trace \fBtputs\fP(3X) calls.
.TP 5
-TRACE_UPDATE
+.B TRACE_UPDATE
trace update actions, old & new screens.
.TP 5
-TRACE_MOVE
+.B TRACE_MOVE
trace cursor movement and scrolling.
.TP 5
-TRACE_CHARPUT
+.B TRACE_CHARPUT
trace all character outputs.
.TP 5
-TRACE_ORDINARY
+.B TRACE_ORDINARY
trace all update actions.
The old and new screen contents are written to the trace file
for each refresh.
.TP 5
-TRACE_CALLS
+.B TRACE_CALLS
trace all curses calls.
The parameters for each call are traced, as well as return values.
.TP 5
-TRACE_VIRTPUT
+.B TRACE_VIRTPUT
trace virtual character puts, i.e., calls to \fBaddch\fR.
.TP 5
-TRACE_IEVENT
+.B TRACE_IEVENT
trace low-level input processing, including timeouts.
.TP 5
-TRACE_BITS
+.B TRACE_BITS
trace state of TTY control bits.
.TP 5
-TRACE_ICALLS
+.B TRACE_ICALLS
trace internal/nested calls.
.TP 5
-TRACE_CCALLS
+.B TRACE_CCALLS
trace per-character calls.
.TP 5
-TRACE_DATABASE
+.B TRACE_DATABASE
trace read/write of terminfo/termcap data.
.TP 5
-TRACE_ATTRS
+.B TRACE_ATTRS
trace changes to video attributes and colors.
.TP 5
-TRACE_MAXIMUM
+.B TRACE_MAXIMUM
maximum trace level, enables all of the separate trace features.
.PP
-Some tracing features are enabled whenever the \fBtrace\fR parameter
-is nonzero. Some features overlap.
+Some tracing features are enabled whenever the \fBcurses_trace\fR parameter
+is nonzero.
+Some features overlap.
The specific names are used as a guideline.
-.PP
+.SS Initialization
These functions check the \fBNCURSES_TRACE\fP environment variable,
-to set the tracing feature as if \fBtrace\fP was called:
-.RS
+to set the tracing feature as if \fBcurses_trace\fP was called:
+.RS 4
+.PP
+.na
+.hy 0
filter,
initscr,
new_prescr,
newterm,
nofilter,
+restartterm,
ripoffline,
setupterm,
slk_init,
-tgetent
+tgetent,
+use_env,
+use_extended_names,
+use_tioctl
+.hy
+.ad
.RE
-
+.SS Command-line Utilities
+.PP
+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
+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 \fBNCURSES_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
+If ncurses 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.
.SH PORTABILITY
These functions are not part of the XSI 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 ncurses:
+.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,
+ncurses 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
+\fBCURSES_TRACE_MASK\fP and
+\fBCURSES_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 ncurses 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).
diff --git a/man/curs_util.3x b/man/curs_util.3x
index 444f40e2cffb..092b411b8755 100644
--- a/man/curs_util.3x
+++ b/man/curs_util.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2012,2013 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,14 +27,15 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_util.3x,v 1.37 2013/07/20 19:43:45 tom Exp $
+.\" $Id: curs_util.3x,v 1.56 2019/11/30 21:04:02 tom Exp $
.TH curs_util 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.ie \n(.g .ds '' \(rq
.el .ds '' ''
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.na
.hy 0
@@ -56,13 +57,13 @@
.SH SYNOPSIS
\fB#include <curses.h>\fR
.sp
-\fBchar *unctrl(chtype c);\fR
+\fBconst char *unctrl(chtype c);\fR
.br
\fBwchar_t *wunctrl(cchar_t *c);\fR
.br
-\fBchar *keyname(int c);\fR
+\fBconst char *keyname(int c);\fR
.br
-\fBchar *key_name(wchar_t w);\fR
+\fBconst char *key_name(wchar_t w);\fR
.br
\fBvoid filter(void);\fR
.br
@@ -81,16 +82,18 @@
\fBint flushinp(void);\fR
.br
.SH DESCRIPTION
+.SS unctrl
+.PP
The \fBunctrl\fR routine returns a character string which is a printable
representation of the character \fIc\fR, ignoring attributes.
Control characters are displayed in the \fB^\fR\fIX\fR notation.
Printing characters are displayed as is.
The corresponding \fBwunctrl\fR returns a printable representation of
a wide character.
+.SS keyname/key_name
.PP
The \fBkeyname\fR routine returns a character string
corresponding to the key \fIc\fR:
-.RS 3
.bP
Printable characters are displayed as themselves,
e.g., a one-character string containing the key.
@@ -101,7 +104,7 @@ 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 TRUE parameter),
+or if \fBmeta\fP(3X) has been called with a \fBTRUE\fP parameter),
shown in the \fBM\-\fR\fIX\fR notation,
or are displayed as themselves.
In the latter case, the values may not be printable;
@@ -111,20 +114,34 @@ 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.
-.RE
+X/Open also lists an \*(``UNKNOWN KEY\*('' return value,
+which some implementations return rather than null.
.LP
The corresponding \fBkey_name\fR returns a character string corresponding
to the wide-character value \fIw\fR.
The two functions do not return the same set of strings;
the latter returns null where the former would display a meta character.
+.SS filter/nofilter
.PP
The \fBfilter\fR routine, if used, must be called before \fBinitscr\fR or
-\fBnewterm\fR are called. The effect is that, during those calls, \fBLINES\fR
-is set to 1; the capabilities \fBclear\fR, \fBcup\fR, \fBcud\fR, \fBcud1\fR,
-\fBcuu1\fR, \fBcuu\fR, \fBvpa\fR are disabled; and the \fBhome\fR string is
-set to the value of \fBcr\fR.
+\fBnewterm\fR are called.
+Calling \fBfilter\fP causes these changes in initialization:
+.bP
+\fBLINES\fR is set to 1;
+.bP
+the capabilities
+\fBclear\fR,
+\fBcud1\fR,
+\fBcud\fR,
+\fBcup\fR,
+\fBcuu1\fR,
+\fBcuu\fR,
+\fBvpa\fR
+are disabled;
+.bP
+the capability \fBed\fP is disabled if \fBbce\fP is set;
+.bP
+and the \fBhome\fR string is set to the value of \fBcr\fR.
.PP
The \fBnofilter\fP routine cancels the effect of a preceding \fBfilter\fP
call.
@@ -132,6 +149,7 @@ That allows the caller to initialize a screen on a different device,
using a different value of \fB$TERM\fP.
The limitation arises because the \fBfilter\fP routine modifies the
in-memory copy of the terminal information.
+.SS use_env
.PP
The \fBuse_env\fR routine, if used,
should be called before \fBinitscr\fR or
@@ -140,38 +158,40 @@ should be called before \fBinitscr\fR or
It modifies the way \fBncurses\fP treats environment variables
when determining the screen size.
.bP
-Normally ncurses looks first at the terminal database for the screen size.
+Normally \fBncurses\fP looks first at the terminal database for the screen size.
.IP
If \fBuse_env\fP was called with \fBFALSE\fP for parameter,
it stops here unless
-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,
+\fBncurses\fP examines the \fBLINES\fR or \fBCOLUMNS\fR environment variables,
using a value in those to override the results
from the operating system or terminal database.
.IP
-Ncurses also updates the screen size in response to SIGWINCH,
+\fBNcurses\fP also updates the screen size in response to \fBSIGWINCH\fP,
unless overridden by the \fBLINES\fR or \fBCOLUMNS\fR environment variables,
+.SS use_tioctl
.PP
The \fBuse_tioctl\fR routine, if used,
should be called before \fBinitscr\fR or \fBnewterm\fR are called
(because those compute the screen size).
After \fBuse_tioctl\fR is called with \fBTRUE\fR as an argument,
-ncurses modifies the last step in its computation of screen size as follows:
+\fBncurses\fP modifies the last step in its computation
+of screen size as follows:
.bP
checks if the \fBLINES\fR and \fBCOLUMNS\fR environment variables
are set to a number greater than zero.
.bP
-for each, ncurses updates the corresponding environment variable
+for each, \fBncurses\fP updates the corresponding environment variable
with the value that it has obtained via operating system call
or from the terminal database.
.bP
-ncurses re-fetches the value of the environment variables so that
+\fBncurses\fP re-fetches the value of the environment variables so that
it is still the environment variables which set the screen size.
.PP
The \fBuse_env\fP and \fBuse_tioctl\fP routines combine as
@@ -184,33 +204,58 @@ lw7 lw7 lw40.
\fIuse_env\fR/\fIuse_tioctl\fR/\fISummary\fR
TRUE/FALSE/T{
This is the default behavior.
-ncurses uses operating system calls
+\fBncurses\fP uses operating system calls
unless overridden by $LINES or $COLUMNS environment variables.
T}
TRUE/TRUE/T{
-ncurses updates $LINES and $COLUMNS based on operating system calls.
+\fBncurses\fP updates $LINES and $COLUMNS based on operating system calls.
T}
FALSE/TRUE/T{
-ncurses ignores $LINES and $COLUMNS, uses operating system calls to obtain size.
+\fBncurses\fP ignores $LINES and $COLUMNS,
+uses operating system calls to obtain size.
T}
FALSE/FALSE/T{
-ncurses relies on the terminal database to determine size.
+\fBncurses\fP relies on the terminal database to determine size.
T}
.TE
+.SS putwin/getwin
.PP
-The \fBputwin\fR routine writes all data associated with window \fIwin\fR into
-the file to which \fIfilep\fR points. This information can be later retrieved
+The \fBputwin\fR routine writes all data associated
+with window (or pad) \fIwin\fR into
+the file to which \fIfilep\fR points.
+This information can be later retrieved
using the \fBgetwin\fR function.
.PP
The \fBgetwin\fR routine reads window related data stored in the file by
-\fBputwin\fR. The routine then creates and initializes a new window using that
-data. It returns a pointer to the new window.
+\fBputwin\fR.
+The routine then creates and initializes a new window using that
+data.
+It returns a pointer to the new window.
+There are a few caveats:
+.bP
+the data written is a copy of the \fBWINDOW\fP structure,
+and its associated character cells.
+The format differs between the wide-character (\fBncursesw\fP) and
+non-wide (\fBncurses\fP) libraries.
+You can transfer data between the two, however.
+.bP
+the retrieved window is always created as a top-level window (or pad),
+rather than a subwindow.
+.bP
+the window's character cells contain the color pair \fIvalue\fP,
+but not the actual color \fInumbers\fP.
+If cells in the retrieved window use color pairs which have not been
+created in the application using \fBinit_pair\fP,
+they will not be colored when the window is refreshed.
+.SS delay_output
.PP
The \fBdelay_output\fR routine inserts an \fIms\fR millisecond pause
-in output. This routine should not be used extensively because
+in output.
+This routine should not be used extensively because
padding characters are used rather than a CPU pause.
If no padding character is specified,
this uses \fBnapms\fR to perform the delay.
+.SS flushinp
.PP
The \fBflushinp\fR routine throws away any typeahead that has been typed by the
user and has not yet been read by the program.
@@ -228,18 +273,71 @@ In this implementation
\fBflushinp\fR
returns an error if the terminal was not initialized.
.TP 5
-\fBmeta\fR
-returns an error if the terminal was not initialized.
-.TP 5
\fBputwin\fP
returns an error if the associated \fBfwrite\fP calls return an error.
.RE
.SH PORTABILITY
+.SS filter
+.PP
+The SVr4 documentation describes the action of \fBfilter\fR only in the vaguest
+terms.
+The description here is adapted from the XSI Curses standard (which
+erroneously fails to describe the disabling of \fBcuu\fR).
+.SS keyname
+.PP
+The \fBkeyname\fP function may return the names of user-defined
+string capabilities which are defined in the terminfo entry via the \fB\-x\fP
+option of \fB@TIC@\fP.
+This implementation automatically assigns at run-time keycodes to
+user-defined strings which begin with \*(``k\*(''.
+The keycodes start at KEY_MAX, but are not guaranteed to be
+the same value for different runs because user-defined codes are
+merged from all terminal descriptions which have been loaded.
+The \fBuse_extended_names\fP(3X) function controls whether this data is
+loaded when the terminal description is read by the library.
+.SS nofilter/use_tioctl
+.PP
+The \fBnofilter\fP and \fBuse_tioctl\fP routines are specific to \fBncurses\fP.
+They were not supported on Version 7, BSD or System V implementations.
+It is recommended that any code depending on \fBncurses\fP extensions
+be conditioned using NCURSES_VERSION.
+.SS putwin/getwin
+.PP
+The \fBputwin\fP and \fBgetwin\fP functions have several issues with
+portability:
+.bP
+The files written and read by these functions
+use an implementation-specific format.
+Although the format is an obvious target for standardization,
+it has been overlooked.
+.IP
+Interestingly enough, according to the copyright dates in Solaris source,
+the functions (along with \fBscr_init\fP, etc.) originated with
+the University of California, Berkeley (in 1982)
+and were later (in 1988) incorporated into SVr4.
+Oddly, there are no such functions in the 4.3BSD curses sources.
+.bP
+Most implementations simply dump the binary \fBWINDOW\fP structure to the file.
+These include SVr4 curses, NetBSD and PDCurses,
+as well as older \fBncurses\fP versions.
+This implementation
+(as well as the X/Open variant of Solaris curses, dated 1995)
+uses textual dumps.
+.IP
+The implementations which use binary dumps use block-I/O
+(the \fBfwrite\fP and \fBfread\fP functions).
+Those that use textual dumps use buffered-I/O.
+A few applications may happen to write extra data in the file using
+these functions.
+Doing that can run into problems mixing block- and buffered-I/O.
+This implementation reduces the problem on writes by flushing the output.
+However, reading from a file written using mixed schemes may not be successful.
+.SS unctrl/wunctrl
+.PP
The XSI Curses standard, Issue 4 describes these functions.
It states that \fBunctrl\fR and \fBwunctrl\fR will return a null pointer if
unsuccessful, but does not define any error conditions.
This implementation checks for three cases:
-.RS 3
.bP
the parameter is a 7-bit US\-ASCII code.
This is the case that X/Open Curses documented.
@@ -258,17 +356,13 @@ and returns the \*(``~@\*('', etc., values in that case.
.bP
parameter values outside the 0 to 255 range.
\fBunctrl\fP returns a null pointer.
-.RE
-.PP
-The SVr4 documentation describes the action of \fBfilter\fR only in the vaguest
-terms. The description here is adapted from the XSI Curses standard (which
-erroneously fails to describe the disabling of \fBcuu\fR).
.PP
The strings returned by \fBunctrl\fR in this implementation are determined
at compile time,
-showing C1 controls from the upper-128 codes with a `~' prefix rather than `^'.
+showing C1 controls from the upper-128 codes
+with a \*(``~\*('' prefix rather than \*(``^\*(''.
Other implementations have different conventions.
-For example, they may show both sets of control characters with `^',
+For example, they may show both sets of control characters with \*(``^\*('',
and strip the parameter to 7 bits.
Or they may ignore C1 controls and treat all of the upper-128 codes as
printable.
@@ -277,37 +371,37 @@ locale.
The \fBuse_legacy_coding\fP 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
-curses is initialized.
+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
-The \fBkeyname\fP function may return the names of user-defined
-string capabilities which are defined in the terminfo entry via the \fB\-x\fP
-option of \fB@TIC@\fP.
-This implementation automatically assigns at run-time keycodes to
-user-defined strings which begin with "k".
-The keycodes start at KEY_MAX, but are not guaranteed to be
-the same value for different runs because user-defined codes are
-merged from all terminal descriptions which have been loaded.
-The \fBuse_extended_names\fP function controls whether this data is
-loaded when the terminal description is read by the library.
+X/Open Curses documents \fBunctrl\fP as declared in \fB<unctrl.h>\fP,
+which \fBncurses\fP does.
+However, \fBncurses\fP' \fB<curses.h>\fP includes \fB<unctrl.h>\fP,
+matching the behavior of SVr4 curses.
+Other implementations may not do that.
+.SS use_env/use_tioctl
.PP
-The \fBnofilter\fP and \fBuse_tioctl\fP 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 ncurses extensions
-be conditioned using NCURSES_VERSION.
+If \fBncurses\fP is configured to provide the sp-functions extension,
+the state of \fBuse_env\fP and \fBuse_tioctl\fP may be updated before
+creating each \fIscreen\fP rather than once only
+(\fBcurs_sp_funcs\fR(3X)).
+This feature of \fBuse_env\fP
+is not provided by other implementation of curses.
.SH SEE ALSO
\fBlegacy_coding\fR(3X),
\fBcurses\fR(3X),
\fBcurs_initscr\fR(3X),
+\fBcurs_inopts\fR(3X),
\fBcurs_kernel\fR(3X),
\fBcurs_scr_dump\fR(3X),
+\fBcurs_sp_funcs\fR(3X),
\fBcurs_variables\fR(3X),
\fBlegacy_coding\fR(3X).
diff --git a/man/curs_variables.3x b/man/curs_variables.3x
index efbe192a4882..5d7de8c61553 100644
--- a/man/curs_variables.3x
+++ b/man/curs_variables.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2010,2013 Free Software Foundation, Inc. *
+.\" Copyright (c) 2010-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,10 +26,15 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_variables.3x,v 1.6 2013/12/21 18:41:32 tom Exp $
+.\" $Id: curs_variables.3x,v 1.13 2019/06/01 22:51:21 tom Exp $
.TH curs_variables 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.ds n 5
.na
@@ -99,7 +104,7 @@ 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).
+(see curses(3X)).
.SS LINES
After initializing curses, this variable contains the height of the screen,
i.e., the number of lines.
@@ -110,9 +115,18 @@ when converting a tab character to spaces as it adds the tab to a window
.SS The Current Screen
This implementation of curses uses a special window \fBcurscr\fP to
record its updates to the terminal screen.
+.PP
+This is referred to as the \*(``physical screen\*('' in the
+\fBcurs_refresh\fR(3X) and
+\fBcurs_outopts\fR(3X) manual pages.
.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.
+.PP
+This is referred to as the \*(``virtual screen\*('' in the
+\fBcurs_kernel\fR(3X),
+\fBcurs_refresh\fR(3X) and
+\fBcurs_outopts\fR(3X) manual pages.
.SS The Standard Screen
Upon initializing curses,
a default window called \fBstdscr\fP,
@@ -125,8 +139,45 @@ or \fBnewterm\fR(3X).
If \fBcurses\fP is configured to use separate curses/terminfo libraries,
most of these variables reside in the curses library.
.SH PORTABILITY
-ESCDELAY and TABSIZE are extensions,
-not provided in most other implementations of curses.
+\fBTABSIZE\fP is a feature of SVr4 curses
+which is not documented by X/Open curses.
+.bP
+In SVr4 curses, \fBTABSIZE\fP is initially set from the terminal description's
+\fBinit_tabs\fP capability.
+After that, it can be altered by the applications using SVr4 curses.
+.IP
+SVr4 curses uses the current value of \fBTABSIZE\fP to
+compute the position of tabstops for updating both
+the virtual screen with \fBaddch\fP(3X) as well as
+the physical screen with \fBmvcur\fP(3X).
+.bP
+This implementation uses the current value of \fBTABSIZE\fP only for
+updating the virtual screen.
+It uses the terminal description's \fBit\fP (\fBinit_tabs\fP) capability for
+computing hardware tabs (i.e., tab stops on the physical screen).
+.bP
+Other implementations differ.
+For instance, NetBSD curses allows \fBTABSIZE\fP to be set through
+an environment variable.
+This implementation does not.
+.IP
+NetBSD curses does not support hardware tabs;
+it uses the \fBinit_tabs\fP capability and the \fBTABSIZE\fP variable
+only for updating the virtual screen.
+.PP
+\fBESCDELAY\fP is an extension in AIX curses:
+.bP
+In AIX, the units for \fBESCDELAY\fP are \fIfifths\fP of a millisecond.
+.bP
+The default value for AIX's \fBESCDELAY\fP is 0.1 seconds.
+.bP
+AIX also enforces a limit of 10,000 seconds for \fBESCDELAY\fP;
+this implementation currently has no upper limit.
+.PP
+This implementation has long used \fBESCDELAY\fP with units of milliseconds,
+making it impossible to be completely compatible with AIX.
+Likewise, most users have either decided to override the value,
+or rely upon its default value.
.SH SEE ALSO
\fBcurses\fR(3X),
\fBcurs_opaque\fR(3X),
diff --git a/man/curs_window.3x b/man/curs_window.3x
index 9ef41ff523d1..f53f3d778385 100644
--- a/man/curs_window.3x
+++ b/man/curs_window.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 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,7 +26,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_window.3x,v 1.17 2010/12/04 18:38:55 tom Exp $
+.\" $Id: curs_window.3x,v 1.20 2016/10/15 17:26:09 tom Exp $
.TH curs_window 3X ""
.na
.hy 0
@@ -47,81 +47,110 @@
.SH SYNOPSIS
\fB#include <curses.h>\fR
.sp
-\fBWINDOW *newwin(int nlines, int ncols, int begin_y,\fR
- \fBint begin_x);\fR
+\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 *win);\fR
+\fBint delwin(WINDOW *\fP\fIwin\fP\fB);\fR
.br
-\fBint mvwin(WINDOW *win, int y, int x);\fR
+\fBint mvwin(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR
.br
-\fBWINDOW *subwin(WINDOW *orig, int nlines, int ncols,\fR
- \fBint begin_y, int begin_x);\fR
+\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 *orig, int nlines, int ncols,\fR
- \fBint begin_y, int begin_x);\fR
+\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 *win, int par_y, int par_x);\fR
+\fBint mvderwin(WINDOW *\fP\fIwin\fP\fB, int \fP\fIpar_y\fP\fB, int \fP\fIpar_x\fP\fB);\fR
.br
-\fBWINDOW *dupwin(WINDOW *win);\fR
+\fBWINDOW *dupwin(WINDOW *\fP\fIwin\fP\fB);\fR
.br
-\fBvoid wsyncup(WINDOW *win);\fR
+\fBvoid wsyncup(WINDOW *\fP\fIwin\fP\fB);\fR
.br
-\fBint syncok(WINDOW *win, bool bf);\fR
+\fBint syncok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
.br
-\fBvoid wcursyncup(WINDOW *win);\fR
+\fBvoid wcursyncup(WINDOW *\fP\fIwin\fP\fB);\fR
.br
-\fBvoid wsyncdown(WINDOW *win);\fR
+\fBvoid wsyncdown(WINDOW *\fP\fIwin\fP\fB);\fR
.br
.SH DESCRIPTION
+.SS newwin
Calling \fBnewwin\fR 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 line \fIbegin\fR_\fIy\fR, column \fIbegin\fR_\fIx\fR. If either
-\fInlines\fR or \fIncols\fR is zero, they default to \fBLINES \-\fR
-\fIbegin\fR_\fIy\fR and \fBCOLS \-\fR \fIbegin\fR_\fIx\fR. A new full-screen
-window is created by calling \fBnewwin(0,0,0,0)\fR.
+given number of lines and columns.
+The upper left-hand corner of the window is
+at
+.RS
+line \fIbegin\fR_\fIy\fR,
+.br
+column \fIbegin\fR_\fIx\fR
+.RE
+.PP
+If either
+\fInlines\fR or \fIncols\fR is zero, they default to
+.RS
+\fBLINES \-\fR \fIbegin\fR_\fIy\fR and
+.br
+\fBCOLS \-\fR \fIbegin\fR_\fIx\fR.
+.RE
+.PP
+A new full-screen window is created by calling \fBnewwin(0,0,0,0)\fR.
+.SS delwin
.PP
Calling \fBdelwin\fR 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.
+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). 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.
+corner is at position (\fIx\fR, \fIy\fR).
+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. (This position is relative to the
-screen, and not to the window \fIorig\fR.) The window is made in the
-middle of the window \fIorig\fR, so that changes made to one window
-will affect both windows. The subwindow shares memory with the window
-\fIorig\fR. When using this routine, it is necessary to call
+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,
+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.
+.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. There is no
-difference between the subwindows and the derived windows.
+of the window \fIorig\fR 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)
-inside its parent window. The screen-relative parameters of the
-window are not changed. This routine is used to display different
+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.
+.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
+changed in \fIwin\fR.
+If \fBsyncok\fR is called with second argument
\fBTRUE\fR then \fBwsyncup\fR 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
-touched in any of its ancestor windows. This routine is called by
+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.
+.SS wcursyncup
.PP
The routine \fBwcursyncup\fR updates the current cursor position of all the
ancestors of the window to reflect the current cursor position of the
@@ -135,11 +164,18 @@ Routines that return pointers return \fBNULL\fR on error.
.PP
X/Open defines no error conditions.
In this implementation
-.RS
.TP 5
\fBdelwin\fR
returns an error if the window pointer is null, or
if the window is the parent of another window.
+.TP 5
+\fBderwin\fP
+returns an error if the parent window pointer is null, or
+if any of its ordinates or dimensions is negative, or
+if the resulting window does not fit inside the parent window.
+.TP 5
+\fBdupwin\fP
+returns an error if the window pointer is null.
.IP
This implementation also maintains a list of windows,
and checks that the pointer passed to \fBdelwin\fP is one that
@@ -156,26 +192,40 @@ if the window pointer is null, or
if the window is really a pad, or
if some part of the window would be placed off-screen.
.TP 5
+\fBnewwin\fP
+will fail if either of its beginning ordinates is negative, or
+if either the number of lines or columns is negative.
+.TP 5
\fBsyncok\fP
returns an error
if the window pointer is null.
-.RE
+.TP 5
+\fBsubwin\fP
+returns an error if the parent window pointer is null, or
+if any of its ordinates or dimensions is negative, or
+if the resulting window does not fit inside the parent window.
+.PP
+The functions which return a window pointer
+may also fail if there is insufficient memory for its data structures.
+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
degrade performance.
.PP
Note that \fBsyncok\fR may be a macro.
.SH BUGS
-The subwindow functions (\fIsubwin\fR, \fIderwin\fR, \fImvderwin\fR,
+The subwindow functions (\fBsubwin\fR, \fBderwin\fR, \fBmvderwin\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
+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.
+is patterned on the XPG4 curses standard.
+The weaker XPG4 spec may result in slower updates.
.SH PORTABILITY
The XSI Curses standard, Issue 4 describes these functions.
.SH SEE ALSO
diff --git a/man/default_colors.3x b/man/default_colors.3x
index 0b85598eea45..d77022931e5b 100644
--- a/man/default_colors.3x
+++ b/man/default_colors.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2011 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -28,8 +28,12 @@
.\"
.\" 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 $
+.\" $Id: default_colors.3x,v 1.28 2019/11/30 21:06:30 tom Exp $
.TH default_colors 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.SH NAME
\fBuse_default_colors\fR,
\fBassume_default_colors\fR \- use terminal's default colors
@@ -40,10 +44,7 @@
.br
\fBint assume_default_colors(int fg, int bg);\fP
.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 +56,21 @@ Some applications are designed to work with the default background,
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.
@@ -85,34 +86,36 @@ The following are equivalent:
These are ncurses 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.
+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()
+.B assume_default_colors
ncurses 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
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 \fIded\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,15 +123,17 @@ noting that color xterm (and similar programs) provides a background color
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 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_color\fR(3X),
diff --git a/man/define_key.3x b/man/define_key.3x
index 18eaff87cb11..e93661fcb32a 100644
--- a/man/define_key.3x
+++ b/man/define_key.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2009,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 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 *
@@ -28,7 +28,7 @@
.\"
.\" Author: Thomas E. Dickey 1997
.\"
-.\" $Id: define_key.3x,v 1.14 2010/12/04 18:49:20 tom Exp $
+.\" $Id: define_key.3x,v 1.16 2018/07/28 21:34:56 tom Exp $
.TH define_key 3X ""
.SH NAME
\fBdefine_key\fP \- define a keycode
@@ -48,13 +48,15 @@ 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
+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
+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
\fBkeyok\fR(3X),
diff --git a/man/form.3x b/man/form.3x
index 775c8331c958..32583fe75d3f 100644
--- a/man/form.3x
+++ b/man/form.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2008,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,8 +27,16 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form.3x,v 1.24 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form.3x,v 1.33 2019/11/30 20:51:36 tom Exp $
.TH form 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
\fBform\fR \- curses extension for programming forms
.SH SYNOPSIS
@@ -36,7 +44,8 @@
.br
.SH DESCRIPTION
The \fBform\fR library provides terminal-independent facilities for composing
-form screens on character-cell terminals. The library includes: field
+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.
@@ -56,10 +65,12 @@ before using any of these functions.
.
.SS Current Default Values for Field Attributes
.
-The \fBform\fR library maintains a default value for field attributes. You
+The \fBform\fR library maintains a default value for field attributes.
+You
can get or set this default by calling the appropriate \fBset_\fR
or retrieval
-routine with a \fBNULL\fR field pointer. Changing this default with a
+routine with a \fBNULL\fR field pointer.
+Changing this default with a
\fBset_\fR function affects future field creations, but does not change the
rendering of fields already created.
.
@@ -96,6 +107,7 @@ 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)
@@ -145,6 +157,7 @@ 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)
+unfocus_current_field \fBform_page\fR(3X)
unpost_form \fBform_post\fR(3X)
.TE
.SH RETURN VALUE
@@ -185,26 +198,44 @@ The form is already posted.
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\fR(3)).
.TP 5
.B E_UNKNOWN_COMMAND
The form driver code saw an unknown request code.
-.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 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).
+you want to say \*(``\-lform \-lncurses\*('', not the other way around
+(which would give you a link error when using static libraries).
.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 menu facility was documented in SVr4.2 in
+\fICharacter User Interface Programming (UNIX SVR4.2)\fP.
+.PP
+It is not part of X/Open Curses.
+.PP
+Aside from ncurses, 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 ncurses,
+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 ncurses 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@).
diff --git a/man/form_cursor.3x b/man/form_cursor.3x
index ed4b420d29ee..b0073e1fe232 100644
--- a/man/form_cursor.3x
+++ b/man/form_cursor.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,10 +27,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_cursor.3x,v 1.8 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form_cursor.3x,v 1.11 2019/01/20 20:31:42 tom Exp $
.TH form_cursor 3X ""
.SH NAME
-\fBform_cursor\fR \- position a form window cursor
+\fBpos_form_cursor\fR \- position a form window cursor
.SH SYNOPSIS
\fB#include <form.h>\fR
.br
@@ -38,7 +38,8 @@ int pos_form_cursor(FORM *form);
.br
.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
+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
form operation.
.SH RETURN VALUE
@@ -54,7 +55,7 @@ Routine detected an incorrect or out-of-range argument.
The form has not been posted.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
@@ -62,8 +63,9 @@ System error occurred (see \fBerrno\fR).
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.
diff --git a/man/form_data.3x b/man/form_data.3x
index ed39bf5a3ed5..33c5e6ecaac0 100644
--- a/man/form_data.3x
+++ b/man/form_data.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2015,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,10 +27,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_data.3x,v 1.10 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form_data.3x,v 1.12 2018/07/28 21:34:06 tom Exp $
.TH form_data 3X ""
.SH NAME
-\fBform_data\fR \- test for off-screen data in given forms
+\fBdata_ahead\fP,
+\fBdata_behind\fR \- test for off-screen data in given forms
.SH SYNOPSIS
\fB#include <form.h>\fR
.br
@@ -40,18 +41,21 @@ 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).
+ahead in the given form.
+It returns TRUE (1) or FALSE (0).
.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).
+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.
.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.
diff --git a/man/form_driver.3x b/man/form_driver.3x
index 67a986b006ba..3b8308a92748 100644
--- a/man/form_driver.3x
+++ b/man/form_driver.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2008,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,215 +26,146 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_driver.3x,v 1.22 2010/12/04 18:38:55 tom Exp $
+.\" $Id: form_driver.3x,v 1.32 2019/01/20 20:31:42 tom Exp $
.TH form_driver 3X ""
.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\fR,
+\fBform_driver_w\fR \- command-processing loop of the form system
.SH SYNOPSIS
\fB#include <form.h>\fR
.br
-int form_driver(FORM *form, int c);
+\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
.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:
.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
checked according to the program's locale settings.
.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
The form driver requests are as follows:
-.TP 5
-REQ_NEXT_PAGE
-Move to the next page.
-.TP 5
-REQ_PREV_PAGE
-Move to the previous page.
-.TP 5
-REQ_FIRST_PAGE
-Move to the first page.
-.TP 5
-REQ_LAST_PAGE
-Move to the last field.
-.sp
-.TP 5
-REQ_NEXT_FIELD
-Move to the next field.
-.TP 5
-REQ_PREV_FIELD
-Move to the previous field.
-.TP 5
-REQ_FIRST_FIELD
-Move to the first field.
-.TP 5
-REQ_LAST_FIELD
-Move to the last field.
-.TP 5
-REQ_SNEXT_FIELD
-Move to the sorted next field.
-.TP 5
-REQ_SPREV_FIELD
-Move to the sorted previous field.
-.TP 5
-REQ_SFIRST_FIELD
-Move to the sorted first field.
-.TP 5
-REQ_SLAST_FIELD
-Move to the sorted last field.
-.TP 5
-REQ_LEFT_FIELD
-Move left to a field.
-.TP 5
-REQ_RIGHT_FIELD
-Move right to a field.
-.TP 5
-REQ_UP_FIELD
-Move up to a field.
-.TP 5
-REQ_DOWN_FIELD
-Move down to a field.
-.sp
-.TP 5
-REQ_NEXT_CHAR
-Move to the next char.
-.TP 5
-REQ_PREV_CHAR
-Move to the previous char.
-.TP 5
-REQ_NEXT_LINE
-Move to the next line.
-.TP 5
-REQ_PREV_LINE
-Move to the previous line.
-.TP 5
-REQ_NEXT_WORD
-Move to the next word.
-.TP 5
-REQ_PREV_WORD
-Move to the previous word.
-.TP 5
-REQ_BEG_FIELD
-Move to the beginning of the field.
-.TP 5
-REQ_END_FIELD
-Move to the end of the field.
-.TP 5
-REQ_BEG_LINE
-Move to the beginning of the line.
-.TP 5
-REQ_END_LINE
-Move to the end of the line.
-.TP 5
-REQ_LEFT_CHAR
-Move left in the field.
-.TP 5
-REQ_RIGHT_CHAR
-Move right in the field.
-.TP 5
-REQ_UP_CHAR
-Move up in the field.
-.TP 5
-REQ_DOWN_CHAR
-Move down in the field.
-.sp
-.TP 5
-REQ_NEW_LINE
-Insert or overlay a new line.
-.TP 5
-REQ_INS_CHAR
-Insert a blank at the cursor.
-.TP 5
-REQ_INS_LINE
-Insert a blank line at the cursor.
-.TP 5
-REQ_DEL_CHAR
-Delete character at the cursor.
-.TP 5
-REQ_DEL_PREV
-Delete character before the cursor.
-.TP 5
-REQ_DEL_LINE
-Delete line at the cursor.
-.TP 5
-REQ_DEL_WORD
-Delete blank-delimited word at the cursor.
-.TP 5
-REQ_CLR_EOL
-Clear to end of line from cursor.
-.TP 5
-REQ_CLR_EOF
-Clear to end of field from cursor.
-.TP 5
-REQ_CLR_FIELD
-Clear the entire field.
-.TP 5
-REQ_OVL_MODE
-Enter overlay mode.
-.TP 5
-REQ_INS_MODE
-Enter insert mode.
-.sp
-.TP 5
-REQ_SCR_FLINE
-Scroll the field forward a line.
-.TP 5
-REQ_SCR_BLINE
-Scroll the field backward a line.
-.TP 5
-REQ_SCR_FPAGE
-Scroll the field forward a page.
-.TP 5
-REQ_SCR_BPAGE
-Scroll the field backward a page.
-.TP 5
-REQ_SCR_FHPAGE
-Scroll the field forward half a page.
-.TP 5
-REQ_SCR_BHPAGE
-Scroll the field backward half a page.
-.sp
-.TP 5
-REQ_SCR_FCHAR
-Scroll the field forward a character.
-.TP 5
-REQ_SCR_BCHAR
-Scroll the field backward a character.
-.TP 5
-REQ_SCR_HFLINE
-Horizontal scroll the field forward a line.
-.TP 5
-REQ_SCR_HBLINE
-Horizontal scroll the field backward a line.
-.TP 5
-REQ_SCR_HFHALF
-Horizontal scroll the field forward half a line.
-.TP 5
-REQ_SCR_HBHALF
-Horizontal scroll the field backward half a line.
-.sp
-.TP
-REQ_VALIDATION
-Validate field.
-.TP
-REQ_NEXT_CHOICE
-Display next field choice.
-.TP
-REQ_PREV_CHOICE
-Display previous field choice.
+.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.
+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_DOWN_FIELD Move down to a field.
+REQ_END_FIELD Move to the end of the 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.
+REQ_INS_CHAR Insert a blank at the cursor.
+REQ_INS_LINE Insert a blank line at the cursor.
+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_FIELD Move left to a field.
+REQ_NEW_LINE Insert or overlay a new line.
+REQ_NEXT_CHAR Move to the next char.
+REQ_NEXT_CHOICE Display next field choice.
+REQ_NEXT_FIELD Move to the next field.
+REQ_NEXT_LINE Move to the next line.
+REQ_NEXT_PAGE Move to the next page.
+REQ_NEXT_PAGE Move to the next page.
+REQ_NEXT_WORD Move to the next word.
+REQ_OVL_MODE Enter overlay mode.
+REQ_PREV_CHAR Move to the previous char.
+REQ_PREV_CHOICE Display previous field choice.
+REQ_PREV_FIELD Move to the previous field.
+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_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_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_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
+.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
.PP
If the second argument is the KEY_MOUSE special key, the associated
mouse event is translated into one of the above pre-defined requests.
@@ -279,9 +210,10 @@ If a translation
into a request was done, \fBform_driver\fR returns the result of this request.
.RE
.PP
-If you clicked outside the user window or the mouse event could not be translated
+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
+.SS Application-defined commands
.PP
If the second argument is neither printable nor one of the above
pre-defined form requests, the driver assumes it is an application-specific
@@ -306,11 +238,14 @@ The form has not been posted.
.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\fR(3)).
.TP 5
.B E_UNKNOWN_COMMAND
The form driver code saw an unknown request code.
@@ -318,14 +253,18 @@ The form driver code saw an unknown request code.
.SH SEE ALSO
\fBcurses\fR(3X),
\fBform\fR(3X),
+\fBform_field_buffer\fR(3X),
+\fBform_field_validation\fR(3X),
+\fBform_fieldtype\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.
diff --git a/man/form_field.3x b/man/form_field.3x
index 19a8b88ef984..cab42679f34f 100644
--- a/man/form_field.3x
+++ b/man/form_field.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,7 +27,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field.3x,v 1.11 2012/11/03 23:03:59 tom Exp $
+.\" $Id: form_field.3x,v 1.13 2019/01/20 20:31:42 tom Exp $
.TH form_field 3X ""
.SH NAME
\fBform_field\fR \- make and break connections between fields and forms
@@ -75,18 +75,19 @@ The field is already connected to a form.
The form is already posted.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.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
The SVr4 forms library documentation specifies the \fBfield_count\fR error value
as \-1 (which is the value of \fBERR\fR).
.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.
diff --git a/man/form_field_attributes.3x b/man/form_field_attributes.3x
index da3ad793876b..e8c114aeb684 100644
--- a/man/form_field_attributes.3x
+++ b/man/form_field_attributes.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,8 +27,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_attributes.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form_field_attributes.3x,v 1.15 2019/11/30 21:01:57 tom Exp $
.TH form_field_attributes 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.SH NAME
\fBform_field_attributes\fR \- color and attribute control for form fields
.SH SYNOPSIS
@@ -49,16 +53,20 @@ int field_pad(const FIELD *field);
.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
+function \fBfield_fore\fR returns the foreground attribute.
+The default is
\fBA_STANDOUT\fR.
.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
+form.
+The function \fBfield_back\fR returns the background attribute.
+The
default is \fBA_NORMAL\fR.
.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 \fBfield_pad\fR returns the given form's pad character.
+The
default is a blank.
.SH RETURN VALUE
These routines return one of the following:
@@ -70,17 +78,18 @@ The routine succeeded.
Routine detected an incorrect or out-of-range argument.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.
.SH SEE ALSO
-\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed
+\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.
diff --git a/man/form_field_buffer.3x b/man/form_field_buffer.3x
index b4ff8cb7665d..93299186675f 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,10 +27,15 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_buffer.3x,v 1.19 2010/12/04 18:38:55 tom Exp $
+.\" $Id: form_field_buffer.3x,v 1.24 2019/11/30 21:02:22 tom Exp $
.TH form_field_buffer 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.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
@@ -85,7 +90,8 @@ 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
+\fIfield\fR; \fBfield_status\fR 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.
@@ -108,12 +114,12 @@ The remaining routines return one of the following:
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(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
+\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
@@ -125,8 +131,13 @@ 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 ncurses 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.
diff --git a/man/form_field_info.3x b/man/form_field_info.3x
index 6a1af6c3139b..51e8989af134 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,10 +27,15 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_info.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form_field_info.3x,v 1.16 2019/11/30 21:02:29 tom Exp $
.TH form_field_info 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.SH NAME
-\fBform_field_info\fR \- retrieve field characteristics
+\fBdynamic_field_info\fP,
+\fBfield_info\fR \- retrieve field characteristics
.SH SYNOPSIS
\fB#include <form.h>\fR
.br
@@ -41,12 +46,14 @@ int dynamic_field_info(const FIELD *field, int *rows, int *cols, int *max);
.br
.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
+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
+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.
@@ -57,23 +64,24 @@ These routines return one of the following:
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(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
+\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.
diff --git a/man/form_field_just.3x b/man/form_field_just.3x
index 2f223e91e7bf..ad8eb3d79f05 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,10 +27,15 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_just.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form_field_just.3x,v 1.15 2019/11/30 21:02:36 tom Exp $
.TH form_field_just 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.SH NAME
-\fBform_field_just\fR \- retrieve field characteristics
+\fBset_field_just\fR,
+\fBfield_just\fP \- retrieve field characteristics
.SH SYNOPSIS
\fB#include <form.h>\fR
.br
@@ -54,19 +59,20 @@ The function \fBset_field_just\fR returns one of the following:
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(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
+\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.
diff --git a/man/form_field_new.3x b/man/form_field_new.3x
index 23a351663688..38f34bbe6e39 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 (c) 1998-2015,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,10 +27,13 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_new.3x,v 1.18 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form_field_new.3x,v 1.20 2018/07/28 21:34:06 tom Exp $
.TH form_field_new 3X ""
.SH NAME
-\fBform_field_new\fR \- create and destroy form fields
+\fBnew_field\fR,
+\fBdup_field\fR,
+\fBlink_field\fR,
+\fBfree_field\fR \- create and destroy form fields
.SH SYNOPSIS
\fB#include <form.h>\fR
.br
@@ -49,14 +52,17 @@ The function \fBnew_field\fR 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\fR 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.
+shares buffers with its parent.
+Attribute data is separate.
.PP
The function \fBfree_field\fR de-allocates storage associated with a field.
.SH RETURN VALUE
@@ -89,12 +95,13 @@ field is connected.
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
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.
diff --git a/man/form_field_opts.3x b/man/form_field_opts.3x
index a33a0414d3e0..d1076722e6b7 100644
--- a/man/form_field_opts.3x
+++ b/man/form_field_opts.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,10 +27,13 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_opts.3x,v 1.16 2010/12/04 18:41:07 tom Exp $
+.\" $Id: form_field_opts.3x,v 1.24 2019/01/20 20:19:03 tom Exp $
.TH form_field_opts 3X ""
.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
@@ -54,42 +57,68 @@ others alone.
.PP
The function \fBfield_opts\fR returns the field's current option bits.
.PP
-The following options are defined (all are on by default):
-.TP 5
-O_VISIBLE
-The field is displayed. If this option is off, display of the field is
-suppressed.
+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_PUBLIC
-The field contents are displayed as data is entered.
-.TP 5
-O_EDIT
-The field can be edited.
-.TP 5
-O_WRAP
-Words that do not fit on a line are wrapped to the next line. Words are
-blank-separated.
+O_AUTOSKIP
+Skip to the next field when this one fills.
.TP 5
O_BLANK
The field is cleared whenever a character is entered at the first position.
.TP 5
-O_AUTOSKIP
-Skip to the next field when this one fills.
+O_EDIT
+The field can be edited.
.TP 5
O_NULLOK
Allow a blank field.
.TP 5
+O_PASSOK
+Validate field only if modified by user.
+.TP 5
+O_PUBLIC
+The field contents are displayed as data is entered.
+.TP 5
O_STATIC
Field buffers are fixed to field's original size.
Turn this option off to create a dynamic field.
.TP 5
-O_PASSOK
-Validate field only if modified by user.
+O_VISIBLE
+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
+blank-separated.
+.PP
+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:
.TP 5
@@ -103,15 +132,18 @@ Routine detected an incorrect or out-of-range argument.
The field is the current field.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.SH SEE ALSO
-\fBcurses\fR(3X), \fBform\fR(3X).
+\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.
.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.
diff --git a/man/form_field_userptr.3x b/man/form_field_userptr.3x
index 898da976f971..41e8fbe504a1 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 (c) 1998-2015,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,10 +27,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_userptr.3x,v 1.10 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form_field_userptr.3x,v 1.12 2018/07/28 21:34:06 tom Exp $
.TH form_field_userptr 3X ""
.SH NAME
-\fBform_field_userptr\fR \- associate application data with a form field
+\fBset_field_userptr\fR,
+\fBfield_userptr\fR \- associate application data with a form field
.SH SYNOPSIS
\fB#include <form.h>\fR
.br
@@ -40,7 +41,8 @@ void *field_userptr(const FIELD *field);
.br
.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).
@@ -53,11 +55,12 @@ The function \fBset_field_userptr\fR returns \fBE_OK\fP (success).
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
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.
diff --git a/man/form_field_validation.3x b/man/form_field_validation.3x
index 3505fdb231b8..2f78fa45ba3c 100644
--- a/man/form_field_validation.3x
+++ b/man/form_field_validation.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,8 +26,16 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_validation.3x,v 1.20 2010/12/04 18:38:55 tom Exp $
+.\" $Id: form_field_validation.3x,v 1.24 2019/01/20 20:31:42 tom Exp $
.TH form_field_validation 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
\fBform_field_validation\fR \- data type validation for fields
.SH SYNOPSIS
@@ -59,70 +67,112 @@ 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.
+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.
+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.
+Accept one of a specified set of strings.
+Requires additional parameters:
+.RS
+.bP
+a third \fB(char **)\fR argument pointing to a string list;
+.bP
+a fourth \fBint\fR flag argument to enable case-sensitivity;
+.bP
+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.
+.IP
+The library copies the string list,
+so you may use a list that lives in automatic variables on the stack.
+.RE
.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.
+Integer data, parsable to an integer by \fBatoi\fP(3).
+Requires additional parameters:
+.RS
+.bP
+a third \fBint\fR argument controlling the precision,
+.bP
+a fourth \fBlong\fR argument constraining minimum value,
+.bP
+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.
+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.
+.IP
+For details of the precision handling see \fBprintf\fR(3).
+.RE
.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.
+Numeric data (may have a decimal-point part).
+This requires additional parameters:
+.RS
+.bP
+a third \fBint\fR argument controlling the precision,
+.bP
+a fourth \fBdouble\fR argument constraining minimum value,
+.bP
+and a fifth \fBdouble\fR 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.
+.IP
+On return, the field buffer is formatted according to the
+\fBprintf\fR format specification \*(``.*f\*('',
+where the \*(``*\*('' is replaced by the precision argument.
+.IP
+For details of the precision handling see \fBprintf\fR(3).
+.RE
.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
+Regular expression data.
+Requires a regular expression \fB(char *)\fR third argument.
+The data is valid if the regular expression matches it.
+.IP
+Regular expressions
+are in the format of \fBregcomp\fR and \fBregexec\fR.
+.IP
+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.
+An Internet Protocol Version 4 address.
+This requires no additional argument.
+The library checks 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.
+.IP
+This is an ncurses extension;
+this field type may not be available in other curses implementations.
.PP
-It is possible to set up new programmer-defined field types. See the
-\fBform_fieldtype\fR(3X) manual page.
+It is possible to set up new programmer-defined field types.
+See the \fBform_fieldtype\fR(3X) manual page.
.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\fR and \fBfield_arg\fR return \fBNULL\fR on error.
+The function \fBset_field_type\fR 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\fR(3)).
.SH SEE ALSO
\fBcurses\fR(3X),
\fBform\fR(3X),
@@ -131,8 +181,9 @@ System error occurred (see \fBerrno\fR).
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.
diff --git a/man/form_fieldtype.3x b/man/form_fieldtype.3x
index 028e9b0befcc..50f8627842b4 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,7 +27,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_fieldtype.3x,v 1.16 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form_fieldtype.3x,v 1.19 2019/01/20 20:31:42 tom Exp $
.TH form_fieldtype 3X ""
.SH NAME
\fBform_fieldtype\fR \- define validation-field types
@@ -56,7 +56,8 @@ FIELDTYPE *link_fieldtype(FIELDTYPE *type1,
.br
.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
+validation.
+You supply it with \fIfield_check\fR, a predicate to check the
validity of an entered data string whenever the user attempts to leave a field.
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
@@ -69,8 +70,8 @@ the character to be checked and a pointer to an argument-block structure.
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 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
@@ -124,7 +125,7 @@ The field is already connected to a form.
The field is the current field.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
.SH NOTES
@@ -135,8 +136,9 @@ 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.
.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.
diff --git a/man/form_hook.3x b/man/form_hook.3x
index 2943b8804993..803fadd83e57 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,7 +27,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_hook.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form_hook.3x,v 1.13 2019/01/20 20:31:42 tom Exp $
.TH form_hook 3X ""
.SH NAME
\fBform_hook\fR \- set hooks for automatic invocation by applications
@@ -55,40 +55,46 @@ 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
+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
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
+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
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
+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
+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
hook).
.SH RETURN VALUE
-Routines that return pointers return \fBNULL\fR on error. Other routines
+Routines that return pointers return \fBNULL\fR 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).
+System error occurred (see \fBerrno\fR(3)).
.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.
diff --git a/man/form_new.3x b/man/form_new.3x
index b69f642b0a91..373fec0e3a8e 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 (c) 1998-2015,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,10 +27,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_new.3x,v 1.9 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form_new.3x,v 1.11 2018/07/28 21:34:06 tom Exp $
.TH form_new 3X ""
.SH NAME
-\fBform_new\fR \- create and destroy forms
+\fBnew_form\fR,
+\fBfree_form\fP \- create and destroy forms
.SH SYNOPSIS
\fB#include <form.h>\fR
.br
@@ -76,8 +77,9 @@ The form has already been posted.
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.
diff --git a/man/form_new_page.3x b/man/form_new_page.3x
index 635822df2115..8c87e2b12edd 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,10 +27,15 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_new_page.3x,v 1.10 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form_new_page.3x,v 1.14 2019/11/30 21:06:30 tom Exp $
.TH form_new_page 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.SH NAME
-\fBform_new_page\fR \- form pagination functions
+\fBset_new_page\fR,
+\fBnew_page\fR \- form pagination functions
.SH SYNOPSIS
\fB#include <form.h>\fR
.br
@@ -47,25 +52,23 @@ a page beginning on its form.
.SH RETURN VALUE
The function \fBnew_page\fR returns \fBTRUE\fR or \fBFALSE\fR.
.PP
-The function \fBset_new_page\fR return one of the following:
+The function \fBset_new_page\fR 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
+\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.
diff --git a/man/form_opts.3x b/man/form_opts.3x
index f02cec6d93f3..ba4a6bd438ce 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,9 +27,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_opts.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form_opts.3x,v 1.14 2019/01/20 20:31:42 tom Exp $
.TH form_opts 3X ""
.SH NAME
+\fBset_form_opts\fP,
+\fBform_opts_on\fP,
+\fBform_opts_off\fP,
\fBform_opts\fR \- set and get form options
.SH SYNOPSIS
\fB#include <form.h>\fR
@@ -70,15 +73,16 @@ Except for \fBform_opts\fR, each routine returns one of the following:
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.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.
diff --git a/man/form_page.3x b/man/form_page.3x
index 2211216d8155..3e10402c5f87 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,7 +27,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_page.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form_page.3x,v 1.16 2019/01/20 20:31:42 tom Exp $
.TH form_page 3X ""
.SH NAME
\fBform_page\fR \- set and get form page number
@@ -38,6 +38,8 @@ int set_current_field(FORM *form, FIELD *field);
.br
FIELD *current_field(const FORM *);
.br
+int unfocus_current_field(FORM *form);
+.br
int set_form_page(FORM *form, int n);
.br
int form_page(const FORM *form);
@@ -45,16 +47,21 @@ int form_page(const FORM *form);
int field_index(const FIELD *field);
.br
.SH DESCRIPTION
-The function \fBset_current field\fR sets the current field of the given
+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.
.PP
+The function \fBunfocus_current_field\fR removes the focus from the current
+field of the form.
+In such state, inquiries via \fBcurrent_field\fR shall return a NULL pointer.
+.PP
The function \fBset_form_page\fR sets the form's page number (goes to page
\fIn\fR of the form).
.PP
The function \fBform_page\fR returns the form's current page number.
.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
+field array of the form it is connected to.
+It returns \fBERR\fR 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:
@@ -75,7 +82,7 @@ Contents of a field are not valid.
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\fR(3)).
.
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
@@ -83,8 +90,11 @@ System error occurred (see \fBerrno\fR).
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
+The \fBunfocus_current_field\fP function is an ncurses 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.
diff --git a/man/form_post.3x b/man/form_post.3x
index 4799d9d1d324..a255af41b3ce 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,10 +27,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_post.3x,v 1.9 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form_post.3x,v 1.13 2019/01/20 20:31:42 tom Exp $
.TH form_post 3X ""
.SH NAME
-\fBform_post\fR \- write or erase forms from associated subwindows
+\fBpost_form\fR,
+\fBunpost_form\fR \- write or erase forms from associated subwindows
.SH SYNOPSIS
\fB#include <form.h>\fR
.br
@@ -39,8 +40,9 @@ int post_form(FORM *form);
int unpost_form(FORM *form);
.br
.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
+The function \fBpost_form\fR displays a form to its associated subwindow.
+To trigger physical display of the subwindow,
+use \fBrefresh\fR(3X) or some equivalent
\fBcurses\fR routine (the implicit \fBdoupdate\fR triggered by an \fBcurses\fR
input request will do).
.PP
@@ -70,7 +72,7 @@ Form is too large for its window.
The form has already been posted.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
@@ -78,8 +80,9 @@ System error occurred (see \fBerrno\fR).
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.
diff --git a/man/form_requestname.3x b/man/form_requestname.3x
index 4a4e7eb033e3..4e8ada0f9150 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 (c) 1998-2015,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,10 +27,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_requestname.3x,v 1.9 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form_requestname.3x,v 1.11 2018/07/28 21:34:06 tom Exp $
.TH form_requestname 3X ""
.SH NAME
-\fBform_requestname\fR \- handle printable form request names
+\fBform_request_by_name\fP,
+\fBform_request_name\fR \- handle printable form request names
.SH SYNOPSIS
\fB#include <form.h>\fR
.br
@@ -43,7 +44,8 @@ The function \fBform_request_name\fR 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.
+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.
@@ -56,9 +58,11 @@ It does not set errno.
The header file \fB<form.h>\fR automatically includes the header file
\fB<curses.h>\fR.
.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 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 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.
diff --git a/man/form_userptr.3x b/man/form_userptr.3x
index bd29b542c85b..c450a26befbb 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 (c) 1998-2015,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,9 +27,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_userptr.3x,v 1.13 2010/12/04 18:40:45 tom Exp $
+.\" $Id: form_userptr.3x,v 1.15 2018/07/28 21:34:06 tom Exp $
.TH form_userptr 3X ""
.SH NAME
+\fBset_form_userptr\fP,
\fBform_userptr\fR \- associate application data with a form item
.SH SYNOPSIS
\fB#include <form.h>\fR
@@ -53,11 +54,12 @@ The function \fBset_form_userptr\fR returns \fBE_OK\fP (success).
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
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.
diff --git a/man/form_variables.3x b/man/form_variables.3x
index f4af349b1699..7760de2464b2 100644
--- a/man/form_variables.3x
+++ b/man/form_variables.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2010,2013 Free Software Foundation, Inc. *
+.\" Copyright (c) 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,9 +26,8 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_variables.3x,v 1.4 2013/06/22 17:58:32 tom Exp $
+.\" $Id: form_variables.3x,v 1.5 2017/11/20 00:59:21 tom Exp $
.TH form_variables 3X ""
-.ds n 5
.na
.hy 0
.SH NAME
diff --git a/man/form_win.3x b/man/form_win.3x
index 32af49b68040..ecd0a9303ffd 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,7 +27,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_win.3x,v 1.13 2010/12/04 18:38:55 tom Exp $
+.\" $Id: form_win.3x,v 1.15 2019/01/20 20:31:42 tom Exp $
.TH form_win 3X ""
.SH NAME
\fBform_win\fR \- make and break form window and subwindow associations
@@ -45,11 +45,13 @@ WINDOW *form_sub(const FORM *form);
int scale_form(const FORM *form, int *rows, int *columns);
.br
.SH DESCRIPTION
-Every form has an associated pair of \fBcurses\fR windows. The form window
+Every form has an associated pair of \fBcurses\fR 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
+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.
.PP
In the \fBset_\fR functions, window argument of \fBNULL\fR is treated as though
@@ -59,14 +61,15 @@ to change the system default form window or subwindow.
The function \fBscale_form\fR returns the minimum size required for the
subwindow of \fIform\fR.
.SH RETURN VALUE
-Routines that return pointers return \fBNULL\fR on error. Routines that return
+Routines that return pointers return \fBNULL\fR 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\fR(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
@@ -84,8 +87,9 @@ No items are connected to the form.
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.
diff --git a/man/infocmp.1m b/man/infocmp.1m
index 294abe3eb693..cfee79a553eb 100644
--- a/man/infocmp.1m
+++ b/man/infocmp.1m
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2012,2013 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,11 +27,30 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: infocmp.1m,v 1.53 2013/02/02 22:07:35 tom Exp $
+.\" $Id: infocmp.1m,v 1.75 2019/07/20 18:42:11 tom Exp $
.TH @INFOCMP@ 1M ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.ds n 5
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
+.de NS
+.ie n .sp
+.el .sp .5
+.ie n .in +4
+.el .in +2
+.nf
+.ft C \" Courier
+..
+.de NE
+.fi
+.ft R
+.ie n .in -4
+.el .in -2
..
.ds d @TERMINFO@
.SH NAME
@@ -50,6 +69,7 @@ L\
T\
U\
V\
+W\
c\
d\
e\
@@ -65,7 +85,7 @@ u\
x\
\fR]
.br
- [\fB\-v\fR \fIn\fR] [\fB\-s d\fR| \fBi\fR| \fBl\fR| \fBc\fR] [\fB\-R \fR\fBsubset\fR]
+ [\fB\-v\fR \fIn\fR] [\fB\-s d\fR| \fBi\fR| \fBl\fR| \fBc\fR] [\fB\-Q\fR \fIn\fR] [\fB\-R \fR\fBsubset\fR]
.br
[\fB\-w\fR\ \fIwidth\fR] [\fB\-A\fR\ \fIdirectory\fR] [\fB\-B\fR\ \fIdirectory\fR]
.br
@@ -88,30 +108,49 @@ the \fB\-d\fR option will be assumed.
\fItermname\fR with each of the descriptions given by the entries for the other
terminal's \fItermnames\fR.
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\fR for missing boolean variables
+.bP
+\fBNULL\fR for missing integer or string variables
.PP
-The \fB\-d\fR option produces a list of each capability that is different
-between two entries.
-This option is useful to show the difference between two
-entries, created by different people, for the same or similar terminals.
+Use the \fB\-q\fP option to show the distinction between
+\fIabsent\fP and \fIcancelled\fP capabilities.
.PP
-The \fB\-c\fR option produces a list of each capability that is common between
+These options produce a list which you can use to compare two
+or more terminal descriptions:
+.TP 5
+\fB\-d\fR
+produces a list of each capability that is \fIdifferent\fP
+between two entries.
+Each item in the list shows \*(``:\*('' after the capability name,
+followed by the capability values, separated by a comma.
+.TP
+\fB\-c\fR
+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.
-.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.
+Missing capabilities are ignored.
+Each item in the list shows \*(``=\*('' after the capability name,
+followed by the capability value.
+.IP
+The \fB\-u\fR 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\fR
+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 \fItermnames\fR are given,
+\fB@INFOCMP@\fR uses the environment variable \fBTERM\fR
+for each of the \fItermnames\fR.
.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.
+The \fB\-I\fR, \fB\-L\fR, and \fB\-C\fR options will produce
+a source listing for each terminal named.
.
.TS
center tab(/) ;
@@ -137,7 +176,7 @@ These should be edited by hand.
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.
@@ -147,7 +186,7 @@ and trim excess whitespace (use the \fB\-0\fP option for that).
All padding information for strings will be collected together and placed
at the beginning of the string where \fBtermcap\fR 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.
@@ -169,9 +208,9 @@ 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.
+A subsequent conversion of the \fBtermcap\fR file
+back into \fBterminfo\fR format
+will not necessarily reproduce the original \fBterminfo\fR source.
.PP
Some common \fBterminfo\fR parameter sequences, their \fBtermcap\fR
equivalents, and some terminal types which commonly have such sequences, are:
@@ -201,7 +240,8 @@ 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@\fR
+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
@@ -234,7 +274,7 @@ superfluous.
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.
+\fB@INFOCMP@\fP 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).
@@ -265,12 +305,13 @@ 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.
+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.
+tells \fB@INFOCMP@\fP to print the database locations that it knows about,
+and exit.
.TP 5
\fB\-E\fR
Dump the capabilities of the given terminal as tables, needed in
@@ -319,7 +360,11 @@ 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.
+(\fBrs1\fR, \fBrs2\fR, \fBrs3\fR), 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).
+.IP
For each string, the
code tries to analyze it into actions in terms of the other capabilities in the
entry, certain X3.64/ISO 6429/ECMA\-48 capabilities, and certain DEC VT-series
@@ -329,9 +374,9 @@ Each report line consists
of the capability name, followed by a colon and space, followed by a printable
expansion of the capability string with sections matching recognized actions
translated into {}-bracketed descriptions.
+.IP
Here is a list of the DEC/ANSI
special sequences recognized:
-i.
.TS
center tab(/) ;
l l
@@ -376,8 +421,14 @@ DEC[+\-]ARM/auto-repeat mode
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).
-.PP
+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
@@ -386,9 +437,40 @@ Set output format to terminfo.
\fB\-p\fR
Ignore padding specifications when comparing strings.
.TP 5
+\fB\-Q\fR \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
+.IP
+For example, this prints the compiled terminfo value as a string
+which could be assigned to the \fBTERMINFO\fP environment variable:
+.NS
+@INFOCMP@ -0 -q -Q2
+.NE
+.TP 5
\fB\-q\fR
+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".
+\*(``\-\*('' 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\fR\fIsubset\fR
Restrict output to a given subset.
@@ -396,11 +478,20 @@ This option is for use with archaic
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.
+.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\fR(\*n) for details.
+.bP
+You can also choose the subset \*(``BSD\*('' which selects only capabilities
with termcap equivalents recognized by 4.4BSD.
+The \fB\-C\fP option sets the \*(``BSD\*('' subset as a side-effect.
+.bP
+If you select any other value for \fB\-R\fP,
+it is the same as no subset, i.e., all capabilities are used.
+The \fB\-I\fP option likewise selects no subset as a side-effect.
+.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
@@ -438,7 +529,8 @@ 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.
+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.
@@ -448,19 +540,54 @@ reports the version of ncurses which was used in this program, and exits.
.TP 5
\fB\-v\fR \fIn\fR
prints out tracing information on standard error as the program runs.
-Higher values of n induce greater verbosity.
+.IP
+The optional parameter \fIn\fR is a number from 1 to 10, inclusive,
+indicating the desired level of detail of information.
+If ncurses is built without tracing support, the optional parameter is ignored.
+.TP
+\fB\-W\fR
+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\fR \fIwidth\fR
changes the output to \fIwidth\fR characters.
.TP
\fB\-x\fR
-print information for user-defined capabilities.
+print information for user-defined capabilities (see \fBuser_caps(\*n)\fP.
These are extensions to the terminfo repertoire which can be loaded
using the \fB\-x\fR option of \fB@TIC@\fP.
.SH FILES
.TP 20
\*d
Compiled terminal description database.
+.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
+Eric Raymond used the AT&T documentation in 1995 to provide an equivalent
+\fB@INFOCMP@\fP for ncurses.
+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 ncurses versions
+(e.g., it lacks the sorting options documented in X/Open),
+but does include the \fB\-x\fP option adapted from ncurses.
+.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 EXTENSIONS
The
\fB\-0\fR,
@@ -468,6 +595,7 @@ The
\fB\-E\fR,
\fB\-F\fR,
\fB\-G\fR,
+\fB\-Q\fR,
\fB\-R\fR,
\fB\-T\fR,
\fB\-V\fR,
@@ -482,7 +610,14 @@ The
\fB\-t\fR
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\fR 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.
@@ -495,8 +630,9 @@ The \fB\-F\fR option of \fB@INFOCMP@\fR(1M) should be a \fB@TOE@\fR(1M) mode.
\fB@TOE@\fR(1M),
\fBcurses\fR(3X),
\fBterminfo\fR(\*n).
+\fBuser_caps\fR(\*n).
.sp
-http://invisible-island.net/ncurses/tctest.html
+https://invisible-island.net/ncurses/tctest.html
.PP
This describes \fBncurses\fR
version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
diff --git a/man/infotocap.1m b/man/infotocap.1m
index d9b44f0e25b9..2297e3132cd8 100644
--- a/man/infotocap.1m
+++ b/man/infotocap.1m
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1999-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1999-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,14 +27,14 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: infotocap.1m,v 1.11 2010/12/04 18:38:55 tom Exp $
+.\" $Id: infotocap.1m,v 1.15 2019/10/12 21:16:00 tom Exp $
.TH @INFOTOCAP@ 1M ""
.ds n 5
.ds d @TERMINFO@
.SH NAME
\fB@INFOTOCAP@\fR \- convert a \fIterminfo\fR description into a \fItermcap\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 . . .
+\fB@INFOTOCAP@\fR [\fB\-v\fR\fIn\fR \fIwidth\fR] [\fB\-V\fR] [\fB\-1\fR] [\fB\-w\fR \fIwidth\fR] \fIfile\fR ...
.SH DESCRIPTION
\fB@INFOTOCAP@\fR looks in each given text
\fIfile\fR for \fBterminfo\fR descriptions.
@@ -61,8 +61,10 @@ change the output to \fIwidth\fR characters.
\*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.
+This utility is actually a link to \fB@TIC@\fR, running in \fI\-C\fR mode.
+You can use other \fB@TIC@\fR options such as \fB\-f\fR and \fB\-x\fR.
+.SH PORTABILITY
+None of X/Open Curses, Issue 7 (2009), SVr4 or NetBSD document this application.
.SH SEE ALSO
\fBcurses\fR(3X),
\fB@TIC@\fR(1M),
diff --git a/man/key_defined.3x b/man/key_defined.3x
index db6c531af0e3..d78b6ffc28a1 100644
--- a/man/key_defined.3x
+++ b/man/key_defined.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2003-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 2003-2010,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 *
@@ -28,7 +28,7 @@
.\"
.\" Author: Thomas E. Dickey 2003
.\"
-.\" $Id: key_defined.3x,v 1.6 2010/12/04 18:40:45 tom Exp $
+.\" $Id: key_defined.3x,v 1.8 2018/07/28 22:08:59 tom Exp $
.TH key_defined 3X ""
.SH NAME
\fBkey_defined\fP \- check if a keycode is defined
@@ -43,10 +43,13 @@ 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
+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
\fBdefine_key\fR(3X).
diff --git a/man/keybound.3x b/man/keybound.3x
index 5dd083afe1ab..ec90c453b199 100644
--- a/man/keybound.3x
+++ b/man/keybound.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1999-2008,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1999-2010,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 *
@@ -28,7 +28,7 @@
.\"
.\" Author: Thomas E. Dickey 1999
.\"
-.\" $Id: keybound.3x,v 1.8 2010/12/04 18:49:20 tom Exp $
+.\" $Id: keybound.3x,v 1.9 2018/07/28 21:34:06 tom Exp $
.TH keybound 3X ""
.SH NAME
\fBkeybound\fP \- return definition of keycode
@@ -48,8 +48,10 @@ 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
+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
\fBdefine_key\fR(3X),
diff --git a/man/keyok.3x b/man/keyok.3x
index 8eaf9a3c99cf..d181c1059bd2 100644
--- a/man/keyok.3x
+++ b/man/keyok.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 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 *
@@ -28,7 +28,7 @@
.\"
.\" Author: Thomas E. Dickey 1997
.\"
-.\" $Id: keyok.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
+.\" $Id: keyok.3x,v 1.13 2018/07/28 21:34:56 tom Exp $
.TH keyok 3X ""
.SH NAME
\fBkeyok\fP \- enable or disable a keycode
@@ -42,14 +42,16 @@ It permits an application to disable specific keycodes, rather than
use the \fIkeypad\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
+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
\fBdefine_key\fR(3X).
diff --git a/man/legacy_coding.3x b/man/legacy_coding.3x
index fabb607a572e..b3d7b41e7526 100644
--- a/man/legacy_coding.3x
+++ b/man/legacy_coding.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2005-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 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,18 +28,16 @@
.\"
.\" Author: Thomas E. Dickey
.\"
-.\" $Id: legacy_coding.3x,v 1.4 2010/12/04 18:49:20 tom Exp $
+.\" $Id: legacy_coding.3x,v 1.6 2017/03/15 08:14:25 tom Exp $
.TH legacy_coding 3X ""
.SH NAME
-\fBuse_legacy_coding\fR \- use terminal's default colors
+\fBuse_legacy_coding\fR \- override 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.
+The \fBuse_legacy_coding\fP 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.
diff --git a/man/make_sed.sh b/man/make_sed.sh
index f2afac93ebc8..55ba32f528c6 100755
--- a/man/make_sed.sh
+++ b/man/make_sed.sh
@@ -1,7 +1,7 @@
#!/bin/sh
-# $Id: make_sed.sh,v 1.9 2005/07/16 18:15:31 tom Exp $
+# $Id: make_sed.sh,v 1.10 2017/08/12 12:22:06 tom Exp $
##############################################################################
-# Copyright (c) 1998-2003,2005 Free Software Foundation, Inc. #
+# Copyright (c) 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"), #
@@ -45,7 +45,7 @@ UPPER=upper$$
SCRIPT=script$$
RESULT=result$$
rm -f $UPPER $SCRIPT $RESULT
-trap "rm -f $COL.* $INPUT $UPPER $SCRIPT $RESULT" 0 1 2 5 15
+trap "rm -f $COL.* $INPUT $UPPER $SCRIPT $RESULT" 0 1 2 3 15
fgrep -v \# $1 | \
sed -e 's/[ ][ ]*/ /g' >$INPUT
diff --git a/man/man_db.renames b/man/man_db.renames
index e98fd69d6251..8299df89020b 100644
--- a/man/man_db.renames
+++ b/man/man_db.renames
@@ -1,5 +1,5 @@
##############################################################################
-# Copyright (c) 1998-2009,2010 Free Software Foundation, Inc. #
+# Copyright (c) 1998-2017,2019 Free Software Foundation, Inc. #
# #
# Permission is hereby granted, free of charge, to any person obtaining a #
# copy of this software and associated documentation files (the "Software"), #
@@ -25,7 +25,7 @@
# use or other dealings in this Software without prior written #
# authorization. #
##############################################################################
-# $Id: man_db.renames,v 1.47 2010/09/18 15:43:20 tom Exp $
+# $Id: man_db.renames,v 1.55 2019/07/20 10:18:12 Sven.Joachim Exp $
# Manual-page renamings for the man_db program
#
# Files:
@@ -149,11 +149,13 @@ mitem_userptr.3x menu_userptr.3menu
mitem_value.3x menu_value.3menu
mitem_visible.3x menu_visible.3menu
ncurses.3x ncurses.3ncurses
+new_pair.3x new_pair.3ncurses
panel.3x panel.3curses
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
@@ -165,7 +167,7 @@ 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:
@@ -174,20 +176,24 @@ tack.1m tack.1
getty.1 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
#
-# Generated:
+# 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
-ncurseswt6-config.1 ncurseswt6-config.1
+ncursestw6-config.1 ncursestw6-config.1
#
# vile:cfgmode
diff --git a/man/manhtml.aliases b/man/manhtml.aliases
index a4ae047a14c6..6db78f3a14a2 100644
--- a/man/manhtml.aliases
+++ b/man/manhtml.aliases
@@ -1,16 +1,62 @@
-# $Id: manhtml.aliases,v 1.1 2013/12/21 21:44:52 tom Exp $
+# $Id: manhtml.aliases,v 1.13 2019/02/16 23:44:49 tom Exp $
+#***************************************************************************
+# Copyright (c) 2013-2017,2019 Free Software Foundation, Inc. *
+# *
+# Permission is hereby granted, free of charge, to any person obtaining a *
+# copy of this software and associated documentation files (the *
+# "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
+assume_default_colors(3X) default_colors(3X)
addch(3X) curs_addch(3X)
+curs_set(3X) curs_kernel(3X)
delscreen(3X) curs_initscr(3X)
+doupdate(3X) curs_refresh(3X)
+endwin(3X) curs_initscr(3X)
filter(3X) curs_util(3X)
-form_fieldtype(3X) form_fieldtype(3X)
+get_wch(3X) curs_get_wch(3X)
getch(3X) curs_getch(3X)
+inch(3X) curs_inch(3X)
infocmp(1) infocmp(1M)
initscr(3X) curs_initscr(3X)
+is_scrollok(3X) curs_opaque(3X)
+keypad(3X) curs_inopts(3X)
+longname(3X) curs_termattrs(3X)
+meta(3X) curs_inopts(3X)
+mvcur(3X) curs_terminfo(3X)
newterm(3X) curs_initscr(3X)
+refresh(3X) curs_refresh(3X)
+reset_shell_mode(3X) curs_kernel(3X)
set_fieldtype(3X) form_fieldtype(3X)
set_term(3X) curs_initscr(3X)
setupterm(3X) curs_terminfo(3X)
+slk_init(3X) curs_slk(3X)
tic(1) tic(1M)
+tigetstr(3X) curs_terminfo(3X)
+tparm(3X) curs_terminfo(3X)
+tputs(3X) curs_terminfo(3X)
use_env(3X) curs_util(3X)
+use_default_colors(3X) default_colors(3X)
+use_extended_names(3X) curs_extend(3X)
vidputs(3X) curs_terminfo(3X)
+wgetch(3X) curs_getch(3X)
diff --git a/man/manhtml.externs b/man/manhtml.externs
index d26b6127a445..8c302540dccf 100644
--- a/man/manhtml.externs
+++ b/man/manhtml.externs
@@ -1,24 +1,64 @@
-# $Id: manhtml.externs,v 1.3 2013/12/21 22:11:29 tom Exp $
+# $Id: manhtml.externs,v 1.12 2019/07/27 11:30:24 tom Exp $
# Items in this list will not be linked by man2html
+#***************************************************************************
+# Copyright (c) 2013-2017,2019 Free Software Foundation, Inc. *
+# *
+# Permission is hereby granted, free of charge, to any person obtaining a *
+# copy of this software and associated documentation files (the *
+# "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. *
+#***************************************************************************
+ADACURSES(1)
+COLOR_PAIR(1)
+COLOR_PAIR(2)
+COLOR_PAIR(3)
+atoi(3)
conflict(1)
csh(1)
ded(1)
environ(7)
+errno(3)
+file(1)
getty(1)
+lynx(1)
nvi(1)
+mutt(1)
+od(1)
printf(3)
profile(5)
putc(3)
+putchar(3)
putwc(3)
read(2)
-rogue(1)
scanf(3)
sh(1)
sscanf(3)
stdio(3)
stty(1)
system(3)
-termio(7)
+termios(3)
tty(4)
ttys(5)
+vprintf(3)
+vscanf(3)
wcwidth(3)
+write(2)
diff --git a/man/menu.3x b/man/menu.3x
index ff3a19c04333..2c2b7efa5936 100644
--- a/man/menu.3x
+++ b/man/menu.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,8 +27,16 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu.3x,v 1.21 2010/12/04 18:40:45 tom Exp $
+.\" $Id: menu.3x,v 1.26 2019/01/20 20:32:23 tom Exp $
.TH menu 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
\fBmenu\fR \- curses extension for programming menus
.SH SYNOPSIS
@@ -36,20 +44,24 @@
.br
.SH DESCRIPTION
The \fBmenu\fR library provides terminal-independent facilities for composing
-menu systems on character-cell terminals. The library includes: item routines,
+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
+these functions.
+To use the \fBmenu\fR library, link with the options
\fB\-lmenu \-lcurses\fR.
.
.SS Current Default Values for Item Attributes
.
-The \fBmenu\fR library maintains a default value for item attributes. You can
+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
+routine with a \fBNULL\fR item pointer.
+Changing this default with a
\fBset_\fR function affects future item creations, but does not change the
rendering of items already created.
.
@@ -128,7 +140,8 @@ top_row \fBmitem_current\fR(3X)
unpost_menu \fBmenu_post\fR(3X)
.TE
.SH RETURN VALUE
-Routines that return pointers return \fBNULL\fR on error. Routines that return
+Routines that return pointers return \fBNULL\fR on error.
+Routines that return
an integer return one of the following error codes:
.TP 5
.B E_OK
@@ -162,26 +175,38 @@ The menu is already posted.
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\fR(3)).
.TP 5
.B E_UNKNOWN_COMMAND
The menu driver code saw an unknown request code.
-.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 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).
+you should say \*(``\-lmenu \-lncurses\*('', not the other way around
+(which would give a link-error when using static libraries).
.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 menu facility was documented in SVr4.2 in
+\fICharacter User Interface Programming (UNIX SVR4.2)\fP.
+.PP
+It is not part of X/Open Curses.
+.PP
+Aside from ncurses, 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 ncurses by Eric
-S. Raymond.
+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@).
diff --git a/man/menu_attributes.3x b/man/menu_attributes.3x
index c33059b9948f..3ba1b87ad310 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,10 +27,21 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_attributes.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
+.\" $Id: menu_attributes.3x,v 1.16 2019/11/30 21:02:51 tom Exp $
.TH menu_attributes 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.SH NAME
-\fBmenu_attributes\fR \- color and attribute control for menus
+\fBmenu_back\fR,
+\fBmenu_fore\fR,
+\fBmenu_grey\fR,
+\fBmenu_pad\fR,
+\fBset_menu_back\fR,
+\fBset_menu_fore\fR,
+\fBset_menu_grey\fR,
+\fBset_menu_pad\fR \- color and attribute control for menus
.SH SYNOPSIS
\fB#include <menu.h>\fR
.br
@@ -53,22 +64,28 @@ int menu_pad(const MENU *menu);
.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
+\fBmenu_fore\fR returns the foreground attribute.
+The default
is \fBA_REVERSE\fR.
.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.
+selected) menu items.
+The function \fBmenu_back\fR returns the background
+attribute.
+The default is \fBA_NORMAL\fR.
.PP
The function \fBset_menu_grey\fR sets the grey attribute of \fImenu\fR. 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.
+one selection.
+The function \fBmenu_grey\fR returns the grey attribute.
The default is \fBA_UNDERLINE\fR.
.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.
+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.
.SH RETURN VALUE
These routines return one of the following:
.TP 5
@@ -76,19 +93,20 @@ These routines return one of the following:
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(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
+\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.
diff --git a/man/menu_cursor.3x b/man/menu_cursor.3x
index 66a835be58c8..52f46af08b2d 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,10 +27,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_cursor.3x,v 1.8 2010/12/04 18:40:45 tom Exp $
+.\" $Id: menu_cursor.3x,v 1.11 2019/01/20 20:32:23 tom Exp $
.TH menu_cursor 3X ""
.SH NAME
-\fBmenu_cursor\fR \- position a menu's cursor
+\fBpos_menu_cursor\fR \- position a menu's cursor
.SH SYNOPSIS
\fB#include <menu.h>\fR
.br
@@ -38,7 +38,8 @@ int pos_menu_cursor(const MENU *menu);
.br
.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
+associated with the menu's selected item.
+This is useful after \fBcurses\fR
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,7 +48,7 @@ This routine returns one of the following:
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
@@ -60,8 +61,9 @@ The menu has not been posted.
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.
diff --git a/man/menu_driver.3x b/man/menu_driver.3x
index 1fe5001fec05..086381f34be1 100644
--- a/man/menu_driver.3x
+++ b/man/menu_driver.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2008,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,10 +26,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_driver.3x,v 1.20 2010/12/04 18:38:55 tom Exp $
+.\" $Id: menu_driver.3x,v 1.25 2019/01/20 20:32:23 tom Exp $
.TH menu_driver 3X ""
.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
@@ -44,7 +45,8 @@ through \fBmenu_driver\fR. 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,7 +109,8 @@ Move to the previous item matching the pattern match.
.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
+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.
.PP
If the second argument is one of the above pre-defined requests, the
@@ -150,12 +153,14 @@ application specific command should be executed.
If a translation
into a request was done, \fBmenu_driver\fR returns the result of this request.
.PP
-If you clicked outside the user window or the mouse event could not be translated
+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 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
+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 requests.
@@ -166,7 +171,7 @@ pre-defined requests.
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
@@ -193,8 +198,10 @@ The menu driver could not process the request.
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 ncurses 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.
diff --git a/man/menu_format.3x b/man/menu_format.3x
index b9a572b01774..b3385e8f49ad 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,10 +27,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_format.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
+.\" $Id: menu_format.3x,v 1.16 2019/01/20 20:32:23 tom Exp $
.TH menu_format 3X ""
.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
@@ -40,12 +41,16 @@ 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.
+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.
.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
+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
value.
.PP
@@ -58,7 +63,7 @@ These routines returns one of the following:
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
@@ -74,8 +79,9 @@ No items are connected to the menu.
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.
diff --git a/man/menu_hook.3x b/man/menu_hook.3x
index 1fd74de77935..41d1c74aefa4 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,7 +27,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_hook.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
+.\" $Id: menu_hook.3x,v 1.13 2019/01/20 20:32:23 tom Exp $
.TH menu_hook 3X ""
.SH NAME
\fBmenu_hook\fR \- set hooks for automatic invocation by applications
@@ -55,17 +55,20 @@ 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.
.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
+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
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
+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
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
+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
hook).
.PP
@@ -74,22 +77,25 @@ 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
is no such hook).
.SH RETURN VALUE
-Routines that return pointers return \fBNULL\fR on error. Other routines
+Routines that return pointers return \fBNULL\fR 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).
+System error occurred (see \fBerrno\fR(3)).
.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
+Juergen Pfeifer.
+Manual pages and adaptation for new curses by Eric
S. Raymond.
diff --git a/man/menu_items.3x b/man/menu_items.3x
index 04b00ad76772..27f203c7f970 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,10 +27,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_items.3x,v 1.10 2012/11/03 23:03:59 tom Exp $
+.\" $Id: menu_items.3x,v 1.13 2019/01/20 20:32:23 tom Exp $
.TH menu_items 3X ""
.SH NAME
-\fBmenu_items\fR \- make and break connections between items and menus
+\fBset_menu_items\fR,
+\fBmenu_items\fR,
+\fBitem_count\fP \- make and break connections between items and menus
.SH SYNOPSIS
\fB#include <menu.h>\fR
.br
@@ -69,7 +71,7 @@ No items are connected to the menu.
The menu is already posted.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
@@ -77,11 +79,12 @@ System error occurred (see \fBerrno\fR).
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 SVr4 menu library documentation specifies the \fBitem_count\fR error value
as \-1 (which is the value of \fBERR\fR).
.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.
diff --git a/man/menu_mark.3x b/man/menu_mark.3x
index 1425154b8dc4..64e73d0b601a 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,9 +27,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_mark.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
+.\" $Id: menu_mark.3x,v 1.14 2019/01/20 20:32:23 tom Exp $
.TH menu_mark 3X ""
.SH NAME
+\fBset_menu_mark\fP,
\fBmenu_mark\fR \- get and set the menu mark string
.SH SYNOPSIS
\fB#include <menu.h>\fR
@@ -48,7 +49,8 @@ Calling \fBset_menu_mark\fR 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
+The default string is "\-" (a dash).
+Calling \fBset_menu_mark\fR with
a non-\fBNULL\fR menu argument will change this default.
.PP
The function \fBmenu_mark\fR returns the menu's mark string (or \fBNULL\fR if
@@ -66,15 +68,16 @@ The routine succeeded.
Routine detected an incorrect or out-of-range argument.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.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.
diff --git a/man/menu_new.3x b/man/menu_new.3x
index 11976547fc75..9fbab3412f58 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,10 +27,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_new.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
+.\" $Id: menu_new.3x,v 1.14 2019/01/20 20:32:23 tom Exp $
.TH menu_new 3X ""
.SH NAME
-\fBmenu_new\fR \- create and destroy menus
+\fBnew_menu\fP,
+\fBfree_menu\fR \- create and destroy menus
.SH SYNOPSIS
\fB#include <menu.h>\fR
.br
@@ -60,7 +61,7 @@ The function \fBfree_menu\fR returns one of the following:
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
@@ -73,8 +74,9 @@ The menu has already been posted.
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.
diff --git a/man/menu_opts.3x b/man/menu_opts.3x
index 5f4cb0806b3e..fec6eab7c2ca 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,9 +27,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_opts.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
+.\" $Id: menu_opts.3x,v 1.16 2019/01/20 20:32:23 tom Exp $
.TH menu_opts 3X ""
.SH NAME
+\fBset_menu_opts\fP,
+\fBmenu_opts_on\fP,
+\fBmenu_opts_off\fP,
\fBmenu_opts\fR \- set and get menu options
.SH SYNOPSIS
\fB#include <menu.h>\fR
@@ -74,6 +77,12 @@ Move the cursor to within the item name while pattern-matching.
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:
.TP 5
@@ -81,7 +90,7 @@ Except for \fBmenu_opts\fR, each routine returns one of the following:
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.TP 5
.B E_POSTED
The menu is already posted.
@@ -91,8 +100,9 @@ The menu is already posted.
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.
diff --git a/man/menu_pattern.3x b/man/menu_pattern.3x
index e63a9f73d84c..1905fe1adcc8 100644
--- a/man/menu_pattern.3x
+++ b/man/menu_pattern.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2008,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,10 +26,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_pattern.3x,v 1.13 2010/12/04 18:40:45 tom Exp $
+.\" $Id: menu_pattern.3x,v 1.17 2019/01/20 20:32:23 tom Exp $
.TH menu_pattern 3X ""
.SH NAME
-\fBmenu_pattern\fR \- get and set a menu's pattern buffer
+\fBset_menu_pattern\fP,
+\fBmenu_pattern\fR \- set and get a menu's pattern buffer
.SH SYNOPSIS
\fB#include <menu.h>\fR
.br
@@ -38,19 +39,23 @@ int set_menu_pattern(MENU *menu, const char *pattern);
char *menu_pattern(const MENU *menu);
.br
.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).
.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.
+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.
.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.
+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.
.PP
The function \fBset_menu_pattern\fR may return the following error codes:
@@ -71,15 +76,16 @@ No items are connected to menu.
Character failed to match.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.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.
diff --git a/man/menu_post.3x b/man/menu_post.3x
index d09d0ca4fe88..f2c46344cd3a 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,10 +27,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_post.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
+.\" $Id: menu_post.3x,v 1.17 2019/01/20 20:32:23 tom Exp $
.TH menu_post 3X ""
.SH NAME
-\fBmenu_post\fR \- write or erase menus from associated subwindows
+\fBpost_menu\fR,
+\fBunpost_menu\fR \- write or erase menus from associated subwindows
.SH SYNOPSIS
\fB#include <menu.h>\fR
.br
@@ -39,10 +40,13 @@ int post_menu(MENU *menu);
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
+The function \fBpost_menu\fR displays a menu to its associated subwindow.
+To
+trigger physical display of the subwindow,
+use \fBrefresh\fR(3X) 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.
+input request will do).
+\fBpost_menu\fR resets the selection status of all items.
.PP
The function \fBunpost_menu\fR erases menu from its associated subwindow.
.SH RETURN VALUE
@@ -52,7 +56,7 @@ These routines return one of the following:
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
@@ -64,8 +68,8 @@ The menu has already been posted.
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\fR to solve the problem.
.TP 5
.B E_NOT_POSTED
The menu has not been posted.
@@ -78,8 +82,9 @@ No items are connected to the menu.
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.
diff --git a/man/menu_requestname.3x b/man/menu_requestname.3x
index d1957a2f1cd5..cc2d4c9ed59e 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 (c) 1998-2015,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,10 +27,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_requestname.3x,v 1.9 2010/12/04 18:40:45 tom Exp $
+.\" $Id: menu_requestname.3x,v 1.11 2018/07/28 21:34:06 tom Exp $
.TH menu_requestname 3X ""
.SH NAME
-\fBmenu_requestname\fR \- handle printable menu request names
+\fBmenu_request_by_name\fP,
+\fBmenu_request_name\fR \- handle printable menu request names
.SH SYNOPSIS
\fB#include <menu.h>\fR
.br
@@ -57,9 +58,11 @@ It does not set errno.
The header file \fB<menu.h>\fR automatically includes the header file
\fB<curses.h>\fR.
.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 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 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.
diff --git a/man/menu_spacing.3x b/man/menu_spacing.3x
index 9e7c3eabfe92..b3038d5d734d 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,10 +27,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_spacing.3x,v 1.12 2010/12/04 18:38:55 tom Exp $
+.\" $Id: menu_spacing.3x,v 1.15 2019/06/01 22:33:45 tom Exp $
.TH menu_spacing 3X ""
.SH NAME
-\fBmenu_spacing\fR \- Control spacing between menu items.
+\fBset_menu_spacing\fP,
+\fBmenu_spacing\fR \- set and get spacing between menu items.
.SH SYNOPSIS
\fB#include <menu.h>\fR
.br
@@ -46,21 +47,23 @@ int menu_spacing(const MENU *menu,
.br
.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.
+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 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.
+The \fBspc_rows\fR parameter 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.
+The \fBspc_columns\fR parameter 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.
.br
The function \fBmenu_spacing\fR passes back the spacing info for the menu.
If a
diff --git a/man/menu_userptr.3x b/man/menu_userptr.3x
index 0455fe3a0380..eb8ef99f17ca 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 (c) 1998-2015,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,9 +27,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_userptr.3x,v 1.10 2010/12/04 18:40:45 tom Exp $
+.\" $Id: menu_userptr.3x,v 1.12 2018/07/28 21:34:06 tom Exp $
.TH menu_userptr 3X ""
.SH NAME
+\fBset_menu_userptr\fP,
\fBmenu_userptr\fR \- associate application data with a menu item
.SH SYNOPSIS
\fB#include <menu.h>\fR
@@ -53,11 +54,12 @@ It does not set errno.
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.
diff --git a/man/menu_win.3x b/man/menu_win.3x
index 774eafa9fdf5..be1db5738b91 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,7 +27,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_win.3x,v 1.11 2010/12/04 18:38:55 tom Exp $
+.\" $Id: menu_win.3x,v 1.13 2019/01/20 20:32:23 tom Exp $
.TH menu_win 3X ""
.SH NAME
\fBmenu_win\fR \- make and break menu window and subwindow associations
@@ -45,11 +45,13 @@ WINDOW *menu_sub(const MENU *menu);
int scale_menu(const MENU *menu, int *rows, int *columns);
.br
.SH DESCRIPTION
-Every menu has an associated pair of \fBcurses\fR windows. The menu window
+Every menu has an associated pair of \fBcurses\fR 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
+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.
.PP
In the \fBset_\fR functions, window argument of \fBNULL\fR is treated as though
@@ -59,14 +61,15 @@ to change the system default menu window or subwindow.
The function \fBscale_menu\fR returns the minimum size required for the
subwindow of \fImenu\fR.
.SH RETURN VALUE
-Routines that return pointers return \fBNULL\fR on error. Routines that return
+Routines that return pointers return \fBNULL\fR 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\fR(3)).
.TP 5
.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
@@ -84,8 +87,9 @@ No items are connected to the menu.
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.
diff --git a/man/mitem_current.3x b/man/mitem_current.3x
index 86c9b4775eaa..00a876ab71cc 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,14 +27,14 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: mitem_current.3x,v 1.13 2010/12/04 18:40:45 tom Exp $
+.\" $Id: mitem_current.3x,v 1.16 2019/03/23 21:47:36 tom Exp $
.TH mitem_current 3X ""
.SH NAME
\fBmitem_current\fR \- set and get current_menu_item
.SH SYNOPSIS
\fB#include <menu.h>\fR
.br
-int set_current_item(MENU *menu, const ITEM *item);
+int set_current_item(MENU *menu, ITEM *item);
.br
ITEM *current_item(const MENU *menu);
.br
@@ -46,13 +46,16 @@ int item_index(const ITEM *item);
.br
.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 menu cursor is positioned).
+\fBcurrent_item\fR 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
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\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
row being displayed.
.PP
The function \fBitem_index\fR returns the (zero-origin) index of \fIitem\fR in
@@ -79,18 +82,19 @@ Routine was called from an initialization or termination function.
No items are connected to the menu.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.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 SVr4 menu library documentation specifies the \fBtop_row\fR and
\fBindex_item\fR error value as \-1 (which is the value of \fBERR\fR).
.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.
diff --git a/man/mitem_name.3x b/man/mitem_name.3x
index ff879e669776..1ea46b236a6b 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 (c) 1998-2015,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,10 +27,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: mitem_name.3x,v 1.8 2010/12/04 18:40:45 tom Exp $
+.\" $Id: mitem_name.3x,v 1.10 2018/07/28 21:34:06 tom Exp $
.TH mitem_name 3X ""
.SH NAME
-\fBmitem_name\fR \- get menu item name and description fields
+\fBitem_name\fR,
+\fBitem_description\fR \- get menu item name and description fields
.SH SYNOPSIS
\fB#include <menu.h>\fR
.br
@@ -55,5 +56,5 @@ The header file \fB<menu.h>\fR automatically includes the header file
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.
diff --git a/man/mitem_new.3x b/man/mitem_new.3x
index 8e2449e2e208..1e6fd0d872ea 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,10 +27,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: mitem_new.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
+.\" $Id: mitem_new.3x,v 1.15 2019/01/20 20:32:23 tom Exp $
.TH mitem_new 3X ""
.SH NAME
-\fBmitem_new\fR \- create and destroy menu items
+\fBnew_item\fP,
+\fBfree_item\fR \- create and destroy menu items
.SH SYNOPSIS
\fB#include <menu.h>\fR
.br
@@ -40,12 +41,16 @@ int free_item(ITEM *item);
.br
.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
+\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
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\fR 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
@@ -70,15 +75,16 @@ Routine detected an incorrect or out-of-range argument.
Item is connected to a menu.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.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.
diff --git a/man/mitem_opts.3x b/man/mitem_opts.3x
index 37ea552328f6..b7aaff69af1c 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 (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,10 +27,13 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: mitem_opts.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
+.\" $Id: mitem_opts.3x,v 1.14 2019/01/20 20:32:23 tom Exp $
.TH mitem_opts 3X ""
.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\fR \- set and get menu item options
.SH SYNOPSIS
\fB#include <menu.h>\fR
.br
@@ -55,7 +58,8 @@ others alone.
The function \fBitem_opts\fR 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
+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:
@@ -64,15 +68,16 @@ Except for \fBitem_opts\fR, each routine returns one of the following:
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.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.
diff --git a/man/mitem_userptr.3x b/man/mitem_userptr.3x
index 7b51ec50a655..0ddf40de8cf1 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 (c) 1998-2015,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,10 +27,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: mitem_userptr.3x,v 1.11 2010/12/04 18:40:45 tom Exp $
+.\" $Id: mitem_userptr.3x,v 1.13 2018/07/28 21:34:06 tom Exp $
.TH mitem_userptr 3X ""
.SH NAME
-\fBmitem_userptr\fR \- associate application data with a menu item
+\fBset_item_userptr\fP,
+\fBitem_userptr\fR \- associate application data with a menu item
.SH SYNOPSIS
\fB#include <menu.h>\fR
.br
@@ -40,7 +41,8 @@ void *item_userptr(const ITEM *item);
.br
.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).
@@ -54,11 +56,12 @@ The \fBset_item_userptr\fP always returns \fBE_OK\fP (success).
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.
diff --git a/man/mitem_value.3x b/man/mitem_value.3x
index 57cfc536750f..061a57411ba6 100644
--- a/man/mitem_value.3x
+++ b/man/mitem_value.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,10 +26,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: mitem_value.3x,v 1.10 2010/12/04 18:40:45 tom Exp $
+.\" $Id: mitem_value.3x,v 1.13 2019/01/20 20:32:23 tom Exp $
.TH mitem_value 3X ""
.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
@@ -53,7 +54,7 @@ The function \fBset_item_value\fR returns one of the following:
The routine succeeded.
.TP 5
.B E_SYSTEM_ERROR
-System error occurred (see \fBerrno\fR).
+System error occurred (see \fBerrno\fR(3)).
.TP 5
.B E_REQUEST_DENIED
The menu driver could not process the request.
@@ -63,8 +64,9 @@ The menu driver could not process the request.
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.
diff --git a/man/mitem_visible.3x b/man/mitem_visible.3x
index 4ff9405483c9..ab53c7ec1445 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 (c) 1998-2010,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,7 +27,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: mitem_visible.3x,v 1.7 2010/12/04 18:40:45 tom Exp $
+.\" $Id: mitem_visible.3x,v 1.8 2018/07/28 21:34:06 tom Exp $
.TH mitem_visible 3X ""
.SH NAME
\fBmitem_visible\fR \- check visibility of a menu item
@@ -46,8 +46,9 @@ portion will be smaller than the whole menu).
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.
diff --git a/man/ncurses.3x b/man/ncurses.3x
index 6a5aa7c0c2fe..289f47c7b6d3 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2012,2013 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,7 +27,7 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: ncurses.3x,v 1.112 2013/07/20 19:29:59 tom Exp $
+.\" $Id: ncurses.3x,v 1.143 2019/11/30 20:47:07 tom Exp $
.hy 0
.TH ncurses 3X ""
.ie \n(.g .ds `` \(lq
@@ -35,7 +35,22 @@
.ie \n(.g .ds '' \(rq
.el .ds '' ''
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
+.de NS
+.ie n .sp
+.el .sp .5
+.ie n .in +4
+.el .in +2
+.nf
+.ft C \" Courier
+..
+.de NE
+.fi
+.ft R
+.ie n .in -4
+.el .in -2
..
.ds n 5
.ds d @TERMINFO@
@@ -82,12 +97,14 @@ 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
.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
+.NS
+\fBsetlocale(LC_ALL, "");\fP
+.NE
+.PP
If the locale is not initialized,
the library assumes that characters are printable as in ISO\-8859\-1,
to work with certain legacy programs.
@@ -98,26 +115,29 @@ 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.
+The routine \fBendwin\fR(3X) must be called before exiting.
.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
+.NS
+\fBinitscr(); cbreak(); noecho();\fR
+.NE
+.PP
Most programs would additionally use the sequence:
-.sp
- \fBnonl();\fR
- \fBintrflush(stdscr, FALSE);\fR
- \fBkeypad(stdscr, TRUE);\fR
-.sp
+.NS
+\fBnonl();\fR
+\fBintrflush(stdscr, FALSE);\fR
+\fBkeypad(stdscr, TRUE);\fR
+.NE
+.PP
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
.PP
The \fBncurses\fR library permits manipulation of data structures,
called \fIwindows\fR, which can be thought of as two-dimensional
@@ -144,7 +164,7 @@ allowing the user to specify a window.
The routines not beginning
with \fBw\fR affect \fBstdscr\fR.
.PP
-After using routines to manipulate a window, \fBrefresh\fR is called,
+After using routines to manipulate a window, \fBrefresh\fR(3X) 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
@@ -167,6 +187,7 @@ 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
.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
@@ -180,19 +201,22 @@ If the environment variable \fBTERMINFO\fR is defined, any program using
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
+.NS
+\fB\*d/a/att4424\fR.
+.NE
+.PP
(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
+.NS
+\fB$HOME/myterms/a/att4424\fR,
+.NE
+.PP
and if that fails, it then checks
-.sp
- \fB\*d/a/att4424\fR.
-.sp
+.NS
+\fB\*d/a/att4424\fR.
+.NE
+.PP
This is useful for developing experimental definitions or when write
permission in \fB\*d\fR is not available.
.PP
@@ -240,10 +264,10 @@ Types used for the terminfo routines such as
This manual page describes functions which may appear in any configuration
of the library.
There are two common configurations of the library:
-.RS
+.RS 3
.TP 5
-ncurses
-the "normal" library, which handles 8-bit characters.
+.I ncurses
+the \*(``normal\*('' library, which handles 8-bit characters.
The normal (8-bit) library stores characters combined with attributes
in \fBchtype\fP data.
.IP
@@ -253,13 +277,14 @@ In either case, the data is stored in something like an integer.
.IP
Each cell (row and column) in a \fBWINDOW\fP is stored as a \fBchtype\fP.
.TP 5
-ncursesw
-the so-called "wide" library, which handles multibyte characters
+.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.
+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
+.RS 5
.TP 5
.B cchar_t
corresponds to \fBchtype\fP.
@@ -270,9 +295,13 @@ 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.
+.IP
+The \fBsetcchar\fP(3X) and \fBgetcchar\fP(3X)
+functions store and retrieve the data from
+a \fBcchar_t\fP structure.
.TP 5
.B wchar_t
-stores a "wide" character.
+stores a \*(``wide\*('' character.
Like \fBchtype\fP, this may be an integer.
.TP 5
.B wint_t
@@ -280,10 +309,10 @@ 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.
+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.
+a \*(``_w\*('' is inserted into the name.
For example, \fBwaddch\fP becomes \fBwadd_wch\fP.
.RE
.PP
@@ -291,7 +320,7 @@ For example, \fBwaddch\fP becomes \fBwadd_wch\fP.
.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 `*'
+Routines flagged with \*(``*\*(''
are ncurses-specific, not described by XPG4 or present in SVr4.
.PP
.TS
@@ -323,6 +352,7 @@ addnstr/\fBcurs_addstr\fR(3X)
addnwstr/\fBcurs_addwstr\fR(3X)
addstr/\fBcurs_addstr\fR(3X)
addwstr/\fBcurs_addwstr\fR(3X)
+alloc_pair/\fBnew_pair\fR(3X)*
assume_default_colors/\fBdefault_colors\fR(3X)*
attr_get/\fBcurs_attr\fR(3X)
attr_off/\fBcurs_attr\fR(3X)
@@ -372,9 +402,14 @@ endwin/\fBcurs_initscr\fR(3X)
erase/\fBcurs_clear\fR(3X)
erasechar/\fBcurs_termattrs\fR(3X)
erasewchar/\fBcurs_termattrs\fR(3X)
+extended_color_content/\fBcurs_color\fR(3X)*
+extended_pair_content/\fBcurs_color\fR(3X)*
+extended_slk_color/\fBcurs_slk\fR(3X)*
filter/\fBcurs_util\fR(3X)
+find_pair/\fBnew_pair\fR(3X)*
flash/\fBcurs_beep\fR(3X)
flushinp/\fBcurs_util\fR(3X)
+free_pair/\fBnew_pair\fR(3X)*
get_wch/\fBcurs_get_wch\fR(3X)
get_wstr/\fBcurs_get_wstr\fR(3X)
getattrs/\fBcurs_attr\fR(3X)
@@ -417,6 +452,8 @@ inch/\fBcurs_inch\fR(3X)
inchnstr/\fBcurs_inchstr\fR(3X)
inchstr/\fBcurs_inchstr\fR(3X)
init_color/\fBcurs_color\fR(3X)
+init_extended_color/\fBcurs_color\fR(3X)*
+init_extended_pair/\fBcurs_color\fR(3X)*
init_pair/\fBcurs_color\fR(3X)
initscr/\fBcurs_initscr\fR(3X)
innstr/\fBcurs_instr\fR(3X)
@@ -441,7 +478,9 @@ 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)
@@ -574,6 +613,7 @@ 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)
@@ -627,6 +667,7 @@ tigetflag/\fBcurs_terminfo\fR(3X)
tigetnum/\fBcurs_terminfo\fR(3X)
tigetstr/\fBcurs_terminfo\fR(3X)
timeout/\fBcurs_inopts\fR(3X)
+tiparm/\fBcurs_terminfo\fR(3X)*
touchline/\fBcurs_touch\fR(3X)
touchwin/\fBcurs_touch\fR(3X)
tparm/\fBcurs_terminfo\fR(3X)
@@ -643,7 +684,7 @@ 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)
+use_tioctl/\fBcurs_util\fR(3X)*
vid_attr/\fBcurs_terminfo\fR(3X)
vid_puts/\fBcurs_terminfo\fR(3X)
vidattr/\fBcurs_terminfo\fR(3X)
@@ -693,8 +734,11 @@ 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)
@@ -756,108 +800,109 @@ right-hand side of assignment statements).
.PP
Routines that return pointers return \fBNULL\fR on error.
.SH ENVIRONMENT
+.PP
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.
-.TP 5
-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.
-.TP 5
-CC
+.SS CC command-character
+.PP
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.
-.IP
+.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.
-.TP 5
-COLUMNS
+.SS BAUDRATE
+.PP
+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
+.PP
Specify 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).
-.IP
+.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.
-.IP
+.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.
-.IP
+.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.
-.TP 5
-ESCDELAY
+.SS ESCDELAY
+.PP
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.
-.IP
+.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.
-.IP
+.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.
-.IP
+.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
in either form,
but setting the environment variable rather than the global variable
does not create problems when compiling an application.
-.TP 5
-HOME
+.SS HOME
Tells \fBncurses\fR where your home directory is.
That is where it may read and write auxiliary terminal descriptions:
-.IP
+.NS
$HOME/.termcap
-.br
$HOME/.terminfo
-.TP 5
-LINES
+.NE
+.SS LINES
+.PP
Like COLUMNS, specify the height of the screen in characters.
See COLUMNS for a detailed description.
-.TP 5
-MOUSE_BUTTONS_123
+.SS MOUSE_BUTTONS_123
+.PP
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
+.NS
1 = left
.br
2 = right
.br
3 = middle.
-.sp
+.NE
+.PP
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.
-.TP 5
-NCURSES_ASSUMED_COLORS
+.SS NCURSES_ASSUMED_COLORS
+.PP
Override the compiled-in assumption that the
terminal's default colors are white-on-black
(see \fBdefault_colors\fR(3X)).
@@ -867,35 +912,45 @@ 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.
-.TP 5
-NCURSES_GPM_TERMS
+.SS NCURSES_CONSOLE2
+This applies only to the MinGW port of ncurses.
+.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,
+explicitly saving and restoring the original screen contents.
+Setting the environment variable \fBNCGDB\fP has the same effect.
+.SS NCURSES_GPM_TERMS
+.PP
This applies only to ncurses configured to use the GPM interface.
-.IP
+.PP
If present,
the environment variable is a list of one or more terminal names
-against which the TERM environment variable is matched.
+against which the \fBTERM\fP environment variable is matched.
Setting it to an empty value disables the GPM interface;
using the built-in support for xterm, etc.
-.IP
+.PP
If the environment variable is absent,
-ncurses will attempt to open GPM if TERM contains "linux".
-.TP 5
-NCURSES_NO_HARD_TABS
+ncurses will attempt to open GPM if \fBTERM\fP contains \*(``linux\*(''.
+.SS NCURSES_NO_HARD_TABS
+.PP
\fBNcurses\fP may use tabs as part of the 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.
-.TP 5
-NCURSES_NO_MAGIC_COOKIES
+.SS NCURSES_NO_MAGIC_COOKIE
+.PP
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.
-.TP 5
-NCURSES_NO_PADDING
+.SS NCURSES_NO_PADDING
+.PP
Most of the terminal descriptions in the terminfo database are written
-for real "hardware" terminals.
+for real \*(``hardware\*('' terminals.
Many people use terminal emulators
which run in a windowing environment and use curses-based applications.
Terminal emulators can duplicate
@@ -909,29 +964,28 @@ 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.
-.IP
+.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.
-.IP
+.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.
-.TP 5
-NCURSES_NO_SETBUF
+.SS NCURSES_NO_SETBUF
This setting is obsolete.
Before changes
-.RS
+.RS 3
.bP
-started with 5.9 patch 20120825
+started with 5.9 patch 20120825
and
.bP
continued
though 5.9 patch 20130126
.RE
-.IP
+.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,
@@ -939,11 +993,11 @@ this feature was made optional.
Setting the NCURSES_NO_SETBUF variable
disabled output buffering, leaving the output in the original (usually
line buffered) mode.
-.IP
+.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.
-.IP
+.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
@@ -953,30 +1007,30 @@ 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.
-.TP 5
-NCURSES_NO_UTF8_ACS
+.SS NCURSES_NO_UTF8_ACS
+.PP
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.
+Ncurses checks the \fBTERM\fP 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.
-.IP
+.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".
-.IP
+disables the special check for \*(``linux\*('' and \*(``screen\*(''.
+.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 5
+.RS 3
.ft CW
.sp
.nf
@@ -991,94 +1045,157 @@ xterm-utf8|xterm relying on UTF-8 line-graphics,
.fi
.ft
.RE
-.IP
-The name "U8" is chosen to be two characters,
+.PP
+The name \*(``U8\*('' is chosen to be two characters,
to permit it to be used by applications that use ncurses'
termcap interface.
-.TP 5
-NCURSES_TRACE
+.SS NCURSES_TRACE
+.PP
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.
-.IP
+.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.
-.TP 5
-TERM
+.PP
+See \fBcurs_trace\fP(3X) for more information.
+.SS TERM
+.PP
Denotes your terminal type.
Each terminal type is distinct, though many are similar.
-.TP 5
-TERMCAP
+.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.
-.IP
-The TERMCAP environment variable contains either a terminal description (with
-newlines stripped out),
+.PP
+The \fBTERMCAP\fP 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.
+the \fBTERM\fP environment variable exists.
In either case, setting it directs \fBncurses\fR to ignore
the usual place for this information, e.g., /etc/termcap.
-.TP 5
-TERMINFO
-Overrides the directory in which \fBncurses\fR searches for your terminal
+.SS TERMINFO
+.PP
+\fBncurses\fP can be configured to read from multiple terminal databases.
+The \fBTERMINFO\fP variable overrides the location for
+the default terminal database.
+Terminal descriptions (in terminal format) are stored in terminal databases:
+.bP
+Normally these are stored in a directory tree,
+using subdirectories named by the first letter of the terminal names therein.
+.IP
+This is the scheme used in System V, which legacy Unix systems use,
+and the \fBTERMINFO\fP variable is used by \fIcurses\fP applications on those
+systems to override the default location of the terminal database.
+.bP
+If \fBncurses\fP is built to use hashed databases,
+then each entry in this list may be the path of a hashed database file, e.g.,
+.NS
+/usr/share/terminfo.db
+.NE
+.IP
+rather than
+.NS
+/usr/share/terminfo/
+.NE
+.IP
+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,
+reading it directly
+rather than using the terminfo library calls.
+.bP
+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.
+.bP
+If the \fBTERMINFO\fP variable begins with
+\*(``hex:\*('' or \*(``b64:\*('',
+\fBncurses\fP uses the remainder of that variable as a compiled terminal
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
+You might produce the base64 format using \fBinfocmp\fP(1M):
+.NS
+TERMINFO="$(infocmp -0 -Q2 -q)"
+export TERMINFO
+.NE
+.IP
+The compiled description is used if it corresponds to the terminal identified
+by the \fBTERM\fP variable.
+.PP
+Setting \fBTERMINFO\fP is the simplest,
+but not the only way to set location of the default terminal database.
+The complete list of database locations in order follows:
+.RS 3
.bP
-the last directory to which \fBncurses\fR wrote, if any, is searched first
+the last terminal database to which \fBncurses\fR wrote,
+if any, is searched first
.bP
-the directory specified by the TERMINFO environment variable
+the location specified by the TERMINFO environment variable
.bP
$HOME/.terminfo
.bP
-directories listed in the TERMINFO_DIRS environment variable
+locations listed in the TERMINFO_DIRS environment variable
.bP
-one or more directories whose names are configured and compiled into the
+one or more locations whose names are configured and compiled into the
ncurses library, i.e.,
-.RS
+.RS 3
.bP
@TERMINFO_DIRS@ (corresponding to the TERMINFO_DIRS variable)
.bP
@TERMINFO@ (corresponding to the TERMINFO variable)
.RE
.RE
-.TP 5
-TERMINFO_DIRS
-Specifies a list of directories to search for terminal descriptions.
+.PP
+.SS TERMINFO_DIRS
+.PP
+Specifies a list of locations to search for terminal descriptions.
+Each location in the list is a terminal database as described in
+the section on the \fBTERMINFO\fP variable.
The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
-.IP
-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.
-.IP
-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.
-.IP
-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.
-.TP 5
-TERMPATH
-If TERMCAP does not hold a file name then \fBncurses\fR checks
-the TERMPATH environment variable.
+.PP
+There is no corresponding feature in System V terminfo;
+it is an extension developed for \fBncurses\fP.
+.SS TERMPATH
+.PP
+If \fBTERMCAP\fP does not hold a file name then \fBncurses\fR checks
+the \fBTERMPATH\fP environment variable.
This is a list of filenames separated by spaces or colons (i.e., ":") on Unix,
semicolons on OS/2 EMX.
-.IP
-If the TERMPATH environment variable is not set,
+.PP
+If the \fBTERMPATH\fP environment variable is not set,
\fBncurses\fR looks in the files
-/etc/termcap, /usr/share/misc/termcap and $HOME/.termcap, in that order.
+.NS
+/etc/termcap, /usr/share/misc/termcap and $HOME/.termcap,
+.NE
+.PP
+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:
-.IP
+.NS
$TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
+.NE
.SH ALTERNATE CONFIGURATIONS
+.PP
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
@@ -1086,19 +1203,17 @@ developer using \fBncurses\fP:
.TP 5
\-\-disable\-overwrite
The standard include for \fBncurses\fP is as noted in \fBSYNOPSIS\fP:
-.RS
-.sp
+.NS
\fB#include <curses.h>\fR
-.RE
+.NE
.IP
This option is used to avoid filename conflicts when \fBncurses\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
-.sp
+.NS
\fB#include <ncurses/curses.h>\fR
-.RE
+.NE
.IP
It also omits a symbolic link which would allow you to use \fB\-lcurses\fP
to build executables.
@@ -1107,30 +1222,60 @@ to build executables.
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
-.sp
+.NS
\fB\-lncurses\fR
-.RE
+.NE
.IP
you link with
-.RS
-.sp
+.NS
\fB\-lncursesw\fR
+.NE
+.IP
+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 XSI Curses, Issue 4:
+.RS
+.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).
.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.
+.IP
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.
.TP 5
+\-\-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).
+.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
@@ -1140,8 +1285,8 @@ from the same set of headers.
\-\-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
@@ -1157,9 +1302,11 @@ directory containing initialization files for the terminal capability database
terminal capability database
.SH SEE ALSO
\fBterminfo\fR(\*n) and related pages whose names begin
-"curs_" for detailed routine descriptions.
+\*(``curs_\*('' for detailed routine descriptions.
+.br
+\fBcurs_variables\fR(3X)
.br
-\fBcurs_variables\fR(3X)
+\fBuser_caps\fP(5) for user-defined capabilities
.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
@@ -1177,7 +1324,7 @@ 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.
+In addition, the library may be configured with a \fBSIGWINCH\fP handler.
.PP
The \fBncurses\fR library extends the fixed set of function key capabilities
of terminals by allowing the application designer to define additional
diff --git a/man/new_pair.3x b/man/new_pair.3x
new file mode 100644
index 000000000000..3d2eb0954242
--- /dev/null
+++ b/man/new_pair.3x
@@ -0,0 +1,165 @@
+.\"***************************************************************************
+.\" Copyright (c) 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 *
+.\" "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.13 2018/07/28 22:19:56 tom Exp $
+.TH new_pair 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
+.de NS
+.ie n .sp
+.el .sp .5
+.ie n .in +4
+.el .in +2
+.nf
+.ft C \" Courier
+..
+.de NE
+.fi
+.ft R
+.ie n .in -4
+.el .in -2
+..
+.SH NAME
+\fBalloc_pair\fP,
+\fBfind_pair\fP,
+\fBfree_pair\fP \- new curses color-pair functions
+.SH SYNOPSIS
+\fB#include <curses.h>\fP
+.sp
+\fBint alloc_pair(int fg, int bg);\fP
+.br
+\fBint find_pair(int fg, int bg);\fP
+.br
+\fBint free_pair(int pair);\fP
+.SH DESCRIPTION
+These functions are an extension to the curses 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 curses 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.
+.bP
+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:
+.NS
+\fBCOLORS\fP\fI * \fP\fBCOLORS\fP
+.NE
+.bP
+Terminals which support \fIdefault colors\fP distinct
+from \*(``ANSI colors\*(''
+add to the possible combinations, producing this total:
+.NS
+\fI( \fP\fBCOLORS\fP\fI + 1 ) * ( \fP\fBCOLORS\fP\fI + 1 )\fP
+.NE
+.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 \fIpairs\fP capability.
+The table is shared with \fBinit_pair\fP;
+in fact \fBalloc_pair\fP calls \fBinit_pair\fP after
+updating the ncurses 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
+.PP
+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 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_color\fR(3X).
+.SH AUTHOR
+Thomas Dickey.
diff --git a/man/panel.3x b/man/panel.3x
index 25e2348e878d..63babe695521 100644
--- a/man/panel.3x
+++ b/man/panel.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,10 +26,12 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: panel.3x,v 1.17 2010/10/02 23:22:44 tom Exp $
+.\" $Id: panel.3x,v 1.27 2019/03/23 19:23:01 tom Exp $
.TH panel 3X ""
-.ds n 5
-.ds d @TERMINFO@
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.SH NAME
panel \- panel stack extension for curses
.SH SYNOPSIS
@@ -37,46 +39,49 @@ panel \- panel stack extension for curses
.P
\fBcc [flags] sourcefiles \-lpanel \-lncurses\fR
.P
-\fBPANEL *new_panel(WINDOW *win)\fR
+\fBPANEL *new_panel(WINDOW *win);\fR
.br
-\fBint bottom_panel(PANEL *pan)\fR
+\fBint bottom_panel(PANEL *pan);\fR
.br
-\fBint top_panel(PANEL *pan)\fR
+\fBint top_panel(PANEL *pan);\fR
.br
-\fBint show_panel(PANEL *pan)\fR
+\fBint show_panel(PANEL *pan);\fR
.br
-\fBvoid update_panels();\fR
+\fBvoid update_panels(void);\fR
.br
-\fBint hide_panel(PANEL *pan)\fR
+\fBint hide_panel(PANEL *pan);\fR
.br
-\fBWINDOW *panel_window(const PANEL *pan)\fR
+\fBWINDOW *panel_window(const PANEL *pan);\fR
.br
-\fBint replace_panel(PANEL *pan, WINDOW *window)\fR
+\fBint replace_panel(PANEL *pan, WINDOW *window);\fR
.br
-\fBint move_panel(PANEL *pan, int starty, int startx)\fR
+\fBint move_panel(PANEL *pan, int starty, int startx);\fR
.br
-\fBint panel_hidden(const PANEL *pan)\fR
+\fBint panel_hidden(const PANEL *pan);\fR
.br
-\fBPANEL *panel_above(const PANEL *pan)\fR
+\fBPANEL *panel_above(const PANEL *pan);\fR
.br
-\fBPANEL *panel_below(const PANEL *pan)\fR
+\fBPANEL *panel_below(const PANEL *pan);\fR
.br
-\fBint set_panel_userptr(PANEL *pan, const void *ptr)\fR
+\fBint set_panel_userptr(PANEL *pan, const void *ptr);\fR
.br
-\fBconst void *panel_userptr(const PANEL *pan)\fR
+\fBconst void *panel_userptr(const PANEL *pan);\fR
.br
-\fBint del_panel(PANEL *pan)\fR
+\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
+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
+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
+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
@@ -90,15 +95,15 @@ allocates a \fBPANEL\fR structure, associates it with
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.
+.B update_panels
+refreshes the \fIvirtual screen\fP to reflect the relations between the
+panels in the stack, but does not call \fBdoupdate\fP to refresh the
+\fIphysical screen\fP.
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.
+\fBdoupdate\fP, but \fBdoupdate\fP is the function responsible for updating
+the \fIphysical screen\fP.
.TP
.B del_panel(pan)
removes the given panel from the stack and deallocates the
@@ -106,19 +111,22 @@ removes the given panel from the stack and deallocates the
.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.
+view.
+The \fBPANEL\fR structure is not lost, merely removed from the stack.
.TP
.B panel_hidden(pan)
-returns TRUE if the panel is in the panel stack,
-FALSE if it is not.
-If the panel is a null pointer, return ERR.
+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 \fBERR\fP.
.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.
+panel stack.
+See COMPATIBILITY below.
.TP
.B top_panel(pan)
-puts the given visible panel on top of all panels in the stack. See
+puts the given visible panel on top of all panels in the stack.
+See
COMPATIBILITY below.
.TP
.B bottom_panel(pan)
@@ -126,8 +134,10 @@ 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,
+\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)
@@ -137,11 +147,13 @@ 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
+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
+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)
@@ -154,26 +166,39 @@ returns the user pointer for a given panel.
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
+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
+with the native panel facility introduced in System V (inspection of
the SVr4 manual pages suggests the programming interface is unchanged).
-The \fBPANEL\fR data structures are merely similar. The programmer
+The \fBPANEL\fR data structur