aboutsummaryrefslogtreecommitdiff
path: root/contrib/ncurses/man
diff options
context:
space:
mode:
authorRong-En Fan <rafan@FreeBSD.org>2007-01-20 07:32:02 +0000
committerRong-En Fan <rafan@FreeBSD.org>2007-01-20 07:32:02 +0000
commit4a1a95108dd76c4259fe6c37c4471f7969b17983 (patch)
tree1c6c3b549401156e1dbd96b9a6b18521f63ffb58 /contrib/ncurses/man
parent555c9cae3cf9146482732c28c06a73314b618149 (diff)
downloadsrc-4a1a95108dd76c4259fe6c37c4471f7969b17983.tar.gz
src-4a1a95108dd76c4259fe6c37c4471f7969b17983.zip
Import ncurses 5.6-20061217 onto the vender branch
Approved by: delphij
Notes
Notes: svn path=/vendor/ncurses/dist/; revision=166124
Diffstat (limited to 'contrib/ncurses/man')
-rw-r--r--contrib/ncurses/man/Makefile.in17
-rw-r--r--contrib/ncurses/man/captoinfo.1m18
-rw-r--r--contrib/ncurses/man/clear.19
-rw-r--r--contrib/ncurses/man/curs_add_wch.3x5
-rw-r--r--contrib/ncurses/man/curs_add_wchstr.3x11
-rw-r--r--contrib/ncurses/man/curs_addch.3x70
-rw-r--r--contrib/ncurses/man/curs_addchstr.3x40
-rw-r--r--contrib/ncurses/man/curs_addstr.3x16
-rw-r--r--contrib/ncurses/man/curs_addwstr.3x15
-rw-r--r--contrib/ncurses/man/curs_attr.3x104
-rw-r--r--contrib/ncurses/man/curs_beep.3x12
-rw-r--r--contrib/ncurses/man/curs_bkgd.3x41
-rw-r--r--contrib/ncurses/man/curs_bkgrnd.3x19
-rw-r--r--contrib/ncurses/man/curs_border.3x39
-rw-r--r--contrib/ncurses/man/curs_border_set.3x11
-rw-r--r--contrib/ncurses/man/curs_clear.3x43
-rw-r--r--contrib/ncurses/man/curs_color.3x68
-rw-r--r--contrib/ncurses/man/curs_delch.3x6
-rw-r--r--contrib/ncurses/man/curs_deleteln.3x18
-rw-r--r--contrib/ncurses/man/curs_extend.3x15
-rw-r--r--contrib/ncurses/man/curs_get_wch.3x20
-rw-r--r--contrib/ncurses/man/curs_get_wstr.3x36
-rw-r--r--contrib/ncurses/man/curs_getcchar.3x8
-rw-r--r--contrib/ncurses/man/curs_getch.3x75
-rw-r--r--contrib/ncurses/man/curs_getstr.3x33
-rw-r--r--contrib/ncurses/man/curs_getyx.3x47
-rw-r--r--contrib/ncurses/man/curs_in_wch.3x6
-rw-r--r--contrib/ncurses/man/curs_in_wchstr.3x13
-rw-r--r--contrib/ncurses/man/curs_inch.3x14
-rw-r--r--contrib/ncurses/man/curs_inchstr.3x19
-rw-r--r--contrib/ncurses/man/curs_initscr.3x34
-rw-r--r--contrib/ncurses/man/curs_inopts.3x78
-rw-r--r--contrib/ncurses/man/curs_ins_wch.3x6
-rw-r--r--contrib/ncurses/man/curs_ins_wstr.3x14
-rw-r--r--contrib/ncurses/man/curs_insch.3x14
-rw-r--r--contrib/ncurses/man/curs_insstr.3x52
-rw-r--r--contrib/ncurses/man/curs_instr.3x16
-rw-r--r--contrib/ncurses/man/curs_inwstr.3x10
-rw-r--r--contrib/ncurses/man/curs_kernel.3x67
-rw-r--r--contrib/ncurses/man/curs_mouse.3x129
-rw-r--r--contrib/ncurses/man/curs_move.3x22
-rw-r--r--contrib/ncurses/man/curs_outopts.3x73
-rw-r--r--contrib/ncurses/man/curs_overlay.3x21
-rw-r--r--contrib/ncurses/man/curs_pad.3x102
-rw-r--r--contrib/ncurses/man/curs_print.3x16
-rw-r--r--contrib/ncurses/man/curs_printw.3x48
-rw-r--r--contrib/ncurses/man/curs_refresh.3x34
-rw-r--r--contrib/ncurses/man/curs_scanw.3x44
-rw-r--r--contrib/ncurses/man/curs_scr_dump.3x28
-rw-r--r--contrib/ncurses/man/curs_scroll.3x32
-rw-r--r--contrib/ncurses/man/curs_slk.3x110
-rw-r--r--contrib/ncurses/man/curs_termattrs.3x31
-rw-r--r--contrib/ncurses/man/curs_termcap.3x43
-rw-r--r--contrib/ncurses/man/curs_terminfo.3x137
-rw-r--r--contrib/ncurses/man/curs_touch.3x32
-rw-r--r--contrib/ncurses/man/curs_trace.3x16
-rw-r--r--contrib/ncurses/man/curs_util.3x94
-rw-r--r--contrib/ncurses/man/curs_window.3x67
-rw-r--r--contrib/ncurses/man/default_colors.3x28
-rw-r--r--contrib/ncurses/man/define_key.3x13
-rw-r--r--contrib/ncurses/man/form.3x76
-rw-r--r--contrib/ncurses/man/form_cursor.3x17
-rw-r--r--contrib/ncurses/man/form_data.3x6
-rw-r--r--contrib/ncurses/man/form_driver.3x43
-rw-r--r--contrib/ncurses/man/form_field.3x41
-rw-r--r--contrib/ncurses/man/form_field_attributes.3x19
-rw-r--r--contrib/ncurses/man/form_field_buffer.3x35
-rw-r--r--contrib/ncurses/man/form_field_info.3x17
-rw-r--r--contrib/ncurses/man/form_field_just.3x16
-rw-r--r--contrib/ncurses/man/form_field_new.3x36
-rw-r--r--contrib/ncurses/man/form_field_opts.3x30
-rw-r--r--contrib/ncurses/man/form_field_userptr.3x22
-rw-r--r--contrib/ncurses/man/form_field_validation.3x51
-rw-r--r--contrib/ncurses/man/form_fieldtype.3x70
-rw-r--r--contrib/ncurses/man/form_hook.3x16
-rw-r--r--contrib/ncurses/man/form_new.3x30
-rw-r--r--contrib/ncurses/man/form_new_page.3x14
-rw-r--r--contrib/ncurses/man/form_opts.3x16
-rw-r--r--contrib/ncurses/man/form_page.3x21
-rw-r--r--contrib/ncurses/man/form_post.3x35
-rw-r--r--contrib/ncurses/man/form_requestname.3x5
-rw-r--r--contrib/ncurses/man/form_userptr.3x22
-rw-r--r--contrib/ncurses/man/form_win.3x20
-rw-r--r--contrib/ncurses/man/infocmp.1m263
-rw-r--r--contrib/ncurses/man/infotocap.1m7
-rw-r--r--contrib/ncurses/man/key_defined.3x60
-rw-r--r--contrib/ncurses/man/keybound.3x15
-rw-r--r--contrib/ncurses/man/keyok.3x8
-rw-r--r--contrib/ncurses/man/legacy_coding.3x82
-rwxr-xr-xcontrib/ncurses/man/make_sed.sh18
-rw-r--r--contrib/ncurses/man/man_db.renames34
-rw-r--r--contrib/ncurses/man/manlinks.sed59
-rw-r--r--contrib/ncurses/man/menu.3x65
-rw-r--r--contrib/ncurses/man/menu_attributes.3x16
-rw-r--r--contrib/ncurses/man/menu_cursor.3x12
-rw-r--r--contrib/ncurses/man/menu_driver.3x24
-rw-r--r--contrib/ncurses/man/menu_format.3x19
-rw-r--r--contrib/ncurses/man/menu_hook.3x16
-rw-r--r--contrib/ncurses/man/menu_items.3x36
-rw-r--r--contrib/ncurses/man/menu_mark.3x28
-rw-r--r--contrib/ncurses/man/menu_new.3x23
-rw-r--r--contrib/ncurses/man/menu_opts.3x18
-rw-r--r--contrib/ncurses/man/menu_pattern.3x35
-rw-r--r--contrib/ncurses/man/menu_post.3x22
-rw-r--r--contrib/ncurses/man/menu_requestname.3x12
-rw-r--r--contrib/ncurses/man/menu_spacing.3x6
-rw-r--r--contrib/ncurses/man/menu_userptr.3x22
-rw-r--r--contrib/ncurses/man/menu_win.3x20
-rw-r--r--contrib/ncurses/man/mitem_current.3x33
-rw-r--r--contrib/ncurses/man/mitem_name.3x11
-rw-r--r--contrib/ncurses/man/mitem_new.3x27
-rw-r--r--contrib/ncurses/man/mitem_opts.3x16
-rw-r--r--contrib/ncurses/man/mitem_userptr.3x22
-rw-r--r--contrib/ncurses/man/mitem_value.3x12
-rw-r--r--contrib/ncurses/man/ncurses.3x277
-rw-r--r--contrib/ncurses/man/panel.3x11
-rw-r--r--contrib/ncurses/man/resizeterm.3x20
-rw-r--r--contrib/ncurses/man/term.5115
-rw-r--r--contrib/ncurses/man/term.730
-rw-r--r--contrib/ncurses/man/terminfo.head18
-rw-r--r--contrib/ncurses/man/terminfo.tail262
-rw-r--r--contrib/ncurses/man/tic.1m172
-rw-r--r--contrib/ncurses/man/toe.1m34
-rw-r--r--contrib/ncurses/man/tput.1181
-rw-r--r--contrib/ncurses/man/tset.1152
-rw-r--r--contrib/ncurses/man/wresize.3x8
126 files changed, 3459 insertions, 1779 deletions
diff --git a/contrib/ncurses/man/Makefile.in b/contrib/ncurses/man/Makefile.in
index 56dbe0933e96..8a24d843a242 100644
--- a/contrib/ncurses/man/Makefile.in
+++ b/contrib/ncurses/man/Makefile.in
@@ -1,6 +1,6 @@
-# $Id: Makefile.in,v 1.33 2002/01/19 22:49:44 tom Exp $
+# $Id: Makefile.in,v 1.39 2005/07/16 17:26:45 tom Exp $
##############################################################################
-# Copyright (c) 1998,2000,2001,2002 Free Software Foundation, Inc. #
+# Copyright (c) 1998-2003,2005 Free 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"), #
@@ -27,7 +27,7 @@
# authorization. #
##############################################################################
#
-# Author: Thomas E. Dickey <dickey@clark.net> 1996,1997
+# Author: Thomas E. Dickey 1996,1997
#
# Makefile for ncurses manual pages.
#
@@ -49,6 +49,7 @@ INSTALL_DATA = @INSTALL_DATA@
all \
sources : terminfo.5
depend :
+tags :
$(DESTDIR)$(mandir) :
sh $(srcdir)/../mkinstalldirs $@
@@ -56,10 +57,10 @@ $(DESTDIR)$(mandir) :
EDITARGS = $(DESTDIR)$(mandir) $(srcdir) terminfo.5 $(srcdir)/*.[0-9]*
install install.man : terminfo.5 $(DESTDIR)$(mandir)
- sh ./edit_man.sh installing $(EDITARGS)
+ sh ../edit_man.sh normal installing $(EDITARGS)
uninstall uninstall.man :
- -sh ./edit_man.sh removing $(EDITARGS)
+ -sh ../edit_man.sh normal removing $(EDITARGS)
# We compose terminfo.5 from the real sources...
CAPLIST=$(srcdir)/../include/@TERMINFO_CAPS@
@@ -72,8 +73,8 @@ mostlyclean :
clean: mostlyclean
rm -f terminfo.5
-edit_man.sed : make_sed.sh @MANPAGE_RENAMES@
- sh $srcdir/make_sed.sh @MANPAGE_RENAMES@ >edit_man.sed
+../edit_man.sed : make_sed.sh @MANPAGE_RENAMES@
+ sh $(srcdir)/make_sed.sh @MANPAGE_RENAMES@ >../edit_man.sed
distclean realclean: clean
- rm -f Makefile edit_man.*
+ rm -f Makefile ../edit_man.*
diff --git a/contrib/ncurses/man/captoinfo.1m b/contrib/ncurses/man/captoinfo.1m
index 40c09f5a213f..1bb6dec82fbf 100644
--- a/contrib/ncurses/man/captoinfo.1m
+++ b/contrib/ncurses/man/captoinfo.1m
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2004,2006 Free 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: captoinfo.1m,v 1.16 2000/08/13 01:56:49 tom Exp $
+.\" $Id: captoinfo.1m,v 1.20 2006/05/13 15:14:01 tom Exp $
.TH captoinfo 1M ""
.ds n 5
.ds d @TERMINFO@
@@ -40,7 +40,7 @@
one found, an equivalent \fBterminfo\fR description is written to standard
output. Termcap \fBtc\fR capabilities are translated directly to terminfo
\fBuse\fR capabilities.
-
+.PP
If no \fIfile\fR is given, then the environment variable \fBTERMCAP\fR is used
for the filename or entry. If \fBTERMCAP\fR is a full pathname to a file, only
the terminal whose name is specified in the environment variable \fBTERM\fR is
@@ -151,7 +151,6 @@ be composed into an \fBacsc\fR string. The double-line capabilities and
IBM's AIX has a terminfo facility descended from SVr1 terminfo but incompatible
with the SVr4 format. The following AIX extensions are automatically
translated:
-.PP
.TS
c c
l l.
@@ -174,11 +173,16 @@ These will be discarded with a warning message.
.SH NOTES
This utility is actually a link to \fItic\fR(1M), running in \fI-I\fR mode.
You can use other \fItic\fR options such as \fB-f\fR and \fB-x\fR.
-
+.PP
The trace option isn't identical to SVr4's. Under SVr4, instead of following
-the -v with a trace level n, you repeat it n times.
+the \fB-v\fR with a trace level n, you repeat it n times.
.SH SEE ALSO
-\fBcurses\fR(3X), \fB@INFOCMP@\fR(1M), \fBterminfo\fR(\*n)
+\fB@INFOCMP@\fR(1M),
+\fBcurses\fR(3X),
+\fBterminfo\fR(\*n)
+.PP
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.SH AUTHOR
Eric S. Raymond <esr@snark.thyrsus.com>
.\"#
diff --git a/contrib/ncurses/man/clear.1 b/contrib/ncurses/man/clear.1
index 4c4991f1d1a3..41c4cadc7796 100644
--- a/contrib/ncurses/man/clear.1
+++ b/contrib/ncurses/man/clear.1
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2000,2006 Free 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: clear.1,v 1.3 2000/07/15 23:59:35 china Exp $
+.\" $Id: clear.1,v 1.5 2006/07/01 21:55:09 tom Exp $
.TH clear 1 ""
.ds n 5
.SH NAME
@@ -38,8 +38,13 @@
\fBclear\fR clears your screen if this is possible. It looks in the
environment for the terminal type and then in the \fBterminfo\fR database to
figure out how to clear the screen.
+.PP
+\fBclear\fR ignores any command-line parameters that may be present.
.SH SEE ALSO
\fB@TPUT@\fR(1), \fBterminfo\fR(\*n)
+.PP
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/curs_add_wch.3x b/contrib/ncurses/man/curs_add_wch.3x
index fae59ae0b6cd..91228d450b20 100644
--- a/contrib/ncurses/man/curs_add_wch.3x
+++ b/contrib/ncurses/man/curs_add_wch.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2001,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 2001-2002,2006 Free 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_add_wch.3x,v 1.4 2002/02/16 22:28:43 tom Exp $
+.\" $Id: curs_add_wch.3x,v 1.5 2006/12/02 17:02:35 tom Exp $
.TH curs_add_wch 3X ""
.SH NAME
\fBadd_wch\fP,
@@ -121,6 +121,7 @@ Those are not currently implemented in \fBncurses\fP.
.SH SEE ALSO
.PP
\fBcurses\fR(3X),
+\fBcurs_addch\fR(3X),
\fBcurs_attr_get\fR(3X),
\fBcurs_clear\fR(3X),
\fBcurs_outopts\fR(3X),
diff --git a/contrib/ncurses/man/curs_add_wchstr.3x b/contrib/ncurses/man/curs_add_wchstr.3x
index 17d344698500..f84c2cb98c24 100644
--- a/contrib/ncurses/man/curs_add_wchstr.3x
+++ b/contrib/ncurses/man/curs_add_wchstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2004,2005 Free 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,9 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_add_wchstr.3x,v 1.1 2002/02/23 22:15:55 tom Exp $
+.\" $Id: curs_add_wchstr.3x,v 1.6 2005/01/02 01:28:49 tom Exp $
.TH curs_add_wchstr 3X ""
.SH NAME
-.PP
\fBadd_wchstr\fR,
\fBadd_wchnstr\fR,
\fBwadd_wchstr\fR,
@@ -40,7 +39,7 @@
\fBmvwadd_wchnstr\fR \- add an array of complex characters (and attributes) to a curses window
.SH SYNOPSIS
.B #include <curses.h>
-
+.PP
.nf
\fBint add_wchstr(const cchar_t *\fR\fIwchstr\fR\fB);\fR
.br
@@ -73,7 +72,7 @@ On the other hand, they do not perform checking
they do not advance the current cursor position,
they do not expand other control characters to ^-escapes,
and they truncate the string if it crosses the right margin,
-rather then wrapping it around to the new line.
+rather than wrapping it around to the new line.
.PP
These routines end successfully
on encountering a null \fIcchar_t\fR, or
@@ -88,7 +87,7 @@ All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success.
All these entry points are described in the XSI Curses standard, Issue 4.
.SH SEE ALSO
\fBcurses\fR(3X),
-\fBcurs_addchstr\fR(3X)
+\fBcurs_addchstr\fR(3X),
\fBcurs_addwstr\fR(3X)
.\"#
.\"# The following sets edit modes for GNU EMACS
diff --git a/contrib/ncurses/man/curs_addch.3x b/contrib/ncurses/man/curs_addch.3x
index 63e05269d0b7..d8b645d7c359 100644
--- a/contrib/ncurses/man/curs_addch.3x
+++ b/contrib/ncurses/man/curs_addch.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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: curs_addch.3x,v 1.17 2000/07/01 19:53:01 tom Exp $
+.\" $Id: curs_addch.3x,v 1.25 2006/12/02 17:02:22 tom Exp $
.TH curs_addch 3X ""
.SH NAME
\fBaddch\fR, \fBwaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR,
@@ -35,18 +35,18 @@
\fBwechochar\fR - add a character (with attributes) to a \fBcurses\fR window, then advance the cursor
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
-\fBint addch(chtype ch);\fR
+.PP
+\fBint addch(const chtype ch);\fR
.br
-\fBint waddch(WINDOW *win, chtype ch);\fR
+\fBint waddch(WINDOW *win, const chtype ch);\fR
.br
-\fBint mvaddch(int y, int x, chtype ch);\fR
+\fBint mvaddch(int y, int x, const chtype ch);\fR
.br
-\fBint mvwaddch(WINDOW *win, int y, int x, chtype ch);\fR
+\fBint mvwaddch(WINDOW *win, int y, int x, const chtype ch);\fR
.br
-\fBint echochar(chtype ch);\fR
+\fBint echochar(const chtype ch);\fR
.br
-\fBint wechochar(WINDOW *win, chtype ch);\fR
+\fBint wechochar(WINDOW *win, const chtype ch);\fR
.br
.SH DESCRIPTION
The \fBaddch\fR, \fBwaddch\fR, \fBmvaddch\fR and \fBmvwaddch\fR routines put
@@ -55,25 +55,29 @@ 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.
-
-If \fIch\fR is a tab, newline, or backspace, the cursor is moved appropriately
-within the window. Backspace moves the cursor one character left; at the left
-edge of a window it does nothing. 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). Tabs are considered to be at every eighth column.
-
+.PP
+If \fIch\fR is a tab, newline, or backspace,
+the cursor is moved appropriately within the window.
+Backspace moves the cursor one character left; at the left
+edge of a window it does nothing.
+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.
+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
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 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.
-
+.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
@@ -84,9 +88,9 @@ their equivalents.
The following variables may be used to add line drawing characters to the
screen with routines of the \fBaddch\fR family. The default character listed
below is used if the \fBacsc\fR capability doesn't define a terminal-specific
-replacement for it (but see the EXTENSIONS section below). The names are
-taken from VT100 nomenclature.
-
+replacement for it.
+The names are taken from VT100 nomenclature.
+.PP
.TS
l l l
_ _ _
@@ -125,7 +129,6 @@ ACS_ULCORNER + upper left-hand corner
ACS_URCORNER + upper right-hand corner
ACS_VLINE | 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
@@ -137,7 +140,7 @@ 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.
-
+.LP
Some ACS symbols
(ACS_S3,
ACS_S7,
@@ -151,10 +154,25 @@ any publicly released System V. However, many publicly available terminfos
include \fBacsc\fR strings in which their key characters (pryz{|}) are
embedded, and a second-hand list of their character descriptions has come
to light. The ACS-prefixed names for them were invented for \fBncurses\fR(3X).
+.LP
+The \fBTABSIZE\fR variable is implemented in some versions of curses,
+but is not part of X/Open curses.
+.LP
+If \fIch\fR is a carriage return,
+the cursor is moved to the beginning of the current row of the window.
+This is true of other implementations, but is not documented.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_attr\fR(3X), \fBcurs_clear\fR(3X),
-\fBcurs_inch\fR(3X), \fBcurs_outopts\fR(3X), \fBcurs_refresh\fR(3X),
+\fBcurses\fR(3X),
+\fBcurs_attr\fR(3X),
+\fBcurs_clear\fR(3X),
+\fBcurs_inch\fR(3X),
+\fBcurs_outopts\fR(3X),
+\fBcurs_refresh\fR(3X),
\fBputc\fR(3S).
+.PP
+Comparable functions in the wide-character (ncursesw) library are
+described in
+\fBcurs_add_wch\fR(3X).
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/curs_addchstr.3x b/contrib/ncurses/man/curs_addchstr.3x
index 0d9ea29f0280..ac1b040021e5 100644
--- a/contrib/ncurses/man/curs_addchstr.3x
+++ b/contrib/ncurses/man/curs_addchstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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,15 +26,24 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addchstr.3x,v 1.7 2000/07/01 19:53:33 tom Exp $
+.\" $Id: curs_addchstr.3x,v 1.12 2006/12/02 17:02:45 tom Exp $
.TH curs_addchstr 3X ""
+.na
+.hy 0
.SH NAME
-\fBaddchstr\fR, \fBaddchnstr\fR, \fBwaddchstr\fR,
-\fBwaddchnstr\fR, \fBmvaddchstr\fR, \fBmvaddchnstr\fR, \fBmvwaddchstr\fR,
+\fBaddchstr\fR,
+\fBaddchnstr\fR,
+\fBwaddchstr\fR,
+\fBwaddchnstr\fR,
+\fBmvaddchstr\fR,
+\fBmvaddchnstr\fR,
+\fBmvwaddchstr\fR,
\fBmvwaddchnstr\fR - add a string of characters (and attributes) to a \fBcurses\fR window
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.PP
\fBint addchstr(const chtype *chstr);\fR
.br
\fBint addchnstr(const chtype *chstr, int n);\fR
@@ -56,25 +65,32 @@ the current cursor position. The four routines with \fIn\fR as the last
argument copy at most \fIn\fR elements, but no more than will fit on the line.
If \fBn\fR=\fB-1\fR then the whole string is copied, to the maximum number of
characters that will fit on the line.
-
+.PP
The window cursor is \fInot\fR advanced, and these routines work faster than
-\fBwaddnstr\fR. On the other hand, they don't perform any kind of checking
-(such as for the newline, backspace, or carriage return characters), they don't
-advance the current cursor position, they don't expand other control characters
+\fBwaddnstr\fR. On the other hand, they do not perform any kind of checking
+(such as for the newline, backspace, or carriage return characters), they do not
+advance the current cursor position, they do not expand other control characters
to ^-escapes, and they truncate the string if it crosses the right margin,
-rather then wrapping it around to the new line.
-
+rather than wrapping it around to the new line.
.SH RETURN VALUES
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.
+.PP
+X/Open does not define any error conditions.
+This implementation returns an error
+if the window pointer is null.
.SH NOTES
Note that all routines except \fBwaddchnstr\fR may be macros.
.SH PORTABILITY
-All these entry points are described in the XSI Curses standard, Issue 4.
+These entry points 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_add_wchstr\fR(3X).
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/curs_addstr.3x b/contrib/ncurses/man/curs_addstr.3x
index a845acbca7e9..488b9dd8e752 100644
--- a/contrib/ncurses/man/curs_addstr.3x
+++ b/contrib/ncurses/man/curs_addstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2005 Free 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,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addstr.3x,v 1.10 2002/03/09 23:09:29 tom Exp $
+.\" $Id: curs_addstr.3x,v 1.13 2005/05/15 16:17:14 tom Exp $
.TH curs_addstr 3X ""
+.na
+.hy 0
.SH NAME
\fBaddstr\fR,
\fBaddnstr\fR,
@@ -37,10 +39,12 @@
\fBmvaddnstr\fR,
\fBmvwaddstr\fR,
\fBmvwaddnstr\fR - add a string of characters to a \fBcurses\fR window and advance cursor
+.ad
+.hy
.SH SYNOPSIS
.nf
\fB#include <curses.h>\fR
-
+.PP
\fBint addstr(const char *\fR\fIstr\fR\fB);\fR
.br
\fBint addnstr(const char *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
@@ -70,6 +74,12 @@ or until a terminating null is reached.
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.
+.PP
+X/Open does not define any error conditions.
+This implementation returns an error
+if the window pointer is null or
+if the string pointer is null or
+if the corresponding calls to \fBwaddch\fP return an error.
.SH NOTES
Note that all of these routines except \fBwaddstr\fR and \fBwaddnstr\fR may be
macros.
diff --git a/contrib/ncurses/man/curs_addwstr.3x b/contrib/ncurses/man/curs_addwstr.3x
index 4ce7c2301e6a..63d274608cc7 100644
--- a/contrib/ncurses/man/curs_addwstr.3x
+++ b/contrib/ncurses/man/curs_addwstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2005,2006 Free 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,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addwstr.3x,v 1.2 2002/03/09 23:16:59 tom Exp $
+.\" $Id: curs_addwstr.3x,v 1.7 2006/02/25 20:59:08 tom Exp $
.TH curs_addwstr 3X ""
+.na
+.hy 0
.SH NAME
\fBaddwstr\fR,
\fBaddnwstr\fR,
@@ -37,10 +39,12 @@
\fBmvaddnwstr\fR,
\fBmvwaddwstr\fR,
\fBmvwaddnwstr\fR \- add a string of wide characters to a \fBcurses\fR window and advance cursor
+.ad
+.hy
.SH SYNOPSIS
.nf
\fB#include <curses.h>\fR
-
+.PP
\fBint addwstr(const wchar_t *\fR\fIwstr\fR\fB);\fR
.br
\fBint addnwstr(const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
@@ -58,7 +62,8 @@
\fBint mvwaddnwstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
.fi
.SH DESCRIPTION
-These routines write the characters of the (null-terminated) \fBwchar_t\fRcharacter string
+These routines write the characters of the
+(null-terminated) \fBwchar_t\fR character string
\fIwstr\fR on the given window.
It is similar to constructing a \fBcchar_t\fR for each wchar_t in the string,
then calling \fBwadd_wch\fR for the resulting \fBcchar_t\fR.
@@ -79,8 +84,6 @@ Note that all of these routines except \fBwaddnwstr\fR may be macros.
.SH PORTABILITY
All these entry points are described in the XSI Curses standard, Issue 4.
.SH SEE ALSO
-.PP
-Functions:
\fBcurses\fR(3X),
\fBcurs_add_wch\fR(3X)
.\"#
diff --git a/contrib/ncurses/man/curs_attr.3x b/contrib/ncurses/man/curs_attr.3x
index 022613de29e5..31c5397dad1f 100644
--- a/contrib/ncurses/man/curs_attr.3x
+++ b/contrib/ncurses/man/curs_attr.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2000,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,19 +27,38 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_attr.3x,v 1.24 2002/02/16 22:38:32 tom Exp $
+.\" $Id: curs_attr.3x,v 1.30 2006/07/15 18:39:05 tom Exp $
.TH curs_attr 3X ""
+.na
+.hy 0
.SH NAME
-\fBattroff\fR, \fBwattroff\fR, \fBattron\fR, \fBwattron\fR,
-\fBattrset\fR, \fBwattrset\fR, \fBcolor_set\fR, \fBwcolor_set\fR,
-\fBstandend\fR, \fBwstandend\fR, \fBstandout\fR, \fBwstandout\fR,
-\fBattr_get\fR, \fBwattr_get\fR,
-\fBattr_off\fR, \fBwattr_off\fR,
-\fBattr_on\fR, \fBwattr_on\fR,
-\fBattr_set\fR, \fBwattr_set\fR,
-\fBchgat\fR, \fBwchgat\fR,
-\fBmvchgat\fR, \fBmvwchgat\fR,
+\fBattroff\fR,
+\fBwattroff\fR,
+\fBattron\fR,
+\fBwattron\fR,
+\fBattrset\fR,
+\fBwattrset\fR,
+\fBcolor_set\fR,
+\fBwcolor_set\fR,
+\fBstandend\fR,
+\fBwstandend\fR,
+\fBstandout\fR,
+\fBwstandout\fR,
+\fBattr_get\fR,
+\fBwattr_get\fR,
+\fBattr_off\fR,
+\fBwattr_off\fR,
+\fBattr_on\fR,
+\fBwattr_on\fR,
+\fBattr_set\fR,
+\fBwattr_set\fR,
+\fBchgat\fR,
+\fBwchgat\fR,
+\fBmvchgat\fR,
+\fBmvwchgat\fR,
\fBPAIR_NUMBER\fR - \fBcurses\fR character and window attribute control routines
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
.br
@@ -105,7 +124,7 @@ a property of the character, and move with the character through any scrolling
and insert/delete line/character operations. To the extent possible, they are
displayed as appropriate modifications to the graphic rendition of characters
put on the screen.
-
+.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
@@ -113,19 +132,24 @@ 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
+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.
-
+.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.
-
+.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
@@ -137,9 +161,9 @@ of \fIinit_pair\fR, see \fBcurs_color\fR(3X)). The \fBopts\fR argument is not
presently used, but is reserved for the future (leave it \fBNULL\fR).
.SS Attributes
The following video attributes, defined in \fB<curses.h>\fR, can be passed to
-the routines \fBattron\fR, \fBattroff\fR, and \fBattrset\fR, or OR'ed with the
+the routines \fBattron\fR, \fBattroff\fR, and \fBattrset\fR, or OR'd with the
characters passed to \fBaddch\fR.
-
+.PP
.TS
center ;
l l .
@@ -156,39 +180,49 @@ l l .
\fBA_CHARTEXT\fR Bit-mask to extract a character
\fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR Color-pair number \fIn\fR
.TE
-
+.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.
+.PP
+\fBCOLOR_PAIR\fP values can only be OR'd with attributes if the pair
+number is less than 256.
+The alternate functions such as \fBcolor_set\fP can pass a color pair
+value directly.
+However, ncurses ABI 4 and 5 simply OR this value within the alternate functions.
+You must use ncurses ABI 6 to support more than 256 color pairs.
.SH PORTABILITY
-All these functions are supported in the XSI Curses standard, Issue 4. The
+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.
-
+.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
SVr4 curses, these functions correctly manipulate all other highlights
(specifically, \fBA_ALTCHARSET\fR, \fBA_PROTECT\fR, and \fBA_INVIS\fR).
-
+.PP
XSI Curses added the new entry points, \fBattr_get\fR, \fBattr_on\fR,
\fBattr_off\fR, \fBattr_set\fR, \fBwattr_on\fR, \fBwattr_off\fR,
\fBwattr_get\fR, \fBwattr_set\fR. These are intended to work with
a new series of highlight macros prefixed with \fBWA_\fR.
-
+.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
.TS
center ;
l l .
@@ -201,17 +235,29 @@ l l .
\fBWA_BOLD\fR Extra bright or bold
\fBWA_ALTCHARSET\fR Alternate character set
.TE
-
+.PP
The XSI curses standard specifies that each pair of corresponding \fBA_\fR
and \fBWA_\fR-using functions operates on the same current-highlight
information.
-
+.PP
The XSI standard extended conformance level adds new highlights
\fBA_HORIZONTAL\fR, \fBA_LEFT\fR, \fBA_LOW\fR, \fBA_RIGHT\fR, \fBA_TOP\fR,
\fBA_VERTICAL\fR (and corresponding \fBWA_\fR macros for each) which this
-curses does not yet support.
+implementation does not yet support.
+.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.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_addch\fR(3X), \fBcurs_addstr\fR(3X),
+\fBcurses\fR(3X),
+\fBcurs_addch\fR(3X),
+\fBcurs_addstr\fR(3X),
+\fBcurs_bkgd\fR(3X),
\fBcurs_printw\fR(3X)
.\"#
.\"# The following sets edit modes for GNU EMACS
diff --git a/contrib/ncurses/man/curs_beep.3x b/contrib/ncurses/man/curs_beep.3x
index b9caaa804f76..49e57619de3c 100644
--- a/contrib/ncurses/man/curs_beep.3x
+++ b/contrib/ncurses/man/curs_beep.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2005 Free 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,13 +26,13 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_beep.3x,v 1.7 1998/03/11 21:12:53 juergen Exp $
+.\" $Id: curs_beep.3x,v 1.10 2005/01/08 17:55:51 tom Exp $
.TH curs_beep 3X ""
.SH NAME
\fBbeep\fR, \fBflash\fR - \fBcurses\fR bell and screen flash routines
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.PP
\fBint beep(void);\fR
.br
\fBint flash(void);\fR
@@ -45,14 +45,14 @@ 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,
+These routines return \fBOK\fR if they succeed in beeping or flashing,
\fBERR\fR otherwise.
.SH EXTENSIONS
SVr4's beep and flash routines always returned \fBOK\fR, so it was not
possible to tell when the beep or flash failed.
.SH PORTABILITY
-These functions are defined in the XSI Curses standard, Issue 4. Like SVr4, it
-specifies that they always return \fBOK\fR.
+These functions are described in the XSI Curses standard, Issue 4.
+Like SVr4, it specifies that they always return \fBOK\fR.
.SH SEE ALSO
\fBcurses\fR(3X)
.\"#
diff --git a/contrib/ncurses/man/curs_bkgd.3x b/contrib/ncurses/man/curs_bkgd.3x
index 035e97501e77..b2d768a441d9 100644
--- a/contrib/ncurses/man/curs_bkgd.3x
+++ b/contrib/ncurses/man/curs_bkgd.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2000,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2002,2003 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,23 +26,22 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_bkgd.3x,v 1.16 2002/02/16 22:38:32 tom Exp $
+.\" $Id: curs_bkgd.3x,v 1.19 2003/12/27 18:50:40 tom Exp $
.TH curs_bkgd 3X ""
.SH NAME
\fBbkgdset\fR, \fBwbkgdset\fR,
\fBbkgd\fR, \fBwbkgd\fR,
\fBgetbkgd\fR - \fBcurses\fR window background manipulation routines
-
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
-\fBvoid bkgdset(const chtype ch);\fR
+.PP
+\fBvoid bkgdset(chtype ch);\fR
.br
-\fBvoid wbkgdset(WINDOW *win, const chtype ch);\fR
+\fBvoid wbkgdset(WINDOW *win, chtype ch);\fR
.br
-\fBint bkgd(const chtype ch);\fR
+\fBint bkgd(chtype ch);\fR
.br
-\fBint wbkgd(WINDOW *win, const chtype ch);\fR
+\fBint wbkgd(WINDOW *win, chtype ch);\fR
.br
\fBchtype getbkgd(WINDOW *win);\fR
.br
@@ -57,23 +56,23 @@ 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.
-
-To the extent possible on a
-particular terminal, the attribute part of the background is displayed
+.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.
-
+.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:
-
+.PP
.RS
The rendition of every character on the screen is changed to
the new background rendition.
-
+.PP
Wherever the former background character
appears, it is changed to the new background character.
.RE
-
+.PP
The \fBgetbkgd\fR function returns the given window's current background
character/attribute pair.
.SH RETURN VALUE
@@ -83,12 +82,14 @@ but this appears to be an error.
.SH NOTES
Note that \fBbkgdset\fR and \fBbkgd\fR may be macros.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4. The draft
-does not include \fBconst\fR qualifiers on the arguments. The standard
-specifies that \fBbkgd\fR and \fBwbkgd\fR return \fBERR\fR, on failure. but
-gives no failure conditions.
+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.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_addch\fR(3X), \fBcurs_outopts\fR(3X)
+\fBcurses\fR(3X),
+\fBcurs_addch\fR(3X),
+\fBcurs_attr\fR(3X),
+\fBcurs_outopts\fR(3X)
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/curs_bkgrnd.3x b/contrib/ncurses/man/curs_bkgrnd.3x
index 3be0dced7b22..8c6f6afff6f4 100644
--- a/contrib/ncurses/man/curs_bkgrnd.3x
+++ b/contrib/ncurses/man/curs_bkgrnd.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2004,2006 Free 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,9 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_bkgrnd.3x,v 1.1 2002/02/23 23:23:42 tom Exp $
+.\" $Id: curs_bkgrnd.3x,v 1.3 2006/02/25 21:49:19 tom Exp $
.TH curs_bkgrnd 3X ""
.SH NAME
-.PP
\fBbkgrnd\fR,
\fBwbkgrnd\fR,
\fBbkgrndset\fR,
@@ -39,7 +38,7 @@
.SH SYNOPSIS
.PP
.B #include <curses.h>
-
+.sp
\fBint bkgrnd(\fR\fB const cchar_t *\fR\fIwch\fR\fB);\fR
.br
\fBint wbkgrnd(\fR\fB WINDOW *\fR\fIwin\fR\fB, const cchar_t *\fR\fIwch\fR\fB);\fR
@@ -64,26 +63,26 @@ 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.
-
+.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
The rendition of every character on the screen is changed to
the new background rendition.
-
+.PP
Wherever the former background character
appears, it is changed to the new background character.
.RE
-
+.PP
The \fBgetbkgrnd\fR function returns the given window's current background
character/attribute pair via the \fBwch\fR pointer.
-
+.
.SH NOTES
Note that
\fBbkgrnd\fR,
diff --git a/contrib/ncurses/man/curs_border.3x b/contrib/ncurses/man/curs_border.3x
index c087fad73bcd..3071d2a603ea 100644
--- a/contrib/ncurses/man/curs_border.3x
+++ b/contrib/ncurses/man/curs_border.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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,24 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_border.3x,v 1.15 2002/02/16 22:21:47 tom Exp $
+.\" $Id: curs_border.3x,v 1.18 2006/02/25 21:49:19 tom Exp $
.TH curs_border 3X ""
+.na
+.hy 0
.SH NAME
-\fBborder\fR, \fBwborder\fR, \fBbox\fR,
-\fBhline\fR, \fBwhline\fR,
-\fBvline\fR, \fBwvline\fR,
-\fBmvhline\fR, \fBmvwhline\fR,
-\fBmvvline\fR, \fBmvwvline\fR - create \fBcurses\fR borders, horizontal and vertical lines
+\fBborder\fR,
+\fBwborder\fR,
+\fBbox\fR,
+\fBhline\fR,
+\fBwhline\fR,
+\fBvline\fR,
+\fBwvline\fR,
+\fBmvhline\fR,
+\fBmvwhline\fR,
+\fBmvvline\fR,
+\fBmvwvline\fR - create \fBcurses\fR borders, horizontal and vertical lines
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
.br
@@ -66,6 +76,7 @@
The \fBborder\fR, \fBwborder\fR and \fBbox\fR routines
draw a box around the edges of a window.
Other than the window, each argument is a character with attributes:
+.sp
.RS
\fIls\fR - left side,
.br
@@ -83,8 +94,10 @@ Other than the window, each argument is a character with attributes:
.br
\fIbr\fR - bottom right-hand corner.
.RE
+.PP
If any of these arguments is zero, then the corresponding
default values (defined in \fBcurses.h\fR) are used instead:
+.sp
.RS
\fBACS_VLINE\fR,
.br
@@ -102,16 +115,16 @@ default values (defined in \fBcurses.h\fR) are used instead:
.br
\fBACS_LRCORNER\fR.
.RE
-
+.PP
\fBbox(\fR\fIwin\fR\fB, \fR\fIverch\fR\fB, \fR\fIhorch\fR\fB)\fR is a shorthand
for the following call: \fBwborder(\fR\fIwin\fR\fB,\fR \fIverch\fR\fB,\fR
\fIverch\fR\fB,\fR \fIhorch\fR\fB,\fR \fIhorch\fR\fB, 0, 0, 0, 0)\fR.
-
+.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
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
@@ -119,10 +132,14 @@ long, or as many as fit into the window.
.SH RETURN VALUE
All routines return the integer \fBOK\fR. The SVr4.0 manual says "or a
non-negative integer if \fBimmedok\fR is set", but this appears to be an error.
+.PP
+X/Open does not define any error conditions.
+This implementation returns an error
+if the window pointer is null.
.SH NOTES
The borders generated by these functions are \fIinside\fR borders (this
is also true of SVr4 curses, though the fact is not documented).
-
+.PP
Note that \fBborder\fR and \fBbox\fR may be macros.
.SH PORTABILITY
These functions are described in the XSI Curses standard, Issue 4.
diff --git a/contrib/ncurses/man/curs_border_set.3x b/contrib/ncurses/man/curs_border_set.3x
index ba7a197bf0c7..dbf865385b78 100644
--- a/contrib/ncurses/man/curs_border_set.3x
+++ b/contrib/ncurses/man/curs_border_set.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2004,2005 Free 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_border_set.3x,v 1.3 2002/04/20 16:49:13 tom Exp $
+.\" $Id: curs_border_set.3x,v 1.6 2005/05/15 16:17:37 tom Exp $
.TH curs_border_set 3X ""
+.na
+.hy 0
.SH NAME
-.PP
\fBborder_set\fR,
\fBwborder_set\fR,
\fBbox_set\fR,
@@ -41,6 +42,8 @@
\fBwvline_set\fR,
\fBmvvline_set\fR,
\fBmvwvline_set\fR \- create \fBcurses\fR borders or lines using complex characters and renditions
+.ad
+.hy
.SH SYNOPSIS
.PP
\fB#include <curses.h>\fR
@@ -190,6 +193,8 @@ Upon successful completion, these functions return
\fBOK\fR.
Otherwise, they return
\fBERR\fR.
+.PP
+Functions using a window parameter return an error if it is null.
.SH SEE ALSO
\fBncurses\fR(3X),
\fBcurs_border\fR(3X),
diff --git a/contrib/ncurses/man/curs_clear.3x b/contrib/ncurses/man/curs_clear.3x
index d08e852a27b1..fa7723af4fe8 100644
--- a/contrib/ncurses/man/curs_clear.3x
+++ b/contrib/ncurses/man/curs_clear.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2005 Free 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,15 +26,24 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_clear.3x,v 1.7 1998/03/11 21:12:53 juergen Exp $
+.\" $Id: curs_clear.3x,v 1.10 2005/10/01 19:34:43 tom Exp $
.TH curs_clear 3X ""
+.na
+.hy 0
.SH NAME
-\fBerase\fR, \fBwerase\fR, \fBclear\fR,
-\fBwclear\fR, \fBclrtobot\fR, \fBwclrtobot\fR, \fBclrtoeol\fR,
+\fBerase\fR,
+\fBwerase\fR,
+\fBclear\fR,
+\fBwclear\fR,
+\fBclrtobot\fR,
+\fBwclrtobot\fR,
+\fBclrtoeol\fR,
\fBwclrtoeol\fR - clear all or part of a \fBcurses\fR window
+.ad
+.hy
.SH SYNOPSIS
\fB# include <curses.h>\fR
-
+.sp
\fBint erase(void);\fR
.br
\fBint werase(WINDOW *win);\fR
@@ -54,24 +63,29 @@
.SH DESCRIPTION
The \fBerase\fR and \fBwerase\fR routines copy blanks to every
position in the window, clearing the screen.
-
+.PP
The \fBclear\fR and \fBwclear\fR routines are like \fBerase\fR and
\fBwerase\fR, but they also call \fBclearok\fR, so that the screen is
cleared completely on the next call to \fBwrefresh\fR for that window
and repainted from scratch.
-
+.PP
The \fBclrtobot\fR and \fBwclrtobot\fR routines erase from the cursor to the
end of screen. That is, they erase all lines below the cursor in the window.
Also, the current line to the right of the cursor, inclusive, is erased.
-
+.PP
The \fBclrtoeol\fR and \fBwclrtoeol\fR routines erase the current line
to the right of the cursor, inclusive, to the end of the current line.
-
+.PP
Blanks created by erasure have the current background rendition (as set
by \fBwbkgdset\fR) merged into them.
.SH RETURN VALUE
-All routines return the integer \fBOK\fR. The SVr4.0 manual says "or a
+All routines return the integer \fBOK\fR on success and \fBERR\fP on failure.
+The SVr4.0 manual says "or a
non-negative integer if \fBimmedok\fR is set", but this appears to be an error.
+.PP
+X/Open defines no error conditions.
+In this implementation,
+functions using a window pointer parameter return an error if it is null.
.SH NOTES
Note that \fBerase\fR, \fBwerase\fR, \fBclear\fR, \fBwclear\fR,
\fBclrtobot\fR, and \fBclrtoeol\fR may be macros.
@@ -79,11 +93,18 @@ Note that \fBerase\fR, \fBwerase\fR, \fBclear\fR, \fBwclear\fR,
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
ncurses.
+.PP
+This implementation, and others such as Solaris,
+sets the current position to 0,0 after erasing
+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.
.SH SEE ALSO
\fBcurses\fR(3X), \fBcurs_outopts\fR(3X), \fBcurs_refresh\fR(3X)
.\"#
diff --git a/contrib/ncurses/man/curs_color.3x b/contrib/ncurses/man/curs_color.3x
index 18926d92e6c1..99e63eff136e 100644
--- a/contrib/ncurses/man/curs_color.3x
+++ b/contrib/ncurses/man/curs_color.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2001,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2004,2005 Free 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,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_color.3x,v 1.19 2002/02/16 22:38:32 tom Exp $
+.\" $Id: curs_color.3x,v 1.28 2005/12/18 00:00:37 tom Exp $
.TH curs_color 3X ""
+.na
+.hy 0
.SH NAME
\fBstart_color\fR,
\fBinit_pair\fR,
@@ -37,6 +39,8 @@
\fBcolor_content\fR,
\fBpair_content\fR,
\fBCOLOR_PAIR\fR - \fBcurses\fR color manipulation routines
+.ad
+.hy
.SH SYNOPSIS
\fB# include <curses.h>\fR
.br
@@ -64,7 +68,7 @@ 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.
-
+.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,
@@ -84,7 +88,7 @@ and white), and two global variables, \fBCOLORS\fR and
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.
-
+.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.
@@ -96,18 +100,20 @@ must be between \fB1\fR and \fBCOLOR_PAIRS-1\fR.
.TP 5
-
The value of the second and
-third arguments must be between 0 and \fBCOLORS\fR (the 0 color pair is wired
-to white on black and cannot be changed).
+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.
.PP
If the color-pair was previously
initialized, the screen is refreshed and all occurrences of that color-pair
are changed to the new definition.
-
+.PP
As an extension, ncurses allows you to set color pair 0 via
the \fBassume_default_colors\fR routine, or to specify the use of
default colors (color number \fB-1\fR) if you first invoke the
\fBuse_default_colors\fR routine.
-
+.PP
The \fBinit_color\fR routine changes the definition of a color. It takes four
arguments: the number of the color to be changed followed by three RGB values
(for the amounts of red, green, and blue components). The value of the first
@@ -116,18 +122,18 @@ argument must be between \fB0\fR and \fBCOLORS\fR. (See the section
must be a value between 0 and 1000. When \fBinit_color\fR is used, all
occurrences of that color on the screen immediately change to the new
definition.
-
+.PP
The \fBhas_colors\fR routine requires no arguments. It returns \fBTRUE\fR if
the terminal can manipulate colors; otherwise, it returns \fBFALSE\fR. 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.
-
+.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
@@ -136,7 +142,7 @@ 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).
-
+.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
number, and two addresses of \fBshort\fRs for storing the foreground and the
@@ -147,7 +153,7 @@ to by the second and third arguments are between 0 and \fBCOLORS\fR.
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.
-
+.PP
.nf
\fBCOLOR_BLACK\fR
\fBCOLOR_RED\fR
@@ -161,22 +167,44 @@ background color for all terminals.
.SH RETURN VALUE
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.
+.PP
+X/Open defines no error conditions.
+This implementation will return \fBERR\fR on attempts to
+use color values outside the range 0 to COLORS-1
+(except for the default colors extension),
+or use color pairs outside the range 0 to COLOR_PAIR-1.
+Color values used in \fBinit_color\fP must be in the range 0 to 1000.
+An error is returned from all functions
+if the terminal has not been initialized.
+An error is returned from secondary functions such as \fBinit_pair\fP
+if \fBstart_color\fP was not called.
+.RS
+.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
+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
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
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
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:
.TP 5
-
@@ -201,8 +229,12 @@ 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\fP 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.
.SH SEE ALSO
\fBcurses\fR(3X),
\fBcurs_initscr\fR(3X),
diff --git a/contrib/ncurses/man/curs_delch.3x b/contrib/ncurses/man/curs_delch.3x
index 34bd9ac3e244..70266678d7c6 100644
--- a/contrib/ncurses/man/curs_delch.3x
+++ b/contrib/ncurses/man/curs_delch.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2000,2006 Free 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_delch.3x,v 1.7 2000/07/01 19:55:37 tom Exp $
+.\" $Id: curs_delch.3x,v 1.8 2006/02/25 21:42:57 tom Exp $
.TH curs_delch 3X ""
.SH NAME
\fBdelch\fR,
@@ -35,7 +35,7 @@
\fBmvwdelch\fR - delete character under the cursor in a \fBcurses\fR window
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint delch(void);\fR
.br
\fBint wdelch(WINDOW *win);\fR
diff --git a/contrib/ncurses/man/curs_deleteln.3x b/contrib/ncurses/man/curs_deleteln.3x
index 8b39402d1968..25991391840d 100644
--- a/contrib/ncurses/man/curs_deleteln.3x
+++ b/contrib/ncurses/man/curs_deleteln.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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.7 2000/11/11 20:43:20 Bernhard.Rosenkraenzer Exp $
+.\" $Id: curs_deleteln.3x,v 1.10 2006/02/25 21:49:19 tom Exp $
.TH curs_deleteln 3X ""
.SH NAME
\fBdeleteln\fR,
@@ -37,7 +37,7 @@
\fBwinsertln\fR - delete and insert lines in a \fBcurses\fR window
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint deleteln(void);\fR
.br
\fBint wdeleteln(WINDOW *win);\fR
@@ -54,26 +54,30 @@
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.
-
+.PP
The \fBinsdelln\fR and \fBwinsdelln\fR routines, for positive \fIn\fR, insert
\fIn\fR lines into the specified window above the current line. The \fIn\fR
bottom lines are lost. For negative \fIn\fR, delete \fIn\fR lines (starting
with the one under the cursor), and move the remaining lines up. The bottom
\fIn\fR lines are cleared. The current cursor position remains the same.
-
-The \fBinsertln\fR and \fBwinsertln\fR routines, insert a blank line above the
+.PP
+The \fBinsertln\fR and \fBwinsertln\fR routines insert a blank line above the
current line and the bottom line is lost.
.SH RETURN VALUE
All routines return the integer \fBERR\fR upon failure and an \fBOK\fR (SVr4
specifies only "an integer value other than \fBERR\fR") upon successful
completion.
+.PP
+X/Open defines no error conditions.
+In this implementation,
+if the window parameter is null, an error is returned.
.SH PORTABILITY
These functions are described in the XSI Curses standard, Issue 4. The
standard specifies that they return \fBERR\fR on failure, but specifies no
error conditions.
.SH NOTES
Note that all but \fBwinsdelln\fR may be macros.
-
+.PP
These routines do not require a hardware line delete or insert feature in the
terminal. In fact, they won't use hardware line delete/insert unless
\fBidlok(..., TRUE)\fR has been set on the current window.
diff --git a/contrib/ncurses/man/curs_extend.3x b/contrib/ncurses/man/curs_extend.3x
index dc05b39d1dc7..c053864194c3 100644
--- a/contrib/ncurses/man/curs_extend.3x
+++ b/contrib/ncurses/man/curs_extend.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1999-2000,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1999-2004,2006 Free 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,17 +26,17 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" Author: Thomas E. Dickey <dickey@clark.net> 1999
+.\" Author: Thomas E. Dickey 1999-on
.\"
-.\" $Id: curs_extend.3x,v 1.9 2002/02/16 22:39:04 tom Exp $
+.\" $Id: curs_extend.3x,v 1.15 2006/02/25 21:04:43 tom Exp $
.TH curs_extend 3X ""
.SH NAME
\fBcurses_version\fP,
\fBuse_extended_names\fP \- miscellaneous curses extensions
-
+.
.SH SYNOPSIS
\fB#include <curses.h>\fP
-
+.sp
\fBconst char * curses_version(void);\fP
.br
\fBint use_extended_names(bool enable);\fP
@@ -55,11 +55,11 @@ function controls whether the calling application
is able to use user-defined or nonstandard names
which may be compiled into the terminfo
description, i.e., via the terminfo or termcap interfaces.
-Normally these names are available for use, since the essential descision
+Normally these names are available for use, since the essential decision
is made by using the \fB-x\fP option of \fItic\fP to compile
extended terminal definitions.
However you can disable this feature
-to ensure compatiblity with other implementations of curses
+to ensure compatibility with other implementations of curses.
.SH PORTABILITY
These routines are specific to ncurses. They were not supported on
Version 7, BSD or System V implementations. It is recommended that
@@ -72,6 +72,7 @@ any code depending on them be conditioned using NCURSES_VERSION.
\fBdefine_key\fR(3X),
\fBkeybound\fR(3X),
\fBkeyok\fR(3X),
+\fBnofilter\fR(3X),
\fBresizeterm\fR(3X),
\fBwresize\fR(3X).
.SH AUTHOR
diff --git a/contrib/ncurses/man/curs_get_wch.3x b/contrib/ncurses/man/curs_get_wch.3x
index 26ff2d4c436a..6ecff799b5d6 100644
--- a/contrib/ncurses/man/curs_get_wch.3x
+++ b/contrib/ncurses/man/curs_get_wch.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2003,2006 Free 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_get_wch.3x,v 1.3 2002/05/18 21:48:53 tom Exp $
+.\" $Id: curs_get_wch.3x,v 1.6 2006/02/25 21:47:06 tom Exp $
.TH curs_get_wch 3X ""
.SH NAME
\fBget_wch\fR,
@@ -37,13 +37,13 @@
.SH SYNOPSIS
\fB#include <curses.h>\fR
.sp
-\fBint get_wch(win_t *\fR\fIwch\fR\fB);\fR
+\fBint get_wch(wint_t *\fR\fIwch\fR\fB);\fR
.br
-\fBint wget_wch(WINDOW *\fR\fIwin\fR\fB, win_t *\fR\fIwch\fR\fB);\fR
+\fBint wget_wch(WINDOW *\fR\fIwin\fR\fB, wint_t *\fR\fIwch\fR\fB);\fR
.br
-\fBint mvget_wch(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, win_t *\fR\fIwch\fR\fB);\fR
+\fBint mvget_wch(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwch\fR\fB);\fR
.br
-\fBint mvwget_wch(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, win_t *\fR\fIwch\fR\fB);\fR
+\fBint mvwget_wch(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwch\fR\fB);\fR
.br
\fBint unget_wch(const wchar_t \fR\fIwch\fR\fB);\fR
.SH DESCRIPTION
@@ -64,14 +64,14 @@ or after the first newline (nocbreak mode).
In half-delay mode,
the program waits until the user types a character or the specified
timeout interval has elapsed.
-
+.PP
Unless \fBnoecho\fR has been set,
these routines echo the character into the designated window.
-
+.PP
If the window is not a pad and has been moved or modified since the
last call to \fBwrefresh\fR,
\fBwrefresh\fR will be called before another character is read.
-
+.PP
If \fBkeypad\fR is enabled,
these functions respond to
the pressing of a function key by setting the object pointed to by
@@ -130,7 +130,7 @@ at the same time.
Depending on the state of the tty driver when each character
is typed, the program may produce undesirable results.
.PP
-All functions except \fBwget_wch\fR and \fBunget_wch\fR
+All functions except \fBwget_wch\fR and \fBunget_wch\fR
may be macros.
.SH RETURN VALUES
When
diff --git a/contrib/ncurses/man/curs_get_wstr.3x b/contrib/ncurses/man/curs_get_wstr.3x
index f8fa51d47fcb..4286c78b0d2a 100644
--- a/contrib/ncurses/man/curs_get_wstr.3x
+++ b/contrib/ncurses/man/curs_get_wstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2005,2006 Free 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,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_get_wstr.3x,v 1.2 2002/05/18 21:48:15 tom Exp $
+.\" $Id: curs_get_wstr.3x,v 1.6 2006/02/25 21:49:19 tom Exp $
.TH curs_get_wstr 3X ""
+.na
+.hy 0
.SH NAME
\fBget_wstr\fR,
\fBgetn_wstr\fR,
@@ -37,10 +39,12 @@
\fBmvgetn_wstr\fR,
\fBmvwget_wstr\fR,
\fBmvwgetn_wstr\fR \- get an array of wide characters from a curses terminal keyboard
+.ad
+.hy
.SH SYNOPSIS
.nf
\fB#include <curses.h>\fR
-
+.sp
\fBint get_wstr(wint_t *\fR\fIwstr\fR\fB);\fR
.br
\fBint getn_wstr(wint_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
@@ -68,22 +72,22 @@ An end-of-file condition is represented by \fBWEOF\fR, as defined in \fB<wchar.h
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
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,
backspace is echoed as deletion of the previous character (typically a left
motion).
-
+.PP
The effect of
\fBwget_wstr\fR
is as though a series of
calls to
\fBwget_wch\fR
were made.
-
+.PP
The effect of
\fBmvget_wstr\fR
is as though a call to
@@ -92,7 +96,7 @@ and then a series of calls to
\fBget_wch\fR
were
made.
-
+.PP
The effect of
\fBmvwget_wstr\fR
is as though a call to
@@ -100,7 +104,7 @@ is as though a call to
and then a series of calls to
\fBwget_wch\fR
were made.
-
+.PP
The
\fBgetn_wstr\fR,
\fBmvgetn_wstr\fR,
@@ -135,14 +139,21 @@ The use of
\fBmvgetn_wstr\fR,
\fBmvwgetn_wstr\fR, or
\fBwgetn_wstr\fR, respectively, is recommended.
-
+.PP
These functions cannot return \fBKEY_\fR values because there
is no way to distinguish a \fBKEY_\fR value from a valid \fBwchar_t\fR value.
-
+.PP
All of these routines except \fBwgetn_wstr\fR may be macros.
.SH RETURN VALUES
All of these functions return \fBOK\fR upon successful completion.
Otherwise, they return \fBERR\fR.
+.PP
+Functions using a window parameter return an error if it is null.
+.RS
+.TP 5
+\fBwgetn_wstr\fP
+returns an error if the associated call to \fBwget_wch\fP failed.
+.RE
.SH PORTABILITY
These functions are described in The Single Unix Specification, Version 2.
No error conditions are defined.
@@ -151,6 +162,9 @@ or if the lower-level \fBwget_wch\fR call returns an ERR.
In the latter case,
an ERR return without other data is treated as an end-of-file condition,
and the returned array contains a \fBWEOF\fR followed by a null \fBwchar_t\fR.
+.PP
+X/Open curses documents these functions to pass an array of \fBwchar_t\fR,
+but all of the vendors implement this using \fBwint_t\fR.
.SH SEE ALSO
Functions:
\fBcurses\fR(3X),
diff --git a/contrib/ncurses/man/curs_getcchar.3x b/contrib/ncurses/man/curs_getcchar.3x
index 2dfa10b7967a..91b996197c58 100644
--- a/contrib/ncurses/man/curs_getcchar.3x
+++ b/contrib/ncurses/man/curs_getcchar.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2001,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 2001-2003,2006 Free 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_getcchar.3x,v 1.6 2002/03/24 01:08:55 tom Exp $
+.\" $Id: curs_getcchar.3x,v 1.8 2006/07/15 22:51:07 wcmbrine Exp $
.TH curs_getcchar 3X ""
.SH NAME
\fBgetcchar\fP,
@@ -108,7 +108,7 @@ The wide-character string pointed to by \fIwch\fP.
The string must be L'\\0' terminated,
contain at most one character with strictly positive width,
which must be the first,
-and contain no characters of negative width.
+and contain no characters of negative width.
.SH NOTES
.PP
The \fIopts\fP argument is reserved for future use.
@@ -121,7 +121,7 @@ If \fIwcval\fP is constructed by any other means, the effect is unspecified.
.PP
When \fIwch\fP is a null pointer,
\fBgetcchar\fP returns the number of wide characters referenced by
-\fIwcval\fP, including the null terminator.
+\fIwcval\fP.
.PP
When \fIwch\fP is not a null pointer,
\fBgetcchar\fP returns \fBOK\fP upon successful completion,
diff --git a/contrib/ncurses/man/curs_getch.3x b/contrib/ncurses/man/curs_getch.3x
index 73e1a29679b1..71fed5f7b60d 100644
--- a/contrib/ncurses/man/curs_getch.3x
+++ b/contrib/ncurses/man/curs_getch.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2001,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getch.3x,v 1.21 2002/03/17 14:36:21 tom Exp $
+.\" $Id: curs_getch.3x,v 1.30 2006/12/02 17:02:53 tom Exp $
.TH curs_getch 3X ""
+.na
+.hy 0
.SH NAME
\fBgetch\fR,
\fBwgetch\fR,
@@ -36,9 +38,11 @@
\fBmvwgetch\fR,
\fBungetch\fR,
\fBhas_key\fR \- get (or push back) characters from \fBcurses\fR terminal keyboard
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.PP
\fBint getch(void);\fR
.br
\fBint wgetch(WINDOW *win);\fR
@@ -63,7 +67,7 @@ or after the first newline (nocbreak mode).
In half-delay mode,
the program waits until a character is typed or the
specified timeout has been reached.
-
+.PP
Unless \fBnoecho\fR has been set,
then the character will also be echoed into the
designated window according to the following rules:
@@ -73,19 +77,19 @@ as if \fBdelch\fR had been called.
If the character value is any other \fBKEY_\fR define, the user is alerted
with a \fBbeep\fR call.
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.
-
+.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
+of 8-bit characters whose names begin with \fBKEY_\fR. Thus, a variable
intended to hold the return value of a function key must be of short size or
larger.
-
+.PP
When a character that could be the beginning of a function key is received
(which, on modern terminals, means an escape character),
\fBcurses\fR sets a timer.
@@ -94,11 +98,11 @@ time, the character is passed through;
otherwise, the function key value is returned.
For this reason, many terminals experience a delay between the time
a user presses the escape key and the escape is returned to the program.
-
+.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.
@@ -110,7 +114,6 @@ center tab(/) ;
l l
l l .
\fIName\fR/\fIKey\fR \fIname\fR
-
KEY_BREAK/Break key
KEY_DOWN/The four arrow keys ...
KEY_UP
@@ -143,7 +146,7 @@ KEY_ENTER/Enter or send
KEY_SRESET/Soft (partial) reset
KEY_RESET/Reset or hard reset
KEY_PRINT/Print or copy
-KEY_LL/Home down or bottom (lower left).
+KEY_LL/Home down or bottom (lower left)
KEY_A1/Upper left of keypad
KEY_A3/Upper right of keypad
KEY_B2/Center of keypad
@@ -208,7 +211,7 @@ KEY_SUNDO/Shifted undo key
KEY_SUSPEND/Suspend key
KEY_UNDO/Undo key
.TE
-
+.PP
Keypad is arranged like this:
.sp
.TS
@@ -222,34 +225,50 @@ c c c .
The \fBhas_key\fR routine takes a key value from the above list, and
returns TRUE or FALSE 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
.SH RETURN VALUE
All routines return the integer \fBERR\fR upon failure and an integer value
other than \fBERR\fR (\fBOK\fR in the case of ungetch()) upon successful
completion.
+.RS
+.TP 5
+\fBungetch\fP
+returns an error
+if there is no more room in the FIFO.
+.TP 5
+\fBwgetch\fP
+returns an error
+if the window pointer is null, or
+if its timeout expires without having any data.
+.RE
.SH NOTES
Use of the escape key by a programmer for a single character function is
discouraged, as it will cause a delay of up to one second while the
keypad code looks for a following function-key sequence.
-
+.PP
Note that some keys may be the same as commonly used control
-keys, e.g., KEY_ENTER versus control/M, KEY_BACKSPACE versus control/H.
+keys, e.g., \fBKEY_ENTER\fP versus control/M, \fBKEY_BACKSPACE\fP versus control/H.
Some curses implementations may differ according to whether they
treat these control keys specially (and ignore the terminfo), or
use the terminfo definitions.
\fBNcurses\fR uses the terminfo definition.
-If it says that KEY_ENTER is control/M, \fBgetch\fR, will return KEY_ENTER
+If it says that \fBKEY_ENTER\fP is control/M,
+\fBgetch\fR will return \fBKEY_ENTER\fP
when you press control/M.
-
+.PP
When using \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR, or
\fBmvwgetch\fR, nocbreak mode (\fBnocbreak\fR) and echo mode
(\fBecho\fR) should not be used at the same time.
Depending on the
state of the tty driver when each character is typed, the program may
produce undesirable results.
-
+.PP
Note that \fBgetch\fR, \fBmvgetch\fR, and \fBmvwgetch\fR may be macros.
-
+.PP
Historically, the set of keypad macros was largely defined by the extremely
function-key-rich keyboard of the AT&T 7300, aka 3B1, aka Safari 4.
Modern
@@ -266,27 +285,27 @@ They
read single-byte characters only.
The standard specifies that they return
\fBERR\fR on failure, but specifies no error conditions.
-
+.PP
The echo behavior of these functions on input of \fBKEY_\fR or backspace
characters was not specified in the SVr4 documentation.
This description is
adopted from the XSI Curses standard.
-
+.PP
The behavior of \fBgetch\fR and friends in the presence of handled signals is
unspecified in the SVr4 and XSI Curses documentation.
Under historical curses
implementations, it varied depending on whether the operating system's
implementation of handled signal receipt interrupts a \fBread\fR(2) call in
progress or not, and also (in some implementations) depending on whether an
-input timeout or non-blocking mode hsd been set.
-
+input timeout or non-blocking mode has been set.
+.PP
Programmers concerned about portability should be prepared for either of two
cases: (a) signal receipt does not interrupt \fBgetch\fR; (b) signal receipt
interrupts \fBgetch\fR and causes it to return ERR with \fBerrno\fR set to
\fBEINTR\fR.
Under the \fBncurses\fR implementation, handled signals never
interrupt \fBgetch\fR.
-
+.PP
The \fBhas_key\fR function is unique to \fBncurses\fR.
We recommend that
any code using it be conditionalized on the \fBNCURSES_VERSION\fR feature macro.
@@ -295,8 +314,12 @@ any code using it be conditionalized on the \fBNCURSES_VERSION\fR feature macro.
\fBcurs_inopts\fR(3X),
\fBcurs_mouse\fR(3X),
\fBcurs_move\fR(3X),
-\fBcurs_refresh\fR(3X).
+\fBcurs_refresh\fR(3X),
\fBresizeterm\fR(3X).
+.PP
+Comparable functions in the wide-character (ncursesw) library are
+described in
+\fBcurs_get_wch\fR(3X).
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/curs_getstr.3x b/contrib/ncurses/man/curs_getstr.3x
index 1a32a0be1aeb..f131765043a1 100644
--- a/contrib/ncurses/man/curs_getstr.3x
+++ b/contrib/ncurses/man/curs_getstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000,2001 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2005 Free 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,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getstr.3x,v 1.11 2002/04/13 22:14:30 tom Exp $
+.\" $Id: curs_getstr.3x,v 1.15 2006/01/12 00:30:58 tom Exp $
.TH curs_getstr 3X ""
+.na
+.hy 0
.SH NAME
\fBgetstr\fR,
\fBgetnstr\fR,
@@ -37,9 +39,11 @@
\fBmvgetnstr\fR,
\fBmvwgetstr\fR,
\fBmvwgetnstr\fR - accept character strings from \fBcurses\fR terminal keyboard
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint getstr(char *str);\fR
.br
\fBint getnstr(char *str, int n);\fR
@@ -61,17 +65,17 @@ 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.
-
+.PP
\fBwgetnstr\fR reads at most \fIn\fR characters, thus preventing a possible
overflow of the input buffer. Any attempt to enter more characters (other
than the terminating newline or carriage return) causes a beep. Function
keys also cause a beep and are ignored. The \fBgetnstr\fR function reads
from the \fIstdscr\fR default window.
-
+.PP
The user's erase and kill characters are interpreted. If keypad
mode is on for the window, \fBKEY_LEFT\fR and \fBKEY_BACKSPACE\fR
are both considered equivalent to the user's kill character.
-
+.PP
Characters input are echoed only if \fBecho\fR is currently on. In that case,
backspace is echoed as deletion of the previous character (typically a left
motion).
@@ -79,6 +83,17 @@ motion).
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
+X/Open defines no error conditions.
+.PP
+In this implementation,
+these functions return an error
+if the window pointer is null, or
+if its timeout expires without having any data.
+.PP
+This implementation provides an extension as well.
+If a SIGWINCH interrupts the function, it will return \fBKEY_RESIZE\fP
+rather than \fBOK\fP or \fBERR\fP.
.SH NOTES
Note that \fBgetstr\fR, \fBmvgetstr\fR, and \fBmvwgetstr\fR may be macros.
.SH PORTABILITY
@@ -87,14 +102,14 @@ 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.
-
+.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
+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.
.SH SEE ALSO
diff --git a/contrib/ncurses/man/curs_getyx.3x b/contrib/ncurses/man/curs_getyx.3x
index 820bf99c5327..8fe53dc71972 100644
--- a/contrib/ncurses/man/curs_getyx.3x
+++ b/contrib/ncurses/man/curs_getyx.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2006 Free 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,16 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getyx.3x,v 1.6 1998/03/11 21:12:53 juergen Exp $
+.\" $Id: curs_getyx.3x,v 1.13 2006/05/27 20:28:05 tom Exp $
.TH curs_getyx 3X ""
.SH NAME
-\fBgetyx\fR, \fBgetparyx\fR, \fBgetbegyx\fR,
+\fBgetyx\fR,
+\fBgetparyx\fR,
+\fBgetbegyx\fR,
\fBgetmaxyx\fR - get \fBcurses\fR cursor and window coordinates
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBvoid getyx(WINDOW *win, int y, int x);\fR
.br
\fBvoid getparyx(WINDOW *win, int y, int x);\fR
@@ -45,23 +47,40 @@
.SH DESCRIPTION
The \fBgetyx\fR macro places the current cursor position of the given window in
the two integer variables \fIy\fR and \fIx\fR.
-
+.PP
If \fIwin\fR is a subwindow, the \fBgetparyx\fR macro places the beginning
coordinates of the subwindow relative to the parent window into two integer
-variables \fIy\fR and \fIx\fR. Otherwise, \fB-1\fR is placed into \fIy\fR and
-\fIx\fR.
-
+variables \fIy\fR and \fIx\fR.
+Otherwise, \fB-1\fR is placed into \fIy\fR and \fIx\fR.
+.PP
Like \fBgetyx\fR, the \fBgetbegyx\fR and \fBgetmaxyx\fR macros store
the current beginning coordinates and size of the specified window.
.SH RETURN VALUE
-The return values of these macros are undefined (\fIi\fR.\fIe\fR.,
-they should not be used as the right-hand side of assignment
-statements).
+The return values of these macros are undefined (i.e.,
+they should not be used as the right-hand side of assignment statements).
.SH NOTES
-All of these interfaces are macros and that "\fB&\fR" is not
-necessary before the variables \fIy\fR and \fIx\fR.
+All of these interfaces are macros.
+A "\fB&\fR" is not necessary before the variables \fIy\fR and \fIx\fR.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
+The
+\fBgetyx\fR,
+\fBgetparyx\fR,
+\fBgetbegyx\fR and
+\fBgetmaxyx\fR
+macros are described in the XSI Curses standard, Issue 4.
+.PP
+This implementation also provides
+\fBgetbegx\fR,
+\fBgetbegy\fR,
+\fBgetcurx\fR,
+\fBgetcury\fR,
+\fBgetmaxx\fR,
+\fBgetmaxy\fR,
+\fBgetparx\fR and
+\fBgetpary\fR
+for compatibility with older versions of curses.
+X/Open does not define a corresponding \fBgetcuryx\fP function,
+though that would be needed to make references to the WINDOW structure opaque.
.SH SEE ALSO
\fBcurses\fR(3X)
.\"#
diff --git a/contrib/ncurses/man/curs_in_wch.3x b/contrib/ncurses/man/curs_in_wch.3x
index 668595c6f3ed..8709d130f180 100644
--- a/contrib/ncurses/man/curs_in_wch.3x
+++ b/contrib/ncurses/man/curs_in_wch.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002,2006 Free 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_in_wch.3x,v 1.1 2002/03/10 15:08:57 tom Exp $
+.\" $Id: curs_in_wch.3x,v 1.2 2006/02/25 21:42:22 tom Exp $
.TH curs_in_wch 3X ""
.SH NAME
\fBin_wch\fR,
@@ -35,7 +35,7 @@
\fBwin_wch\fR - extract a complex character and rendition from a window
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint in_wch(cchar_t *\fR\fIwcval\fR\fB);\fR
.br
\fBint mvin_wch(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwcval\fR\fB);\fR
diff --git a/contrib/ncurses/man/curs_in_wchstr.3x b/contrib/ncurses/man/curs_in_wchstr.3x
index 0012789f70fb..b04a1f54cd76 100644
--- a/contrib/ncurses/man/curs_in_wchstr.3x
+++ b/contrib/ncurses/man/curs_in_wchstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2005,2006 Free 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,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_in_wchstr.3x,v 1.2 2002/05/18 21:48:30 tom Exp $
+.\" $Id: curs_in_wchstr.3x,v 1.6 2006/12/02 17:03:07 tom Exp $
.TH curs_in_wchstr 3X ""
+.na
+.hy 0
.SH NAME
\fBin_wchstr\fR,
\fBin_wchnstr\fR,
@@ -37,10 +39,12 @@
\fBmvin_wchnstr\fR,
\fBmvwin_wchstr\fR,
\fBmvwin_wchnstr\fR \- get an array of complex characters and renditions from a curses window
+.ad
+.hy
.SH SYNOPSIS
.nf
\fB#include <curses.h>\fR
-
+.sp
\fBint in_wchstr(cchar_t *\fR\fIwchstr\fR\fB);\fR
.br
\fBint in_wchnstr(cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR
@@ -106,9 +110,10 @@ returning ERR in that case.
.SH SEE ALSO
Functions:
\fBcurses\fR(3X),
-\fBcurs_in_wch\fR(3X)
+\fBcurs_in_wch\fR(3X),
\fBcurs_instr\fR(3X),
\fBcurs_inwstr\fR(3X)
+\fBcurs_inchstr\fR(3X)
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/curs_inch.3x b/contrib/ncurses/man/curs_inch.3x
index bcc8d6f85c60..3091b9c0e6ae 100644
--- a/contrib/ncurses/man/curs_inch.3x
+++ b/contrib/ncurses/man/curs_inch.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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: curs_inch.3x,v 1.11 1998/11/29 01:04:34 Rick.Ohnemus Exp $
+.\" $Id: curs_inch.3x,v 1.13 2006/12/02 16:58:55 tom Exp $
.TH curs_inch 3X ""
.SH NAME
\fBinch\fR, \fBwinch\fR, \fBmvinch\fR, \fBmvwinch\fR
- get a character and attributes from a \fBcurses\fR window
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBchtype inch(void);\fR
.br
\fBchtype winch(WINDOW *win);\fR
@@ -49,10 +49,10 @@ 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.
-
+.
.SS Attributes
The following bit-masks may be AND-ed with characters returned by \fBwinch\fR.
-
+.
.TS
l l .
\fBA_CHARTEXT\fR Bit-mask to extract character
@@ -65,6 +65,10 @@ Note that all of these routines may be macros.
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).
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/curs_inchstr.3x b/contrib/ncurses/man/curs_inchstr.3x
index 60f9d566e9fa..18c21dc3190d 100644
--- a/contrib/ncurses/man/curs_inchstr.3x
+++ b/contrib/ncurses/man/curs_inchstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inchstr.3x,v 1.8 2000/07/01 20:16:18 tom Exp $
+.\" $Id: curs_inchstr.3x,v 1.12 2006/12/02 17:00:58 tom Exp $
.TH curs_inchstr 3X ""
+.na
+.hy 0
.SH NAME
\fBinchstr\fR,
\fBinchnstr\fR,
@@ -37,9 +39,11 @@
\fBmvinchnstr\fR,
\fBmvwinchstr\fR,
\fBmvwinchnstr\fR - get a string of characters (and attributes) from a \fBcurses\fR window
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint inchstr(chtype *chstr);\fR
.br
\fBint inchnstr(chtype *chstr, int n);\fR
@@ -69,6 +73,11 @@ in the \fIchstr\fR [see \fBcurs_inch\fR(3X)].
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.
.SH NOTES
Note that all routines except \fBwinchnstr\fR may be macros. SVr4 does not
document whether the result string is 0-terminated; it does not document
@@ -80,6 +89,10 @@ more specific than the SVr4 documentation on the trailing 0. It does specify
that the successful return of the functions is \fBOK\fR.
.SH SEE ALSO
\fBcurses\fR(3X), \fBcurs_inch\fR(3X).
+.PP
+Comparable functions in the wide-character (ncursesw) library are
+described in
+\fBcurs_in_wchstr\fR(3X).
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/curs_initscr.3x b/contrib/ncurses/man/curs_initscr.3x
index daa5e1e822de..1a865f94ec08 100644
--- a/contrib/ncurses/man/curs_initscr.3x
+++ b/contrib/ncurses/man/curs_initscr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2005 Free 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,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_initscr.3x,v 1.10 2000/07/08 12:47:39 tom Exp $
+.\" $Id: curs_initscr.3x,v 1.14 2005/05/15 16:18:01 tom Exp $
.TH curs_initscr 3X ""
+.na
+.hy 0
.SH NAME
\fBinitscr\fR,
\fBnewterm\fR,
@@ -35,16 +37,18 @@
\fBisendwin\fR,
\fBset_term\fR,
\fBdelscreen\fR - \fBcurses\fR screen initialization and manipulation routines
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBWINDOW *initscr(void);\fR
.br
\fBint endwin(void);\fR
.br
\fBbool isendwin(void);\fR
.br
-\fBSCREEN *newterm(const char *type, FILE *outfd, FILE *infd);\fR
+\fBSCREEN *newterm(char *type, FILE *outfd, FILE *infd);\fR
.br
\fBSCREEN *set_term(SCREEN *new);\fR
.br
@@ -56,13 +60,13 @@ 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.
-
+.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.
-
+.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
@@ -76,23 +80,23 @@ is \fBNULL\fR, \fB$TERM\fR will be used). 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
temporary escape causes the program to resume visual mode.
-
+.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.
-
+.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.
-
+.PP
The \fBdelscreen\fR routine frees storage associated with the
\fBSCREEN\fR data structure. The \fBendwin\fR routine does not do
this, so \fBdelscreen\fR should be called after \fBendwin\fR if a
@@ -100,18 +104,22 @@ particular \fBSCREEN\fR is no longer needed.
.SH RETURN VALUE
\fBendwin\fR returns the integer \fBERR\fR upon failure and \fBOK\fR
upon successful completion.
-
+.PP
Routines that return pointers always return \fBNULL\fR on error.
+.PP
+X/Open defines no error conditions.
+In this implementation
+\fBendwin\fP returns an error if the terminal was not initialized.
.SH NOTES
Note that \fBinitscr\fR and \fBnewterm\fR may be macros.
.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.
-
+.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
+It is safe but redundant to check the return value of \fBinitscr\fR
in XSI Curses.
.SH SEE ALSO
\fBcurses\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_refresh\fR(3X),
diff --git a/contrib/ncurses/man/curs_inopts.3x b/contrib/ncurses/man/curs_inopts.3x
index 1fc6a820a603..7b5a17b8f125 100644
--- a/contrib/ncurses/man/curs_inopts.3x
+++ b/contrib/ncurses/man/curs_inopts.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2005 Free 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,17 +26,33 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inopts.3x,v 1.8 1998/03/11 21:12:53 juergen Exp $
+.\" $Id: curs_inopts.3x,v 1.13 2005/05/15 16:18:07 tom Exp $
.TH curs_inopts 3X ""
+.na
+.hy 0
.SH NAME
-\fBcbreak\fR, \fBnocbreak\fR, \fBecho\fR,
-\fBnoecho\fR, \fBhalfdelay\fR, \fBintrflush\fR, \fBkeypad\fR,
-\fBmeta\fR, \fBnodelay\fR, \fBnotimeout\fR, \fBraw\fR, \fBnoraw\fR,
-\fBnoqiflush\fR, \fBqiflush\fR, \fBtimeout\fR, \fBwtimeout\fR,
+\fBcbreak\fR,
+\fBnocbreak\fR,
+\fBecho\fR,
+\fBnoecho\fR,
+\fBhalfdelay\fR,
+\fBintrflush\fR,
+\fBkeypad\fR,
+\fBmeta\fR,
+\fBnodelay\fR,
+\fBnotimeout\fR,
+\fBraw\fR,
+\fBnoraw\fR,
+\fBnoqiflush\fR,
+\fBqiflush\fR,
+\fBtimeout\fR,
+\fBwtimeout\fR,
\fBtypeahead\fR - \fBcurses\fR input options
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.PP
\fBint cbreak(void);\fR
.br
\fBint nocbreak(void);\fR
@@ -78,14 +94,14 @@ 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)
mode.
-
+.PP
Initially the terminal may or may not be in \fBcbreak\fR mode, as the mode is
inherited; therefore, a program should call \fBcbreak\fR or \fBnocbreak\fR
explicitly. Most interactive programs using \fBcurses\fR set the \fBcbreak\fR
mode. Note that \fBcbreak\fR overrides \fBraw\fR.
[See \fBcurs_getch\fR(3X) for a
discussion of how these routines interact with \fBecho\fR and \fBnoecho\fR.]
-
+.PP
The \fBecho\fR and \fBnoecho\fR routines control whether characters typed by
the user are echoed by \fBgetch\fR as they are typed. Echoing by the tty
driver is always disabled, but initially \fBgetch\fR is in echo mode, so
@@ -95,14 +111,14 @@ 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.]
-
+.PP
The \fBhalfdelay\fR routine is used for half-delay mode, which is similar to
\fBcbreak\fR mode in that characters typed by the user are immediately
available to the program. However, after blocking for \fItenths\fR tenths of
seconds, ERR is returned if nothing has been typed. The value of \fBtenths\fR
must be a number between 1 and 255. Use \fBnocbreak\fR to leave half-delay
mode.
-
+.PP
If the \fBintrflush\fR option is enabled, (\fIbf\fR is \fBTRUE\fR), when an
interrupt key is pressed on the keyboard (interrupt, break, quit) all output in
the tty driver queue will be flushed, giving the effect of faster response to
@@ -110,7 +126,7 @@ the interrupt, but causing \fBcurses\fR to have the wrong idea of what is on
the screen. Disabling (\fIbf\fR is \fBFALSE\fR), the option prevents the
flush. The default for the option is inherited from the tty driver settings.
The window argument is ignored.
-
+.PP
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
@@ -121,30 +137,30 @@ 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.
-
+.PP
Initially, whether the terminal returns 7 or 8 significant bits on
input depends on the control mode of the tty driver [see termio(7)].
To force 8 bits to be returned, invoke \fBmeta\fR(\fIwin\fR,
\fBTRUE\fR); this is equivalent, under POSIX, to setting the CS8 flag
on the terminal. To force 7 bits to be returned, invoke
\fBmeta\fR(\fIwin\fR, \fBFALSE\fR); this is equivalent, under POSIX,
-to setting the CS8 flag on the terminal. The window argument,
+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.
-
+.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
(\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
purpose of the timeout is to differentiate between sequences received
from a function key and those typed by a user.
-
+.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
@@ -152,7 +168,7 @@ raw mode, the interrupt, quit, suspend, and flow control characters are all
passed through uninterpreted, instead of generating a signal. The behavior of
the BREAK key depends on other bits in the tty driver that are not set by
\fBcurses\fR.
-
+.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
@@ -160,18 +176,18 @@ output queues associated with the \fBINTR\fR, \fBQUIT\fR and
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.
-
+.PP
The \fBtimeout\fR and \fBwtimeout\fR routines set blocking or
non-blocking read for a given window. If \fIdelay\fR is negative,
-blocking read is used (\fIi\fR.\fIe\fR., waits indefinitely for
+blocking read is used (i.e., waits indefinitely for
input). If \fIdelay\fR is zero, then non-blocking read is used
-(\fIi\fR.\fIe\fR., read returns \fBERR\fR if no input is waiting). If
+(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).
-
+.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
@@ -186,20 +202,32 @@ The \fBtypeahead\fR routine specifies that the file descriptor
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.
+.PP
+X/Open does not define any error conditions.
+In this implementation,
+functions with a window parameter will return an error if it is null.
+Any function will also return an error if the terminal was not initialized.
+Also,
+.RS
+.TP 5
+\fBhalfdelay\fP
+returns an error
+if its parameter is outside the range 1..255.
+.RE
.SH PORTABILITY
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
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.
.SH NOTES
Note that \fBecho\fR, \fBnoecho\fR, \fBhalfdelay\fR, \fBintrflush\fR,
\fBmeta\fR, \fBnodelay\fR, \fBnotimeout\fR, \fBnoqiflush\fR,
\fBqiflush\fR, \fBtimeout\fR, and \fBwtimeout\fR may be macros.
-
+.PP
The \fBnoraw\fR and \fBnocbreak\fR calls follow historical practice in that
they attempt to restore to normal (`cooked') mode from raw and cbreak modes
respectively. Mixing raw/noraw and cbreak/nocbreak calls leads to tty driver
diff --git a/contrib/ncurses/man/curs_ins_wch.3x b/contrib/ncurses/man/curs_ins_wch.3x
index 23cf0999572a..bb8a9a34afa9 100644
--- a/contrib/ncurses/man/curs_ins_wch.3x
+++ b/contrib/ncurses/man/curs_ins_wch.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002,2006 Free 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_ins_wch.3x,v 1.2 2002/03/10 23:43:27 tom Exp $
+.\" $Id: curs_ins_wch.3x,v 1.3 2006/02/25 21:42:22 tom Exp $
.TH curs_ins_wch 3X ""
.SH NAME
\fBins_wch\fR,
@@ -35,7 +35,7 @@
\fBwins_wch\fR \- insert a complex character and rendition into a window
.SH SYNOPSIS
#include <curses.h>
-
+.sp
\fBint ins_wch(const cchar_t *\fR\fIwch\fR\fB);\fR
.br
\fBint wins_wch(WINDOW *\fR\fIwin, const cchar_t *\fR\fIwch\fR\fB);\fR
diff --git a/contrib/ncurses/man/curs_ins_wstr.3x b/contrib/ncurses/man/curs_ins_wstr.3x
index 197f30f5cd7d..0c153c4c67e4 100644
--- a/contrib/ncurses/man/curs_ins_wstr.3x
+++ b/contrib/ncurses/man/curs_ins_wstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002,2005 Free 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,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_ins_wstr.3x,v 1.2 2002/03/10 23:43:27 tom Exp $
+.\" $Id: curs_ins_wstr.3x,v 1.4 2005/05/15 17:02:54 tom Exp $
.TH curs_ins_wstr 3X ""
+.na
+.hy 0
.SH NAME
\fBins_wstr\fR,
\fBins_nwstr\fR,
@@ -37,10 +39,12 @@
\fBmvins_nwstr\fR,
\fBmvwins_wstr\fR,
\fBmvwins_nwstr\fR \- insert a wide-character string into a curses window
+.ad
+.hy
.SH SYNOPSIS
.nf
\fB#include <curses.h>\fR
-
+.sp
\fBint ins_wstr(const wchar_t *\fR\fIwstr);\fR
.br
\fBint ins_nwstr(const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR
@@ -69,7 +73,7 @@ The cursor position does not change
The four routines with \fIn\fR as the last argument
insert a leading substring of at most \fIn\fR \fBwchar_t\fR characters.
If \fIn\fR is less than 1, the entire string is inserted.
-
+.PP
If a character in \fIwstr\fR is a tab, newline, carriage return or
backspace, the cursor is moved appropriately within the window.
A newline also does a \fBclrtoeol\fR before moving.
@@ -83,7 +87,7 @@ but instead returns a character in the ^-representation
of the control character.
.SH NOTES
Note that all but wins_nwstr may be macros.
-
+.PP
If the first character in the string is a nonspacing character, these
functions will fail.
XSI does not define what will happen if a nonspacing character follows
diff --git a/contrib/ncurses/man/curs_insch.3x b/contrib/ncurses/man/curs_insch.3x
index 8546cf530e67..78ab5a59c89b 100644
--- a/contrib/ncurses/man/curs_insch.3x
+++ b/contrib/ncurses/man/curs_insch.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2006 Free 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_insch.3x,v 1.7 2000/07/01 19:57:21 tom Exp $
+.\" $Id: curs_insch.3x,v 1.10 2006/12/02 17:01:50 tom Exp $
.TH curs_insch 3X ""
.SH NAME
\fBinsch\fR,
@@ -35,7 +35,7 @@
\fBmvwinsch\fR - insert a character before cursor in a \fBcurses\fR window
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint insch(chtype ch);\fR
.br
\fBint winsch(WINDOW *win, chtype ch);\fR
@@ -45,7 +45,7 @@
\fBint mvwinsch(WINDOW *win, int y, int x, chtype ch);\fR
.br
.SH DESCRIPTION
-These routines, insert the character \fIch\fR before the character under the
+These routines insert the character \fIch\fR before the character under the
cursor. All characters to the right of the cursor are moved one space to the
right, with the possibility of the rightmost character on the line being lost.
The insertion operation does not change the cursor position.
@@ -56,12 +56,16 @@ completion, unless otherwise noted in the preceding routine descriptions.
.SH NOTES
These routines do not necessarily imply use of a hardware insert character
feature.
-
+.PP
Note that \fBinsch\fR, \fBmvinsch\fR, and \fBmvwinsch\fR 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_ins_wch\fR(3X).
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/curs_insstr.3x b/contrib/ncurses/man/curs_insstr.3x
index ed1e13eaecb0..6a5d312970f6 100644
--- a/contrib/ncurses/man/curs_insstr.3x
+++ b/contrib/ncurses/man/curs_insstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000,2001 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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_insstr.3x,v 1.12 2001/11/03 19:59:03 tom Exp $
+.\" $Id: curs_insstr.3x,v 1.17 2006/02/25 21:49:19 tom Exp $
.TH curs_insstr 3X ""
.SH NAME
\fBinsstr\fR,
@@ -57,36 +57,42 @@
\fBint mvwinsnstr(WINDOW *win, int y, int x, const char *str, int n);\fR
.br
.SH DESCRIPTION
-These routines insert a character string (as many characters as will fit on the
-line) before the character under the cursor. All characters to the right of
-the cursor are shifted right, with the possibility of the rightmost characters
-on the line being lost. The cursor position does not change (after moving to
-\fIy\fR, \fIx\fR, if specified). The four routines with \fIn\fR as the last
-argument insert a leading substring of at most \fIn\fR characters. If
-\fIn\fR<=0, then the entire string is inserted.
-
-If a character in \fIstr\fR is a tab, newline, carriage return or
-backspace, the cursor is moved appropriately within the window. A
-newline also does a \fBclrtoeol\fR before moving. Tabs are considered
-to be at every eighth column. If a character in \fIstr\fR is another
-control character, it is drawn in the \fB^\fR\fIX\fR notation.
-Calling \fBwinch\fR after adding a control character (and moving to
-it, if necessary) does not return the control character, but instead
-returns a character in the ^-representation of the control character.
+These routines insert a character string
+(as many characters as will fit on the line)
+before the character under the cursor.
+All characters to the right of the cursor are shifted right
+with the possibility of the rightmost characters on the line being lost.
+The cursor position does not change
+(after moving to \fIy\fR, \fIx\fR, if specified).
+The functions with \fIn\fR as the last argument
+insert a leading substring of at most \fIn\fR characters.
+If \fIn\fR<=0, then the entire string is inserted.
+.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.
+.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.
.SH NOTES
Note that all but \fBwinsnstr\fR may be macros.
.SH PORTABILITY
These functions are described in the XSI Curses standard, Issue 4, which adds
-const qualifiers to the arguments. The XSI Curses error conditions
-\fBEILSEQ\fR and \fBEILOVERFLOW\fR associated with extended-level conformance
-are not yet detected (this implementation does not yet support XPG4 multibyte
-characters).
+const qualifiers to the arguments.
+.LP
+The Single Unix Specification, Version 2 states that
+\fBinsnstr\fP and \fBwinsnstr\fP perform wrapping.
+This is probably an error, since it makes this group of functions inconsistent.
+Also, no implementation of curses documents this inconsistency.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_clear\fR(3X), \fBcurs_inch\fR(3X).
+\fBcurses\fR(3X),
+\fBunctrl\fR(3X),
+\fBcurs_clear\fR(3X),
+\fBcurs_inch\fR(3X).
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/curs_instr.3x b/contrib/ncurses/man/curs_instr.3x
index 9a09ab278c47..a93de2728322 100644
--- a/contrib/ncurses/man/curs_instr.3x
+++ b/contrib/ncurses/man/curs_instr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000,2001 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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_instr.3x,v 1.10 2001/11/03 19:58:56 tom Exp $
+.\" $Id: curs_instr.3x,v 1.13 2006/02/25 21:49:19 tom Exp $
.TH curs_instr 3X ""
.SH NAME
\fBinstr\fR,
@@ -39,7 +39,7 @@
\fBmvwinnstr\fR - get a string of characters from a \fBcurses\fR window
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint instr(char *str);\fR
.br
\fBint innstr(char *str, int n);\fR
@@ -65,13 +65,14 @@ functions with \fIn\fR as the last argument return a leading substring at most
.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.
.SH NOTES
Note that all routines except \fBwinnstr\fR may be macros.
.SH PORTABILITY
-The XSI Curses
-error conditions \fBEILSEQ\fR and \fBEILOVERFLOW\fR associated with
-extended-level conformance are not yet detected (this implementation does not
-yet support XPG4 multibyte characters).
SVr4 does not
document whether a length limit includes or excludes the trailing NUL.
.PP
@@ -86,4 +87,3 @@ In this case, the functions return the string ending at the right margin.
.\"# mode:nroff
.\"# fill-column:79
.\"# End:
-
diff --git a/contrib/ncurses/man/curs_inwstr.3x b/contrib/ncurses/man/curs_inwstr.3x
index b345ce6e6fd5..990789cb9b32 100644
--- a/contrib/ncurses/man/curs_inwstr.3x
+++ b/contrib/ncurses/man/curs_inwstr.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 2002-2005,2006 Free 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,9 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inwstr.3x,v 1.2 2002/04/13 20:25:35 tom Exp $
-.TH curs_inwstr 3 ""
+.\" $Id: curs_inwstr.3x,v 1.5 2006/02/25 21:20:20 tom Exp $
+.TH curs_inwstr 3X ""
.SH NAME
-.PP
\fBinwstr\fR,
\fBinnwstr\fR,
\fBwinwstr\fR,
@@ -41,7 +40,7 @@
.SH SYNOPSIS
.nf
\fB#include <curses.h> \fR
-
+.sp
\fBint inwstr(\fR\fBwchar_t *\fR\fIstr\fR\fB);\fR
.br
\fBint innwstr(\fR\fBwchar_t *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR
@@ -83,7 +82,6 @@ routines return
routines return the
number of characters read into the string.
.SH SEE ALSO
-Functions:
\fBcurses\fR(3X),
\fBcurs_instr\fR(3X),
\fBcurs_in_wchstr\fR(3X)
diff --git a/contrib/ncurses/man/curs_kernel.3x b/contrib/ncurses/man/curs_kernel.3x
index caeb5bba0cd8..9403973840e4 100644
--- a/contrib/ncurses/man/curs_kernel.3x
+++ b/contrib/ncurses/man/curs_kernel.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2001,2005 Free 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,27 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_kernel.3x,v 1.13 2001/12/08 18:01:25 tom Exp $
+.\" $Id: curs_kernel.3x,v 1.15 2005/05/15 16:18:13 tom Exp $
.TH curs_kernel 3X ""
+.na
+.hy 0
.SH NAME
-\fBdef_prog_mode\fR, \fBdef_shell_mode\fR,
-\fBreset_prog_mode\fR, \fBreset_shell_mode\fR, \fBresetty\fR,
-\fBsavetty\fR, \fBgetsyx\fR, \fBsetsyx\fR, \fBripoffline\fR,
-\fBcurs_set\fR, \fBnapms\fR - low-level \fBcurses\fR routines
+\fBdef_prog_mode\fR,
+\fBdef_shell_mode\fR,
+\fBreset_prog_mode\fR,
+\fBreset_shell_mode\fR,
+\fBresetty\fR,
+\fBsavetty\fR,
+\fBgetsyx\fR,
+\fBsetsyx\fR,
+\fBripoffline\fR,
+\fBcurs_set\fR,
+\fBnapms\fR - low-level \fBcurses\fR routines
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint def_prog_mode(void);\fR
.br
\fBint def_shell_mode(void);\fR
@@ -62,32 +73,32 @@
The following routines give low-level access to various \fBcurses\fR
capabilities. Theses routines typically are used inside library
routines.
-
+.PP
The \fBdef_prog_mode\fR and \fBdef_shell_mode\fR routines save the
current terminal modes as the "program" (in \fBcurses\fR) or "shell"
(not in \fBcurses\fR) state for use by the \fBreset_prog_mode\fR and
\fBreset_shell_mode\fR routines. This is done automatically by
\fBinitscr\fR. There is one such save area for each screen context
allocated by \fBnewterm()\fR.
-
+.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.
-
+.PP
The \fBresetty\fR and \fBsavetty\fR routines save and restore the
state of the terminal modes. \fBsavetty\fR saves the current state in
a buffer and \fBresetty\fR restores the state to what it was at the
last call to \fBsavetty\fR.
-
+.PP
The \fBgetsyx\fR routine returns the current coordinates of the virtual screen
cursor in \fIy\fR and \fIx\fR. If \fBleaveok\fR is currently \fBTRUE\fR, then
\fB-1\fR,\fB-1\fR is returned. If lines have been removed from the top of the
screen, using \fBripoffline\fR, \fIy\fR and \fIx\fR include these lines;
therefore, \fIy\fR and \fIx\fR should be used only as arguments for
\fBsetsyx\fR.
-
+.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
@@ -97,7 +108,7 @@ 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
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
@@ -112,29 +123,45 @@ 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.
-
+.PP
\fBripoffline\fR can be called up to five times before calling \fBinitscr\fR or
\fBnewterm\fR.
-
+.PP
The \fBcurs_set\fR routine sets the cursor state is set 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.
-
+.PP
The \fBnapms\fR routine is used to sleep for \fIms\fR milliseconds.
.SH RETURN VALUE
Except for \fBcurs_set\fR, these routines always return \fBOK\fR.
-\fBcurs_set\fR returns the previous cursor state, or \fBERR\fR if the
+.PP
+\fBcurs_set\fR
+returns the previous cursor state, or \fBERR\fR if the
requested \fIvisibility\fR is not supported.
+.PP
+X/Open defines no error conditions.
+In this implementation
+.RS
+.TP 5
+\fBdef_prog_mode\fR, \fBdef_shell_mode\fR, \fBreset_prog_mode\fR, \fBreset_shell_mode\fR
+return an error
+if the terminal was not initialized, or
+if the I/O call to obtain the terminal settings fails.
+.TP 5
+\fBripoffline\fP
+returns an error if the maximum number of ripped-off lines
+exceeds the maximum (NRIPS = 5).
+.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
on the correctness of the return value anywhere else.
-
+.PP
Both ncurses and SVr4 will call \fBcurs_set\fR in \fBendwin\fR
if \fBcurs_set\fR
has been called to make the cursor other than normal, i.e., either
@@ -144,7 +171,7 @@ 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.
-
+.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
for the return value.
diff --git a/contrib/ncurses/man/curs_mouse.3x b/contrib/ncurses/man/curs_mouse.3x
index 8211ef894f71..865fab1ad88f 100644
--- a/contrib/ncurses/man/curs_mouse.3x
+++ b/contrib/ncurses/man/curs_mouse.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2001,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2005 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -27,19 +27,23 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_mouse.3x,v 1.19 2002/02/16 22:39:04 tom Exp $
+.\" $Id: curs_mouse.3x,v 1.28 2005/05/15 16:18:19 tom Exp $
.TH curs_mouse 3X ""
+.na
+.hy 0
.SH NAME
\fBgetmouse\fR, \fBungetmouse\fR,
\fBmousemask\fR, \fBwenclose\fR,
\fBmouse_trafo\fR, \fBwmouse_trafo\fR,
\fBmouseinterval\fR - mouse interface through curses
+.ad
+.hy
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fR
-
+\fB#include <curses.h>
+.PP
\fBtypedef unsigned long mmask_t;
-
+.PP
typedef struct
{
short id; \fI/* ID to distinguish multiple devices */\fB
@@ -55,7 +59,7 @@ MEVENT;\fR
.br
\fBmmask_t mousemask(mmask_t newmask, mmask_t *oldmask);\fR
.br
-\fBbool wenclose(WINDOW *win, int y, int x);\fR
+\fBbool wenclose(const WINDOW *win, int y, int x);\fR
.br
\fBbool mouse_trafo(int* pY, int* pX, bool to_screen);\fR
.br
@@ -70,7 +74,7 @@ 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.
-
+.PP
To make mouse events visible, use the \fBmousemask\fR function.
This will set
the mouse events to be reported.
@@ -80,13 +84,13 @@ can be reported; on complete failure it returns 0.
If oldmask is non-NULL,
this function fills the indicated location with the previous value of the given
window's mouse event mask.
-
+.PP
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.
-
-Here are the mouse event type masks:
-
+.PP
+Here are the mouse event type masks which may be defined:
+.PP
.TS
l l
_ _
@@ -97,28 +101,39 @@ BUTTON1_RELEASED mouse button 1 up
BUTTON1_CLICKED mouse button 1 clicked
BUTTON1_DOUBLE_CLICKED mouse button 1 double clicked
BUTTON1_TRIPLE_CLICKED mouse button 1 triple clicked
+_
BUTTON2_PRESSED mouse button 2 down
BUTTON2_RELEASED mouse button 2 up
BUTTON2_CLICKED mouse button 2 clicked
BUTTON2_DOUBLE_CLICKED mouse button 2 double clicked
BUTTON2_TRIPLE_CLICKED mouse button 2 triple clicked
+_
BUTTON3_PRESSED mouse button 3 down
BUTTON3_RELEASED mouse button 3 up
BUTTON3_CLICKED mouse button 3 clicked
BUTTON3_DOUBLE_CLICKED mouse button 3 double clicked
BUTTON3_TRIPLE_CLICKED mouse button 3 triple clicked
+_
BUTTON4_PRESSED mouse button 4 down
BUTTON4_RELEASED mouse button 4 up
BUTTON4_CLICKED mouse button 4 clicked
BUTTON4_DOUBLE_CLICKED mouse button 4 double clicked
BUTTON4_TRIPLE_CLICKED mouse button 4 triple clicked
+_
+BUTTON5_PRESSED mouse button 5 down
+BUTTON5_RELEASED mouse button 5 up
+BUTTON5_CLICKED mouse button 5 clicked
+BUTTON5_DOUBLE_CLICKED mouse button 5 double clicked
+BUTTON5_TRIPLE_CLICKED mouse button 5 triple clicked
+_
BUTTON_SHIFT shift was down during button state change
BUTTON_CTRL control was down during button state change
BUTTON_ALT alt was down during button state change
ALL_MOUSE_EVENTS report all button state changes
REPORT_MOUSE_POSITION report mouse movement
+_
.TE
-
+.PP
Once a class of mouse events have 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.
@@ -131,26 +146,26 @@ x in the event structure coordinates will be screen-relative character-cell
coordinates.
The returned state mask will have exactly one bit set to
indicate the event type.
-
+.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.
-
+.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.
It is useful for determining what subset of
the screen windows enclose the location of a mouse event.
-
+.PP
The \fBwmouse_trafo\fR function transforms a given pair of coordinates from
stdscr-relative coordinates to screen-relative coordinates or vice versa.
Please remember, that stdscr-relative coordinates are not always identical
to screen-relative coordinates due to the mechanism to reserve lines on top
or bottom of the screen for other purposes (ripoff() call, see also slk_...
functions).
-If the parameter \fBto_screen\fR is \fBTRUE\fR, the pointers
-\fBpY, pX\fR must reference the coordinates of a location inside the window
+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 screen-relative coordinates and returned
through the pointers.
@@ -168,47 +183,93 @@ window, \fBFALSE\fR is returned.
Please notice, that the referenced coordinates
are only replaced by the converted coordinates if the transformation was
successful.
-
+.PP
The \fBmouseinterval\fR function sets the maximum time (in thousands of a
second) that can elapse between press and release events for them to
be recognized as a click.
-Use \fBmouseinterval(-1)\fR to disable click resolution.
+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.
-
+.PP
Note that mouse events will be ignored when input is in cooked mode, and will
cause an error beep when cooked mode is being simulated in a window by a
function such as \fBgetstr\fR that expects a linefeed for input-loop
termination.
-
.SH RETURN VALUE
-\fBgetmouse\fR, \fBungetmouse\fR and \fBmouseinterval\fR
+\fBgetmouse\fR and \fBungetmouse\fR
return the integer \fBERR\fR upon failure or \fBOK\fR
upon successful completion.
-\fBmousemask\fR returns the
-mask of reportable events.
+.RS
+.TP 5
+\fBgetmouse\fP
+returns an error.
+If no mouse driver was initialized, or
+if the mask parameter is zero,
+.TP 5
+\fBungetmouse\fP
+returns an error if the FIFO is full.
+.RE
+.PP
+\fBmousemask\fR
+returns the mask of reportable events.
+.PP
+\fBmouseinterval\fR
+returns the previous interval value, unless
+the terminal was not initialized.
+In that case, it returns the maximum interval value (166).
+.PP
\fBwenclose\fR and \fBwmouse_trafo\fR
are boolean functions returning \fBTRUE\fR or \fBFALSE\fR depending
on their test result.
.SH PORTABILITY
These calls were designed for \fBncurses\fR(3X), and are not found in SVr4
curses, 4.4BSD curses, or any other previous version of curses.
-
+.PP
The feature macro \fBNCURSES_MOUSE_VERSION\fR is provided so the preprocessor
-can be used to test whether these features are present (its value is 1).
+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
+.TP 3
+1
+has definitions for reserved events.
+The mask uses 28 bits.
+.TP 3
+2
+adds definitions for button 5,
+removes the definitions for reserved events.
+The mask uses 29 bits.
+.RE
+.PP
The order of the \fBMEVENT\fR structure members is not guaranteed.
Additional fields may be added to the structure in the future.
-
+.PP
Under \fBncurses\fR(3X), these calls are implemented using either
-xterm's built-in mouse-tracking API or Alessandro Rubini's gpm server.
-If you are using something other than xterm and there is no gpm daemon
-running on your machine, mouse events will not be visible to
+xterm's built-in mouse-tracking API or
+platform-specific drivers including
+.RS
+Alessandro Rubini's gpm server.
+.br
+FreeBSD sysmouse
+.br
+OS/2 EMX
+.RE
+If you are using an unsupported configuration,
+mouse events will not be visible to
\fBncurses\fR(3X) (and the \fBwmousemask\fR function will always
return \fB0\fR).
-
+.PP
+If the terminfo entry contains a \fBXM\fR string,
+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
+\\E[?1000%?%p1%{1}%=%th%el%;
+.RE
The z member in the event structure is not presently used.
It is intended
for use with touch screens (which may be pressure-sensitive) or with
@@ -218,12 +279,12 @@ Mouse events under xterm will not in fact be ignored during cooked mode,
if they have been enabled by \fBwmousemask\fR.
Instead, the xterm mouse
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 must have \fBkmous\fR set to "\\E[M" (the beginning
of the response from xterm for mouse clicks).
-
+.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",
diff --git a/contrib/ncurses/man/curs_move.3x b/contrib/ncurses/man/curs_move.3x
index 2fff160c2f14..804637792be5 100644
--- a/contrib/ncurses/man/curs_move.3x
+++ b/contrib/ncurses/man/curs_move.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2001 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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,13 +26,18 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_move.3x,v 1.7 2001/11/03 19:58:47 tom Exp $
+.\" $Id: curs_move.3x,v 1.12 2006/02/25 21:49:19 tom Exp $
.TH curs_move 3X ""
+.na
+.hy 0
.SH NAME
-\fBmove\fR, \fBwmove\fR - move \fBcurses\fR window cursor
+\fBmove\fR,
+\fBwmove\fR - move \fBcurses\fR window cursor
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint move(int y, int x);\fR
.br
\fBint wmove(WINDOW *win, int y, int x);\fR
@@ -46,13 +51,14 @@ left-hand corner of the window, which is (0,0).
These routines return \fBERR\fR upon failure and OK (SVr4
specifies only "an integer value other than \fBERR\fR") upon successful
completion.
+.PP
+Specifically, they return an error
+if the window pointer is null, or
+if the position is outside the window.
.SH NOTES
Note that \fBmove\fR may be a macro.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4. The
-standard specifies that if (y,x) is within a multi-column character, the cursor
-is moved to the first column of that character; however, this implementation
-does not yet support the extended-level XSI multibyte characters.
+These functions are described in the XSI Curses standard, Issue 4.
.SH SEE ALSO
\fBcurses\fR(3X), \fBcurs_refresh\fR(3X)
.\"#
diff --git a/contrib/ncurses/man/curs_outopts.3x b/contrib/ncurses/man/curs_outopts.3x
index f9db6f26def5..5b986bbd67bf 100644
--- a/contrib/ncurses/man/curs_outopts.3x
+++ b/contrib/ncurses/man/curs_outopts.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2001 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2005 Free 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,15 +26,26 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_outopts.3x,v 1.17 2001/10/14 00:50:30 tom Exp $
+.\" $Id: curs_outopts.3x,v 1.20 2005/05/15 16:18:32 tom Exp $
.TH curs_outopts 3X ""
+.na
+.hy 0
.SH NAME
-\fBclearok\fR, \fBidlok\fR, \fBidcok\fR, \fBimmedok\fR,
-\fBleaveok\fR, \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBscrollok\fR,
-\fBnl\fR, \fBnonl\fR - \fBcurses\fR output options
+\fBclearok\fR,
+\fBidlok\fR,
+\fBidcok\fR,
+\fBimmedok\fR,
+\fBleaveok\fR,
+\fBsetscrreg\fR,
+\fBwsetscrreg\fR,
+\fBscrollok\fR,
+\fBnl\fR,
+\fBnonl\fR - \fBcurses\fR output options
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint clearok(WINDOW *win, bool bf);\fR
.br
\fBint idlok(WINDOW *win, bool bf);\fR
@@ -60,7 +71,7 @@ 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.
-
+.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
redraw the entire screen from scratch.
@@ -70,7 +81,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.
-
+.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
equipped.
@@ -83,28 +94,28 @@ disabled by default because insert/delete line tends to be visually annoying
when used in applications where it isn't really needed.
If insert/delete line
cannot be used, \fBcurses\fR redraws the changed portions of all lines.
-
+.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
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.
-
+.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,
-\fIetc\fR., automatically cause a call to \fBwrefresh\fR.
+etc., automatically cause a call to \fBwrefresh\fR.
However, it may
degrade performance considerably, due to repeated calls to \fBwrefresh\fR.
It is disabled by default.
-
+.PP
Normally, the hardware cursor is left at the location of the window cursor
being refreshed.
The \fBleaveok\fR option allows the cursor to be left
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.
-
+.PP
The \fBsetscrreg\fR and \fBwsetscrreg\fR routines allow the application
programmer to set a software scrolling region in a window.
\fItop\fR and
@@ -121,7 +132,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.)
-
+.PP
The \fBscrollok\fR option controls what happens when the cursor of a window is
moved off the edge of the window or scrolling region, either as a result of a
newline action on the bottom line, or typing the last character of the last
@@ -131,7 +142,7 @@ 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).
-
+.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
@@ -148,30 +159,48 @@ The functions \fBsetscrreg\fR and \fBwsetscrreg\fR return \fBOK\fR upon success
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.
+.PP
+In this implementation, those functions that have a window pointer
+will return an error if the window pointer is null.
+.RS
+.TP 5
+.B wclrtoeol
+returns an error
+if the cursor position is about to wrap.
+.TP 5
+.B wsetscrreg
+returns an error if the scrolling region limits extend outside the window.
+.RE
+.PP
+X/Open does not define any error conditions.
+This implementation returns an error
+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().
BSD curses did turn off these translations; AT&T curses (at least as late as
SVr1) did not.
We choose to do so, on the theory that a programmer requesting
raw input wants a clean (ideally 8-bit clean) connection that the operating
-system does not mess with.
-
+system will not alter.
+.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.
-
-Earlier System V curses implementations specified that with \fBscrollok\fR
+.PP
+Earlier System V curses implementations specified that with \fBscrollok\fR
enabled, any window modification triggering a scroll also forced a physical
refresh.
XSI Curses does not require this, and \fBncurses\fR avoids doing
it to perform better vertical-motion optimization at \fBwrefresh\fR
time.
-
+.PP
The XSI Curses standard does not mention that the cursor should be
made invisible as a side-effect of \fBleaveok\fR.
SVr4 curses documentation does this, but the code does not.
@@ -179,7 +208,7 @@ Use \fBcurs_set\fR to make the cursor invisible.
.SH NOTES
Note that \fBclearok\fR, \fBleaveok\fR, \fBscrollok\fR, \fBidcok\fR, \fBnl\fR,
\fBnonl\fR and \fBsetscrreg\fR may be macros.
-
+.PP
The \fBimmedok\fR routine is useful for windows that are used as terminal
emulators.
.SH SEE ALSO
diff --git a/contrib/ncurses/man/curs_overlay.3x b/contrib/ncurses/man/curs_overlay.3x
index f17b375c3982..066c3a4a50f6 100644
--- a/contrib/ncurses/man/curs_overlay.3x
+++ b/contrib/ncurses/man/curs_overlay.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000,2001 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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,20 +26,24 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_overlay.3x,v 1.10 2001/11/03 19:58:30 tom Exp $
+.\" $Id: curs_overlay.3x,v 1.14 2006/02/25 21:49:19 tom Exp $
.TH curs_overlay 3X ""
+.na
+.hy 0
.SH NAME
\fBoverlay\fR,
\fBoverwrite\fR,
\fBcopywin\fR - overlay and manipulate overlapped \fBcurses\fR windows
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint overlay(const WINDOW *srcwin, WINDOW *dstwin);\fR
.br
\fBint overwrite(const WINDOW *srcwin, WINDOW *dstwin);\fR
.br
-\fBint copywin(WINDOW *srcwin, WINDOW *dstwin, int sminrow,\fR
+\fBint copywin(const WINDOW *srcwin, WINDOW *dstwin, int sminrow,\fR
\fBint smincol, int dminrow, int dmincol, int dmaxrow,\fR
\fBint dmaxcol, int overlay);\fR
.SH DESCRIPTION
@@ -48,7 +52,7 @@ 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.
-
+.PP
The \fBcopywin\fR routine provides a finer granularity of control over the
\fBoverlay\fR and \fBoverwrite\fR routines. Like in the \fBprefresh\fR
routine, a rectangle is specified in the destination window, (\fIdminrow\fR,
@@ -60,6 +64,13 @@ argument \fIoverlay\fR is \fBtrue\fR, then copying is non-destructive, as in
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.
+.PP
+X/Open defines no error conditions.
+In this implementation,
+\fBcopywin\fP,
+\fBoverlay\fP and \fBoverwrite\fP return an error
+if either of the window pointers are null, or
+if some part of the window would be placed off-screen.
.SH NOTES
Note that \fBoverlay\fR and \fBoverwrite\fR may be macros.
.SH PORTABILITY
diff --git a/contrib/ncurses/man/curs_pad.3x b/contrib/ncurses/man/curs_pad.3x
index 0813a0a48f64..c7222074ebeb 100644
--- a/contrib/ncurses/man/curs_pad.3x
+++ b/contrib/ncurses/man/curs_pad.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2004,2005 Free 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,22 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_pad.3x,v 1.9 2000/07/04 22:38:13 tom Exp $
+.\" $Id: curs_pad.3x,v 1.14 2005/05/15 16:18:43 tom Exp $
.TH curs_pad 3X ""
+.na
+.hy 0
.SH NAME
-\fBnewpad\fR, \fBsubpad\fR, \fBprefresh\fR,
-\fBpnoutrefresh\fR, \fBpechochar\fR - create and display \fBcurses\fR pads
+\fBnewpad\fR,
+\fBsubpad\fR,
+\fBprefresh\fR,
+\fBpnoutrefresh\fR,
+\fBpechochar\fR,
+\fBpecho_wchar\fR - create and display \fBcurses\fR pads
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBWINDOW *newpad(int nlines, int ncols);\fR
.br
\fBWINDOW *subpad(WINDOW *orig, int nlines, int ncols,\fR
@@ -46,56 +54,100 @@
\fBint sminrow, int smincol, int smaxrow, int smaxcol);\fR
.br
\fBint pechochar(WINDOW *pad, chtype ch);\fR
+.br
+\fBint pecho_wchar(WINDOW *pad, const cchar_t *wch);\fR
.SH DESCRIPTION
The \fBnewpad\fR routine creates and returns a pointer to a new pad data
structure with the given number of lines, \fInlines\fR, and columns,
-\fIncols\fR. A pad is like a window, except that it is not restricted by the
+\fIncols\fR.
+A pad is like a window, except that it is not restricted by the
screen size, and is not necessarily associated with a particular part of the
-screen. Pads can be used when a large window is needed, and only a part of the
-window will be on the screen at one time. Automatic refreshes of pads
-(\fIe\fR.\fIg\fR., from scrolling or echoing of input) do not occur. It is not
+screen.
+Pads can be used when a large window is needed, and only a part of the
+window will be on the screen at one time.
+Automatic refreshes of pads
+(e.g., from scrolling or echoing of input) do not occur.
+It is not
legal to call \fBwrefresh\fR with a \fIpad\fR as an argument; the routines
-\fBprefresh\fR or \fBpnoutrefresh\fR should be called instead. Note that these
+\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.
-
+.PP
The \fBsubpad\fR routine creates and returns a pointer to a subwindow within a
pad with the given number of lines, \fInlines\fR, and columns, \fIncols\fR.
Unlike \fBsubwin\fR, which uses screen coordinates, the window is at position
-(\fIbegin\fR_\fIx\fR\fB,\fR \fIbegin\fR_\fIy\fR) on the pad. The window is
+(\fIbegin\fR_\fIx\fR\fB,\fR \fIbegin\fR_\fIy\fR) on the pad.
+The window is
made in the middle of the window \fIorig\fR, so that changes made to one window
-affect both windows. During the use of this routine, it will often be
+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.
-
+.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. \fIpminrow\fR and \fIpmincol\fR specify the upper
-left-hand corner of the rectangle to be displayed in the pad. \fIsminrow\fR,
+of windows.
+The additional parameters are needed to indicate what part of the
+pad and screen are involved.
+\fIpminrow\fR and \fIpmincol\fR specify the upper
+left-hand corner of the rectangle to be displayed in the pad.
+\fIsminrow\fR,
\fIsmincol\fR, \fIsmaxrow\fR, and \fIsmaxcol\fR specify the edges of the
-rectangle to be displayed on the screen. The lower right-hand corner of the
+rectangle to be displayed on the screen.
+The lower right-hand corner of the
rectangle to be displayed in the pad is calculated from the screen coordinates,
-since the rectangles must be the same size. Both rectangles must be entirely
-contained within their respective structures. Negative values of
+since the rectangles must be the same size.
+Both rectangles must be entirely
+contained within their respective structures.
+Negative values of
\fIpminrow\fR, \fIpmincol\fR, \fIsminrow\fR, or \fIsmincol\fR are treated as if
they were zero.
-
+.PP
The \fBpechochar\fR routine is functionally equivalent to a call to \fBaddch\fR
followed by a call to \fBrefresh\fR, a call to \fBwaddch\fR followed by a call
to \fBwrefresh\fR, or a call to \fBwaddch\fR followed by a call to
-\fBprefresh.\fR The knowledge that only a single character is being output is
+\fBprefresh\fR.
+The knowledge that only a single character is being output is
taken into consideration and, for non-control characters, a considerable
performance gain might be seen by using these routines instead of their
-equivalents. In the case of \fBpechochar\fR, the last location of the pad on
+equivalents.
+In the case of \fBpechochar\fR, the last location of the pad on
the screen is reused for the arguments to \fBprefresh\fR.
+.PP
+The \fBpecho_wchar\fR function is the analogous wide-character
+form of \fBpechochar\fR.
+It outputs one character to a pad and immediately refreshes the pad.
+It does this by a call to \fBwadd_wch\fR followed by a call to \fBprefresh\fR.
.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.
-
+.PP
Routines that return pointers return \fBNULL\fR on error, and set \fBerrno\fR
-to \fBENOMEM\fR.
+to \fBENOMEM\fR.
+.PP
+X/Open does not define any error conditions.
+In this implementation
+.RS
+.TP 5
+\fBprefresh\fP and \fBpnoutrefresh\fP
+return an error
+if the window pointer is null, or
+if the window is not really a pad or
+if the area to refresh extends off-screen or
+if the minimum coordinates are greater than the maximum.
+.TP 5
+\fBpechochar\fP
+returns an error
+if the window is not really a pad, and the associated call
+to \fBwechochar\fP returns an error.
+.TP 5
+\fBpecho_wchar\fP
+returns an error
+if the window is not really a pad, and the associated call
+to \fBwecho_wchar\fP returns an error.
+.RE
.SH NOTES
Note that \fBpechochar\fR may be a macro.
.SH PORTABILITY
diff --git a/contrib/ncurses/man/curs_print.3x b/contrib/ncurses/man/curs_print.3x
index dd4b6e3cba45..92b9ca2dafcc 100644
--- a/contrib/ncurses/man/curs_print.3x
+++ b/contrib/ncurses/man/curs_print.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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,36 +26,36 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_print.3x,v 1.5 2002/02/16 22:39:04 tom Exp $
+.\" $Id: curs_print.3x,v 1.8 2006/02/25 21:49:19 tom Exp $
.TH curs_print 3X ""
.SH NAME
\fBmcprint\fR - ship binary data to printer
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint mcprint(char *data, int len);\fR
.SH DESCRIPTION
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
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
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
+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:
.TP 5
ENODEV
-Capabilities for printer redirection don't exist.
+Capabilities for printer redirection do not exist.
.TP 5
ENOMEM
Couldn't allocate sufficient memory to buffer the printer write.
-
+.PP
When \fBmcprint\fR succeeds, it returns the number of characters actually
sent to the printer.
.SH PORTABILITY
diff --git a/contrib/ncurses/man/curs_printw.3x b/contrib/ncurses/man/curs_printw.3x
index 8ba9d1748649..7c1a41b5b96f 100644
--- a/contrib/ncurses/man/curs_printw.3x
+++ b/contrib/ncurses/man/curs_printw.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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,50 +26,64 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_printw.3x,v 1.11 2000/07/01 20:11:32 tom Exp $
+.\" $Id: curs_printw.3x,v 1.16 2006/02/25 21:49:19 tom Exp $
.TH curs_printw 3X ""
+.na
+.hy 0
.SH NAME
\fBprintw\fR,
\fBwprintw\fR,
\fBmvprintw\fR,
\fBmvwprintw\fR,
\fBvwprintw\fR, \fBvw_printw\fR - print formatted output in \fBcurses\fR windows
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
-\fBint printw(char *fmt\fR [\fB, arg\fR] \fB...);\fR
+.sp
+\fBint printw(const char *fmt, ...);\fR
.br
-\fBint wprintw(WINDOW *win, char *fmt\fR [\fB, arg\fR] \fB...);\fR
+\fBint wprintw(WINDOW *win, const char *fmt, ...);\fR
.br
-\fBint mvprintw(int y, int x, char *fmt\fR [\fB, arg\fR] \fB...);\fR
+\fBint mvprintw(int y, int x, const char *fmt, ...);\fR
.br
-\fBint mvwprintw(WINDOW *win, int y, int x,\fR
- \fBchar *fmt\fR [\fB, arg]\fR ...);
-
-\fB#include <varargs.h>\fR
+\fBint mvwprintw(WINDOW *win, int y, int x, const char *fmt, ...);\fR
.br
-\fBint vwprintw(WINDOW *win, char *fmt, varglist);\fR
+\fBint vwprintw(WINDOW *win, const char *fmt, va_list varglist);\fR
.br
-\fBint vw_printw(WINDOW *win, char *fmt, varglist);\fR
+\fBint vw_printw(WINDOW *win, const char *fmt, va_list varglist);\fR
.br
.SH DESCRIPTION
The \fBprintw\fR, \fBwprintw\fR, \fBmvprintw\fR and \fBmvwprintw\fR
routines are analogous to \fBprintf\fR [see \fBprintf\fR(3S)]. In
effect, the string that would be output by \fBprintf\fR is output
instead as though \fBwaddstr\fR were used on the given window.
-
-The \fBvwprintw\fR routine is analogous to \fBvprintf\fR [see
-\fBprintf\fR(3S)] and performs a \fBwprintw\fR using a variable
-argument list. The third argument is a \fBva_list\fR, a pointer to a
-list of arguments, as defined in \fB<varargs.h>\fR.
+.PP
+The \fBvwprintw\fR and \fBwv_printw\fR routines are analogous
+to \fBvprintf\fR [see \fBprintf\fR(3S)]
+and perform a \fBwprintw\fR using a variable argument list.
+The third argument is a \fBva_list\fR, a pointer to a
+list of arguments, as defined in \fB<stdarg.h>\fR.
.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.
+.PP
+X/Open defines no error conditions.
+In this implementation,
+an error may be returned if it cannot allocate enough memory for the
+buffer used to format the results.
+It will return an error if the window pointer is null.
.SH PORTABILITY
The XSI Curses standard, Issue 4 describes these functions. The function
\fBvwprintw\fR is marked TO BE WITHDRAWN, and is to be replaced by a function
\fBvw_printw\fR using the \fB<stdarg.h>\fR interface.
+The Single Unix Specification, Version 2 states that
+\fBvw_printw\fR is preferred to \fBvwprintw\fR since the latter requires
+including \fB<varargs.h>\fR, which
+cannot be used in the same file as \fB<stdarg.h>\fR.
+This implementation uses \fB<stdarg.h>\fR for both, because that header
+is included in \fB<curses.h\fR>.
.SH SEE ALSO
\fBcurses\fR(3X), \fBprintf\fR(3S), \fBvprintf(3S)\fR
.\"#
diff --git a/contrib/ncurses/man/curs_refresh.3x b/contrib/ncurses/man/curs_refresh.3x
index 210b326a618a..5ce06903d83d 100644
--- a/contrib/ncurses/man/curs_refresh.3x
+++ b/contrib/ncurses/man/curs_refresh.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000,2001 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2001,2005 Free 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,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_refresh.3x,v 1.10 2001/11/03 18:57:12 tom Exp $
+.\" $Id: curs_refresh.3x,v 1.12 2005/05/15 16:18:49 tom Exp $
.TH curs_refresh 3X ""
+.na
+.hy 0
.SH NAME
\fBdoupdate\fR,
\fBredrawwin\fR,
@@ -35,9 +37,11 @@
\fBwnoutrefresh\fR,
\fBwredrawln\fR,
\fBwrefresh\fR - refresh \fBcurses\fR windows and lines
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint refresh(void);\fR
.br
\fBint wrefresh(WINDOW *win);\fR
@@ -62,14 +66,14 @@ 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.
-
+.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.
-
+.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
@@ -84,7 +88,7 @@ characters transmitted and less CPU time used.
If the \fIwin\fR argument to
\fBwrefresh\fR is the global variable \fBcurscr\fR, the screen is immediately
cleared and repainted from scratch.
-
+.PP
The phrase "copies the named window to the virtual screen" above is ambiguous.
What actually happens is that all \fItouched\fR (changed) lines in the window
are copied to the virtual screen.
@@ -94,7 +98,7 @@ 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.)
-
+.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).
@@ -103,11 +107,25 @@ The routine \fBredrawwin\fR() touches the entire window.
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.
+.PP
+X/Open does not define any error conditions.
+In this implementation
+.RS
+.TP 5
+\fBwnoutrefresh\fP
+returns an error
+if the window pointer is null, or
+if the window is really a pad.
+.TP 5
+\fBwredrawln\fP
+returns an error
+if the associated call to \fBtouchln\fP returns an error.
+.RE
.SH NOTES
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
of a window or just its changed portions has never been well-documented in
historic curses versions (including SVr4).
diff --git a/contrib/ncurses/man/curs_scanw.3x b/contrib/ncurses/man/curs_scanw.3x
index b7f3795d8101..9f25b57089bb 100644
--- a/contrib/ncurses/man/curs_scanw.3x
+++ b/contrib/ncurses/man/curs_scanw.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2000,2006 Free 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_scanw.3x,v 1.11 2000/07/15 21:48:17 tom Exp $
+.\" $Id: curs_scanw.3x,v 1.13 2006/02/25 21:42:22 tom Exp $
.TH curs_scanw 3X ""
.SH NAME
\fBscanw\fR,
@@ -36,15 +36,14 @@
\fBvwscanw\fR, \fBvw_scanw\fR - convert formatted input from a \fBcurses\fR window
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
-\fBint scanw(char *fmt\fR [\fB, arg\fR] \fB...);\fR
+.sp
+\fBint scanw(char *fmt, ...);\fR
.br
-\fBint wscanw(WINDOW *win, char *fmt\fR [\fB, arg\fR] \fB...);\fR
+\fBint wscanw(WINDOW *win, char *fmt, ...);\fR
.br
-\fBint mvscanw(int y, int x, char *fmt\fR [\fB, arg\fR] \fB...);\fR
+\fBint mvscanw(int y, int x, char *fmt, ...);\fR
.br
-\fBint mvwscanw(WINDOW *win, int y, int x,\fR
- \fBchar *fmt\fR [\fB, arg]\fR \fB...);\fR
+\fBint mvwscanw(WINDOW *win, int y, int x, char *fmt, ...);\fR
.br
\fBint vw_scanw(WINDOW *win, char *fmt, va_list varglist);\fR
.br
@@ -55,15 +54,15 @@ The \fBscanw\fR, \fBwscanw\fR and \fBmvscanw\fR routines are analogous to
\fBwgetstr\fR were called on the window, and the resulting line used as input
for \fBsscanf\fR(3). Fields which do not map to a variable in the \fIfmt\fR
field are lost.
-
-The \fBvwscanw\fR routine is similar to \fBvwprintw\fR in that it performs a
-\fBwscanw\fR using a variable argument list. The third argument is a
-\fIva\fR_\fIlist\fR, a pointer to a list of arguments, as defined in
-\fB<varargs.h>\fR.
+.PP
+The \fBvwscanw\fR and \fBvw_scanw\fR routines are analogous to \fBvscanf\fR.
+They perform a \fBwscanw\fR using a variable argument list.
+The third argument is a \fIva_list\fR,
+a pointer to a list of arguments, as defined in \fB<stdarg.h>\fR.
.SH RETURN VALUE
\fBvwscanw\fR returns \fBERR\fR on failure and an integer equal to the
number of fields scanned on success.
-
+.PP
Applications may use the return value from the \fBscanw\fR, \fBwscanw\fR,
\fBmvscanw\fR and \fBmvwscanw\fR routines to determine the number of fields
which were mapped in the call.
@@ -71,6 +70,23 @@ which were mapped in the call.
The XSI Curses standard, Issue 4 describes these functions. The function
\fBvwscanw\fR is marked TO BE WITHDRAWN, and is to be replaced by a function
\fBvw_scanw\fR using the \fB<stdarg.h>\fR interface.
+The Single Unix Specification, Version 2 states that
+\fBvw_scanw\fR is preferred to \fBvwscanw\fR since the latter requires
+including \fB<varargs.h>\fR, which
+cannot be used in the same file as \fB<stdarg.h>\fR.
+This implementation uses \fB<stdarg.h>\fR for both, because that header
+is included in \fB<curses.h\fR>.
+.LP
+Both XSI and The Single Unix Specification, Version 2 state that these
+functions return ERR or OK.
+Since the underlying \fBscanf\fR can return the number of items scanned,
+and the SVr4 code was documented to use this feature,
+this is probably an editing error which was introduced in XSI,
+rather than being done intentionally.
+Portable applications should only test if the return value is ERR,
+since the OK value (zero) is likely to be misleading.
+One possible way to get useful results would be to use a "%n" conversion
+at the end of the format string to ensure that something was processed.
.SH SEE ALSO
\fBcurses\fR(3X), \fBcurs_getstr\fR(3X), \fBcurs_printw\fR(3X), \fBscanf\fR(3S)
.\"#
diff --git a/contrib/ncurses/man/curs_scr_dump.3x b/contrib/ncurses/man/curs_scr_dump.3x
index 581d10d13c43..d432c0dbdb6a 100644
--- a/contrib/ncurses/man/curs_scr_dump.3x
+++ b/contrib/ncurses/man/curs_scr_dump.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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,20 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_scr_dump.3x,v 1.2 2000/07/01 20:06:53 tom Exp $
+.\" $Id: curs_scr_dump.3x,v 1.6 2006/02/25 21:49:19 tom Exp $
.TH curs_scr_dump 3X ""
+.na
+.hy 0
.SH NAME
\fBscr_dump\fR,
\fBscr_restore\fR,
\fBscr_init\fR,
\fBscr_set\fR - read (write) a \fBcurses\fR screen from (to) a file
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint scr_dump(const char *filename);\fR
.br
\fBint scr_restore(const char *filename);\fR
@@ -47,41 +51,45 @@
.SH DESCRIPTION
The \fBscr_dump\fR routine dumps the current contents of the virtual screen
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.
-
+.PP
The \fBscr_init\fR routine reads in the contents of \fIfilename\fR and uses
them to initialize the \fBcurses\fR data structures about what the terminal
currently has on its screen. If the data is determined to be valid,
\fBcurses\fR bases its next update of the screen on this information rather
than clearing the screen and starting from scratch. \fBscr_init\fR is used
-after \fBinitscr\fR or a \fBsystem\fR [see \fBsystem\fR(BA_LIB)] call to share
+after \fBinitscr\fR or a \fBsystem\fR call to share
the screen with another process which has done a \fBscr_dump\fR after its
\fBendwin\fR call. The data is declared invalid if the terminfo capabilities
\fBrmcup\fR and \fBnrrmc\fR exist; also if the terminal has been written to
since the preceding \fBscr_dump\fR call.
-
+.PP
The \fBscr_set\fR routine is a combination of \fBscr_restore\fR and
\fBscr_init\fR. It tells the program that the information in \fIfilename\fR is
what is currently on the screen, and also what the program wants on the screen.
This can be thought of as a screen inheritance function.
-
+.PP
To read (write) a window from (to) a file, use the \fBgetwin\fR and
\fBputwin\fR routines [see \fBcurs_util\fR(3X)].
.SH RETURN VALUE
All routines return the integer \fBERR\fR upon failure and \fBOK\fR
upon success.
+.PP
+X/Open defines no error conditions.
+In this implementation,
+each will return an error if the file cannot be opened.
.SH NOTES
Note that \fBscr_init\fR, \fBscr_set\fR, and \fBscr_restore\fR may be macros.
.SH PORTABILITY
The XSI Curses standard, Issue 4, describes these functions (adding the const
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 don't define
+considered invalid "if the time-stamp of the tty is old" but do not define
"old".
.SH SEE ALSO
\fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_refresh\fR(3X),
diff --git a/contrib/ncurses/man/curs_scroll.3x b/contrib/ncurses/man/curs_scroll.3x
index f957ac96db7c..754b71499841 100644
--- a/contrib/ncurses/man/curs_scroll.3x
+++ b/contrib/ncurses/man/curs_scroll.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000,2001 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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,13 +26,19 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_scroll.3x,v 1.9 2001/10/14 00:51:56 tom Exp $
+.\" $Id: curs_scroll.3x,v 1.13 2006/02/25 21:49:19 tom Exp $
.TH curs_scroll 3X ""
+.na
+.hy 0
.SH NAME
-\fBscroll\fR, \fBscrl\fR, \fBwscrl\fR - scroll a \fBcurses\fR window
+\fBscroll\fR,
+\fBscrl\fR,
+\fBwscrl\fR - scroll a \fBcurses\fR window
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint scroll(WINDOW *win);\fR
.br
\fBint scrl(int n);\fR
@@ -46,28 +52,34 @@ 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.
-
+.PP
For positive \fIn\fR, the \fBscrl\fR and \fBwscrl\fR routines scroll the
window up \fIn\fR lines (line \fIi\fR+\fIn\fR becomes \fIi\fR); otherwise
scroll the window down \fIn\fR lines.
This involves moving the lines in the
window character image structure.
The current cursor position is not changed.
-
+.PP
For these functions to work, scrolling must be enabled via \fBscrollok\fR.
.SH RETURN VALUE
These routines return \fBERR\fR upon failure, and \fBOK\fR (SVr4 only specifies
"an integer value other than \fBERR\fR") upon successful completion.
+.PP
+X/Open defines no error conditions.
+.PP
+This implementation returns an error
+if the window pointer is null, or
+if scrolling is not enabled in the window, e.g., with \fBscrollok\fP.
.SH NOTES
Note that \fBscrl\fR and \fBscroll\fR may be macros.
-
-The SVr4 documentation says that the optimization of physically scrolling
+.PP
+The SVr4 documentation says that the optimization of physically scrolling
immediately if the scroll region is the entire screen "is" performed, not
"may be" performed.
This implementation deliberately does not guarantee
that this will occur, to leave open the possibility of smarter
-optimization of multiple scroll actions on the next update.
-
+optimization of multiple scroll actions on the next update.
+.PP
Neither the SVr4 nor the XSI documentation specify whether the current
attribute or
current color-pair of blanks generated by the scroll function is zeroed.
diff --git a/contrib/ncurses/man/curs_slk.3x b/contrib/ncurses/man/curs_slk.3x
index 8f1ae8a0d9bf..b946ff21f2de 100644
--- a/contrib/ncurses/man/curs_slk.3x
+++ b/contrib/ncurses/man/curs_slk.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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,32 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_slk.3x,v 1.11 2001/03/03 21:05:41 Todd.C.Miller Exp $
+.\" $Id: curs_slk.3x,v 1.15 2006/02/25 21:49:19 tom Exp $
.TH curs_slk 3X ""
+.na
+.hy 0
.SH NAME
-\fBslk_init\fR, \fBslk_set\fR, \fBslk_refresh\fR,
-\fBslk_noutrefresh\fR, \fBslk_label\fR,
-\fBslk_clear\fR, \fBslk_restore\fR, \fBslk_touch\fR,
-\fBslk_attron\fR, \fBslk_attrset\fR, \fBslk_attroff\fR,
-\fBslk_attr_on\fR, \fBslk_attr_set\fR, \fBslk_attr_off\fR,
-\fBslk_attr\fR, \fBslk_color\fR - \fBcurses\fR soft label routines
+\fBslk_init\fR,
+\fBslk_set\fR,
+\fBslk_refresh\fR,
+\fBslk_noutrefresh\fR,
+\fBslk_label\fR,
+\fBslk_clear\fR,
+\fBslk_restore\fR,
+\fBslk_touch\fR,
+\fBslk_attron\fR,
+\fBslk_attrset\fR,
+\fBslk_attroff\fR,
+\fBslk_attr_on\fR,
+\fBslk_attr_set\fR,
+\fBslk_attr_off\fR,
+\fBslk_attr\fR,
+\fBslk_color\fR - \fBcurses\fR soft label routines
+.ad
+.hy
.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
@@ -77,13 +91,13 @@ The slk* functions manipulate the set of soft function-key labels that exist on
many terminals. For those terminals that do not have soft labels,
\fBcurses\fR takes over the bottom line of \fBstdscr\fR, reducing the size of
\fBstdscr\fR and the variable \fBLINES\fR. \fBcurses\fR standardizes on eight
-labels of up to eight characters each. In addition to this, the ncurses
+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 most common for todays PC like enduser devices.
Please note that ncurses simulates this mode by taking over up to two lines at
the bottom of the screen, it doesn't try to use any hardware support for this
mode.
-
+.PP
The \fBslk_init\fR routine must be called before \fBinitscr\fR or \fBnewterm\fR
is called. If \fBinitscr\fR eventually uses a line from \fBstdscr\fR to
emulate the soft labels, then \fIfmt\fR determines how the labels are arranged
@@ -92,44 +106,86 @@ the labels, \fB1\fR indicates a 4-4 arrangement and \fB2\fR indicates the
PC like 4-4-4 mode. If \fBfmt\fR is set to \fB3\fR, it 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.
-
+.PP
The \fBslk_set\fR routine requires \fIlabnum\fR to be a label number,
-from \fB1\fR to \fB8\fR (resp. \fB12\fR); \fIlabel\fR must be the string
+from \fB1\fR to \fB8\fR (resp. \fB12\fR); \fIlabel\fR must be the string
to be put on the label, up to eight (resp. five) characters in length.
A null string or a null pointer sets up a blank label. \fIfmt\fR is either
-\fB0\fR, \fB1\fR, or \fB2\fR, indicating whether the label is to be
+\fB0\fR, \fB1\fR, or \fB2\fR, indicating whether the label is to be
left-justified, centered, or right-justified, respectively, within the
label.
-
+.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.
-
+.PP
The \fBslk_clear\fR routine clears the soft labels from the screen.
-
-The \fBslk_restore\fR routine, restores the soft labels to the screen
+.PP
+The \fBslk_restore\fR routine restores the soft labels to the screen
after a \fBslk_clear\fR has been performed.
-
+.PP
The \fBslk_touch\fR routine forces all the soft labels to be output
the next time a \fBslk_noutrefresh\fR is performed.
-
+.PP
The \fBslk_attron\fR, \fBslk_attrset\fR, \fBslk_attroff\fR and \fBslk_attr\fR
routines correspond to \fBattron\fR, \fBattrset\fR, \fBattroff\fR and \fBattr_get\fR.
They have an effect only if soft labels are simulated on the bottom line of
-the screen. The default highlight for soft keys is A_STANDOUT (as in
+the screen. The default highlight for soft keys is A_STANDOUT (as in
System V curses, which does not document this fact).
-
+.PP
The \fBslk_color\fR routine corresponds to \fBcolor_set\fR. It has an effect only
if soft labels are simulated on the bottom line of the screen.
-
+.
.SH RETURN VALUE
These routines return \fBERR\fR upon failure and OK (SVr4 specifies only "an
-integer value other than \fBERR\fR") upon successful completion. \fBslk_attr\fR
+integer value other than \fBERR\fR") upon successful completion.
+.PP
+X/Open defines no error conditions.
+In this implementation
+.RS
+.TP 5
+\fBslk_attr\fR
returns the attribute used for the soft keys.
-
-\fBslk_label\fR returns \fBNULL\fR on error.
+.TP 5
+.na
+.hy 0
+\fBslk_attroff\fP, \fBslk_attron\fP, \fBslk_clear\fP, \fBslk_noutrefresh\fP, \fBslk_refresh\fP, \fBslk_touch\fP
+.ad
+.hy
+return an error
+if the terminal or the softkeys were not initialized.
+.TP 5
+\fBslk_attrset\fP
+returns an error
+if the terminal or the softkeys were not initialized.
+.TP 5
+\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.
+.TP 5
+\fBslk_color\fP
+returns an error
+if the terminal or the softkeys were not initialized, or
+the color pair is outside the range 0..COLOR_PAIRS-1.
+.TP 5
+\fBslk_init\fR
+returns an error
+if the format parameter is outside the range 0..3.
+.TP 5
+\fBslk_label\fR
+returns \fBNULL\fR on error.
+.TP 5
+\fBslk_set\fP
+returns an error
+if the terminal or the softkeys were not initialized, or
+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 NOTES
Most applications would use \fBslk_noutrefresh\fR because a
\fBwrefresh\fR is likely to follow soon.
diff --git a/contrib/ncurses/man/curs_termattrs.3x b/contrib/ncurses/man/curs_termattrs.3x
index d285b8663345..48ff21ced68c 100644
--- a/contrib/ncurses/man/curs_termattrs.3x
+++ b/contrib/ncurses/man/curs_termattrs.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2000,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2002,2003 Free 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.8 2002/05/11 21:32:26 tom Exp $
+.\" $Id: curs_termattrs.3x,v 1.9 2003/12/27 18:37:47 tom Exp $
.TH curs_termattrs 3X ""
.SH NAME
\fBbaudrate\fR,
@@ -42,7 +42,7 @@
\fBtermname\fR - \fBcurses\fR environment query routines
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.PP
\fBint baudrate(void);\fR
.br
\fBchar erasechar(void);\fR
@@ -69,29 +69,29 @@
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.
-
+.PP
The \fBerasechar\fR routine returns the user's current erase character.
-
+.PP
The \fBerasewchar\fR routine stores the current erase character
in the location referenced by \fIch\fR.
If no erase character has been defined, the routine fails
and the location referenced by \fIch\fR is not changed.
-
+.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
be used to determine if it would be appropriate to turn on physical
scrolling using \fBscrollok\fR.
-
+.PP
The \fBkillchar\fR routine returns the user's current line kill character.
-
+.PP
The \fBkillwchar\fR routine stores the current line-kill character
in the location referenced by \fIch\fR.
If no line-kill character has been defined,
the routine fails and the location referenced by \fIch\fR is not changed.
-
+.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
@@ -100,7 +100,7 @@ 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.
-
+.PP
If a given terminal doesn't support a video attribute that an
application program is trying to use, \fBcurses\fR may substitute a
different video attribute for it.
@@ -109,12 +109,11 @@ 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.
-
-The \fBtermname\fR routine returns the value of the environmental
-variable \fBTERM\fR (truncated to 14 characters).
+.PP
+The \fBtermname\fR routine returns the terminal name used by \fBsetupterm\fR.
.SH RETURN VALUE
\fBlongname\fR and \fBtermname\fR return \fBNULL\fR on error.
-
+.PP
Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
completion.
@@ -123,6 +122,8 @@ Note that \fBtermattrs\fR may be a macro.
.SH PORTABILITY
The XSI Curses standard, Issue 4 describes these functions. It changes the
return type of \fBtermattrs\fR to the new type \fBattr_t\fR.
+Most versions of curses truncate the result returned by \fBtermname\fR to
+14 characters.
.SH SEE ALSO
\fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_outopts\fR(3X)
.\"#
diff --git a/contrib/ncurses/man/curs_termcap.3x b/contrib/ncurses/man/curs_termcap.3x
index 828bb9ad3cfd..e8072dc95bcf 100644
--- a/contrib/ncurses/man/curs_termcap.3x
+++ b/contrib/ncurses/man/curs_termcap.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2001,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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_termcap.3x,v 1.16 2002/02/16 19:26:41 tom Exp $
+.\" $Id: curs_termcap.3x,v 1.20 2006/02/25 21:50:01 tom Exp $
.TH curs_termcap 3X ""
.ds n 5
.SH NAME
@@ -40,12 +40,15 @@
\fB#include <curses.h>\fR
.br
\fB#include <term.h>\fR
-.br
+.sp
\fBextern char PC;\fR
+.br
\fBextern char * UP;\fR
+.br
\fBextern char * BC;\fR
-\fBextern @NCURSES_OSPEED@ ospeed;\fR
.br
+\fBextern @NCURSES_OSPEED@ ospeed;\fR
+.sp
\fBint tgetent(char *bp, const char *name);\fR
.br
\fBint tgetflag(char *id);\fR
@@ -64,36 +67,36 @@ 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.
-
+.PP
The \fBtgetent\fR routine loads the entry for \fIname\fR.
It returns 1 on success, 0 if there is no such entry, and -1 if the
terminfo database could not be found.
The emulation ignores the buffer pointer \fIbp\fR.
-
+.PP
The \fBtgetflag\fR routine gets the boolean entry for \fIid\fR,
or zero if it is not available.
-
+.PP
The \fBtgetnum\fR routine gets the numeric entry for \fIid\fR,
or -1 if it is not available.
-
+.PP
The \fBtgetstr\fR routine returns the string entry for \fIid\fR,
or zero if it is not available.
Use \fBtputs\fR to output the returned string.
The return value will also be copied to the buffer pointed to by \fIarea\fR,
and the \fIarea\fR value will be updated to point past the null ending
this value.
-
+.PP
Only the first two characters of the \fBid\fR parameter of
\fBtgetflag\fR,
\fBtgetnum\fR and
\fBtgetstr\fR are compared in lookups.
-
+.PP
The \fBtgoto\fR routine instantiates the parameters into the given capability.
The output from this routine is to be passed to \fBtputs\fR.
-
+.PP
The \fBtputs\fR routine is described on the \fBcurs_terminfo\fR(3X) manual
page. It can retrieve capabilities by either termcap or terminfo name.
-
+.PP
The variables
\fBPC\fR,
\fBUP\fR and
@@ -108,13 +111,13 @@ respectively.
\fBBC\fR is used in the \fBtgoto\fR emulation.
The variable \fBospeed\fR is set by ncurses in a system-specific coding
to reflect the terminal speed.
-
+.
.SH RETURN VALUE
Except where explicitly noted,
routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
completion.
-
+.PP
Routines that return pointers return \fBNULL\fR on error.
.SH BUGS
If you call \fBtgetstr\fR to fetch \fBca\fR or any other parameterized string,
@@ -126,14 +129,20 @@ terminfo-style strings as terminfo.
if the string is indeed terminfo-style by looking for "%p" parameters or
"$<..>" delays, and invoke a termcap-style parser if the string does not
appear to be terminfo).
-
+.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.
+.PP
+Note that termcap has nothing analogous to terminfo's \fBsgr\fR string.
+One consequence of this is that termcap applications assume \fRme\fR
+(terminfo \fBsgr0\fR) does not reset the alternate character set.
+This implementation checks for, and modifies the data shown to the
+termcap interface to accommodate termcap's limitation in this respect.
.SH PORTABILITY
The XSI Curses standard, Issue 4 describes these functions. However, they
are marked TO BE WITHDRAWN and may be removed in future versions.
-
+.PP
Neither the XSI Curses standard nor the SVr4 man pages documented the return
values of \fBtgetent\fR correctly, though all three were in fact returned ever
since SVr1.
@@ -142,7 +151,7 @@ misinterpreted to mean that \fBtgetent\fR returns \fBOK\fR or \fBERR\fR.
Because the purpose of these functions is to provide compatibility with
the \fItermcap\fR library, that is a defect in XCurses, Issue 4, Version 2
rather than in ncurses.
-
+.PP
External variables are provided for support of certain termcap applications.
However, termcap applications' use of those variables is poorly documented,
e.g., not distinguishing between input and output.
diff --git a/contrib/ncurses/man/curs_terminfo.3x b/contrib/ncurses/man/curs_terminfo.3x
index c61b695ace0b..435ac35b7c3e 100644
--- a/contrib/ncurses/man/curs_terminfo.3x
+++ b/contrib/ncurses/man/curs_terminfo.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1999-2000,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1999-2005,2006 Free 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,11 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_terminfo.3x,v 1.15 2002/05/11 21:19:29 tom Exp $
+.\" $Id: curs_terminfo.3x,v 1.24 2006/11/04 21:50:03 tom Exp $
.TH curs_terminfo 3X ""
.ds n 5
+.na
+.hy 0
.SH NAME
\fBdel_curterm\fR,
\fBmvcur\fR,
@@ -46,15 +48,17 @@
\fBvid_puts\fR,
\fBvidattr\fR,
\fBvidputs\fR - \fBcurses\fR interfaces to terminfo database
+.ad
+.hy
.SH SYNOPSIS
.nf
\fB#include <curses.h>\fR
.br
\fB#include <term.h>\fR
-
-\fBint setupterm(const char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
+.PP
+\fBint setupterm(char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
.br
-\fBint setterm(const char *\fR\fIterm\fR\fB);\fR
+\fBint setterm(char *\fR\fIterm\fR\fB);\fR
.br
\fBTERMINAL *set_curterm(TERMINAL *\fR\fInterm\fR\fB);\fR
.br
@@ -62,13 +66,13 @@
.br
\fBint restartterm(const char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
.br
-\fBchar *tparm(const char *\fR\fIstr\fR\fB, ...);\fR
+\fBchar *tparm(char *\fR\fIstr\fR\fB, ...);\fR
.br
\fBint tputs(const char *\fR\fIstr\fR\fB, int \fR\fIaffcnt\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
.br
\fBint putp(const char *\fR\fIstr\fR\fB);\fR
.br
-\fBint vidputs(chtype \fR\fIattrs\fR\fB, int (*\fR\fIputc\fR\fB)(char));\fR
+\fBint vidputs(chtype \fR\fIattrs\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
.br
\fBint vidattr(chtype \fR\fIattrs\fR\fB);\fR
.br
@@ -78,11 +82,11 @@
.br
\fBint mvcur(int \fR\fIoldrow\fR\fB, int \fR\fIoldcol\fR\fB, int \fR\fInewrow\fR, int \fR\fInewcol\fR\fB);\fR
.br
-\fBint tigetflag(const char *\fR\fIcapname\fR\fB);\fR
+\fBint tigetflag(char *\fR\fIcapname\fR\fB);\fR
.br
-\fBint tigetnum(const char *\fR\fIcapname\fR\fB);\fR
+\fBint tigetnum(char *\fR\fIcapname\fR\fB);\fR
.br
-\fBchar *tigetstr(const char *\fR\fIcapname\fR\fB);\fR
+\fBchar *tigetstr(char *\fR\fIcapname\fR\fB);\fR
.br
.fi
.SH DESCRIPTION
@@ -91,7 +95,7 @@ directly with the \fBterminfo\fR database to handle certain terminal
capabilities, such as programming function keys. For all other
functionality, \fBcurses\fR routines are more suitable and their use is
recommended.
-
+.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
@@ -105,21 +109,21 @@ exist and the program is running in a window, the current window size
is used. Otherwise, if the environment variables do not exist, the
values for \fBlines\fR and \fBcolumns\fR specified in the
\fBterminfo\fR database are used.
-
+.PP
The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this
order) to get the definitions for these strings, numbers, and flags.
-Parameterized strings should be passed through \fBtparm\fR to instantiate them.
+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 the \fBreset_shell_mode\fR to restore the
tty modes before exiting [see \fBcurs_kernel\fR(3X)]. Programs which use
cursor addressing should output \fBenter_ca_mode\fR upon startup and should
output \fBexit_ca_mode\fR before exiting. Programs desiring shell escapes
should call
-
+.PP
\fBreset_shell_mode\fR and output \fBexit_ca_mode\fR before the shell
is called and should output \fBenter_ca_mode\fR and 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
@@ -150,60 +154,60 @@ means that the \fBterminfo\fR database could not be found.
If \fIerrret\fR is
null, \fBsetupterm\fR prints an error message upon finding an error
and exits. Thus, the simplest call is:
-
+.sp
\fBsetupterm((char *)0, 1, (int *)0);\fR,
-
+.sp
which uses all the defaults and sends the output to \fBstdout\fR.
-
+.PP
The \fBsetterm\fR routine is being replaced by \fBsetupterm\fR. The call:
-
+.sp
\fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR
-
+.sp
provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR.
The \fBsetterm\fR routine is included here for BSD compatibility, and
is not recommended for new programs.
-
+.PP
The \fBset_curterm\fR routine sets the variable \fBcur_term\fR to
\fInterm\fR, and makes all of the \fBterminfo\fR boolean, numeric, and
string variables use the values from \fInterm\fR. It returns the old value
of \fBcur_term\fR.
-
+.PP
The \fBdel_curterm\fR routine frees the space pointed to by
\fIoterm\fR and makes it available for further use. If \fIoterm\fR is
the same as \fBcur_term\fR, references to any of the \fBterminfo\fR
boolean, numeric, and string variables thereafter may refer to invalid
memory locations until another \fBsetupterm\fR has been called.
-
+.PP
The \fBrestartterm\fR routine is similar to \fBsetupterm\fR and \fBinitscr\fR,
except that it is called after restoring memory to a previous state (for
example, when reloading a game saved as a core image dump). It assumes that
the windows and the input and output options are the same as when memory was
saved, but the terminal type and baud rate may be different. Accordingly,
it saves various tty state bits, does a setupterm, and then restores the bits.
-
+.PP
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.
-
+.PP
The \fBtputs\fR routine applies padding information to the string
\fIstr\fR and outputs it. The \fIstr\fR must be a terminfo string
variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or
\fBtgoto\fR. \fIaffcnt\fR is the number of lines affected, or 1 if
not applicable. \fIputc\fR is a \fBputchar\fR-like routine to which
the characters are passed, one at a time.
-
+.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.
-
+.PP
The \fBvidputs\fR routine displays the string on the terminal in the
video attribute mode \fIattrs\fR, which is any combination of the
attributes listed in \fBcurses\fR(3X). The characters are passed to
the \fBputchar\fR-like routine \fIputc\fR.
-
+.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.
They use a set of arguments for representing the video attributes plus color,
@@ -214,35 +218,37 @@ 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
effect immediately (rather than at the next refresh).
-
+.PP
The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return
the value of the capability corresponding to the \fBterminfo\fR
\fIcapname\fR passed to them, such as \fBxenl\fR.
-
+.PP
The \fBtigetflag\fR routine returns the value \fB-1\fR if
\fIcapname\fR is not a boolean capability,
or \fB0\fR if it is canceled or absent from the terminal description.
-
+.PP
The \fBtigetnum\fR routine returns the value \fB-2\fR if
\fIcapname\fR is not a numeric capability,
or \fB-1\fR if it is canceled or absent from the terminal description.
-
+.PP
The \fBtigetstr\fR routine returns the value \fB(char *)-1\fR
if \fIcapname\fR is not a string capability,
or \fB0\fR if it is canceled or absent from the terminal description.
-
+.PP
The \fIcapname\fR for each capability is given in the table column entitled
\fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n).
-
-\fBchar *boolnames\fR, \fB*boolcodes\fR, \fB*boolfnames\fR
-
-\fBchar *numnames\fR, \fB*numcodes\fR, \fB*numfnames\fR
-
-\fBchar *strnames\fR, \fB*strcodes\fR, \fB*strfnames\fR
-
+.sp
+.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
+.RE
+.PP
These null-terminated arrays contain the \fIcapnames\fR, the
\fBtermcap\fR codes, and the full C names, for each of the
\fBterminfo\fR variables.
@@ -250,40 +256,65 @@ These null-terminated arrays contain the \fIcapnames\fR, the
Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
completion, unless otherwise noted in the preceding routine descriptions.
-
+.PP
Routines that return pointers always return \fBNULL\fR on error.
+.PP
+X/Open defines no error conditions.
+In this implementation
+.RS
+.TP 5
+\fBdel_curterm\fP
+returns an error
+if its terminal parameter is null.
+.TP 5
+\fBrestartterm\fP
+returns an error
+if the associated call to \fBsetupterm\fP returns an error.
+.TP 5
+\fBsetupterm\fP
+returns an error
+if it cannot allocate enough memory, or
+create the initial windows (stdscr, curscr, newscr).
+Other error conditions are documented above.
+.RE
.SH NOTES
The \fBsetupterm\fR routine should be used in place of \fBsetterm\fR.
It may be useful when you want to test for terminal capabilities without
committing to the allocation of storage involved in \fBinitscr\fR.
-
+.PP
Note that \fBvidattr\fR and \fBvidputs\fR may be macros.
.SH PORTABILITY
The function \fBsetterm\fR is not described in the XSI Curses standard and must
be considered non-portable. All other functions are as described in the XSI
curses standard.
-
+.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 XSI Curses
semantics.
-
+.PP
In System V Release 4, the third argument of \fBtputs\fR has the type
\fBint (*putc)(char)\fR.
-
+.PP
The XSI Curses standard prototypes \fBtparm\fR with a fixed number of parameters,
rather than a variable argument list.
-That prototype assumes that none of the parameters are strings
-(or if so, that a long is big enough to hold a pointer).
-The variable argument list implemented in ncurses does not rely on
-that assumption.
-
+This implementation uses a variable argument list.
+Portable applications should provide 9 parameters after the format;
+zeroes are fine for this purpose.
+.PP
XSI notes that after calling \fBmvcur\fR, the curses state may not match the
actual terminal state, and that an application should touch and refresh
the window before resuming normal curses calls.
Both ncurses and System V Release 4 curses implement \fBmvcur\fR using
-the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR.
+the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR.
So though it is documented as a terminfo function,
\fBmvcur\fR is really a curses function which is not well specified.
+.PP
+XSI states that the old location must be given.
+This implementation allows the caller to use -1's for the old ordinates.
+In that case, the old location is unknown.
+.PP
+Extended terminal capability names, e.g., as defined by \fBtic\ -x\fP,
+are not stored in the arrays described in this section.
.SH SEE ALSO
\fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_termcap\fR(3X),
\fBputc\fR(3S), \fBterminfo\fR(\*n)
diff --git a/contrib/ncurses/man/curs_touch.3x b/contrib/ncurses/man/curs_touch.3x
index 58ffa9f6042b..a7d07bc3ffbe 100644
--- a/contrib/ncurses/man/curs_touch.3x
+++ b/contrib/ncurses/man/curs_touch.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_touch.3x,v 1.8 2000/07/08 11:07:57 tom Exp $
+.\" $Id: curs_touch.3x,v 1.11 2006/02/25 21:49:19 tom Exp $
.TH curs_touch 3X ""
+.na
+.hy 0
.SH NAME
\fBtouchwin\fR,
\fBtouchline\fR,
@@ -35,6 +37,8 @@
\fBwtouchln\fR,
\fBis_linetouched\fR,
\fBis_wintouched\fR - \fBcurses\fR refresh control routines
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
.br
@@ -59,15 +63,15 @@ to one window affects the other window, but the records of which lines
have been changed in the other window do not reflect the change. The
routine \fBtouchline\fR only pretends that \fIcount\fR lines have been
changed, beginning with line \fIstart\fR.
-
+.PP
The \fBuntouchwin\fR routine marks all lines in the window as unchanged since
the last call to \fBwrefresh\fR.
-
+.PP
The \fBwtouchln\fR routine makes \fIn\fR lines in the window, starting
at line \fIy\fR, look as if they have (\fIchanged\fR\fB=1\fR) or have
not (\fIchanged\fR\fB=0\fR) been changed since the last call to
\fBwrefresh\fR.
-
+.PP
The \fBis_linetouched\fR and \fBis_wintouched\fR routines return
\fBTRUE\fR if the specified line/window was modified since the last
call to \fBwrefresh\fR; otherwise they return \fBFALSE\fR. In
@@ -77,9 +81,25 @@ valid for the given window.
All routines return the integer \fBERR\fR upon failure and an integer value
other than \fBERR\fR upon successful completion, unless otherwise noted in the
preceding routine descriptions.
+.PP
+X/Open does not define any error conditions.
+In this implementation
+.RS
+.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.
+.TP 5
+\fBwtouchln\fP
+returns an error
+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
diff --git a/contrib/ncurses/man/curs_trace.3x b/contrib/ncurses/man/curs_trace.3x
index 4af258da3b09..560302c42cc7 100644
--- a/contrib/ncurses/man/curs_trace.3x
+++ b/contrib/ncurses/man/curs_trace.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 2000,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 2000-2002,2005 Free 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,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_trace.3x,v 1.5 2002/02/16 22:39:52 tom Exp $
+.\" $Id: curs_trace.3x,v 1.7 2005/05/15 17:02:54 tom Exp $
.TH curs_trace 3X ""
+.na
+.hy 0
.SH NAME
\fB_tracef\fR,
\fB_tracedump\fR,
@@ -39,9 +41,11 @@
\fB_tracechtype2\fR,
\fB_tracemouse\fR,
\fBtrace\fR - \fBcurses\fR debugging routines
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-.br
+.sp
\fBvoid _tracef(const char *format, ...);\fR
.br
\fBvoid _tracedump(const char *label, WINDOW *win);\fR
@@ -67,11 +71,11 @@ 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,
profile) by defining the symbol \fBTRACE\fR.
-
+.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.
-
+.PP
Calling \fBtrace\fR with a nonzero parameter opens the file \fBtrace\fR
in the current directory for output. The parameter is formed by OR'ing
values from the list of \fBTRACE_\fP\fIxxx\fR definitions in \fB<curses.h>\fR.
@@ -127,7 +131,7 @@ trace changes to video attributes and colors.
.TP 5
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.
The specific names are used as a guideline.
diff --git a/contrib/ncurses/man/curs_util.3x b/contrib/ncurses/man/curs_util.3x
index 09d490d1d1a6..e78f99935326 100644
--- a/contrib/ncurses/man/curs_util.3x
+++ b/contrib/ncurses/man/curs_util.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2001,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_util.3x,v 1.8 2002/02/23 22:55:47 tom Exp $
+.\" $Id: curs_util.3x,v 1.21 2006/08/26 14:17:48 tom Exp $
.TH curs_util 3X ""
+.na
+.hy 0
.SH NAME
\fBdelay_output\fR,
\fBfilter\fR,
@@ -35,16 +37,19 @@
\fBgetwin\fR,
\fBkey_name\fR,
\fBkeyname\fR,
+\fBnofilter\fR,
\fBputwin\fR,
\fBunctrl\fR,
\fBuse_env\fR,
\fBwunctrl\fR - miscellaneous \fBcurses\fR utility routines
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBchar *unctrl(chtype c);\fR
.br
-\fBchar *wunctrl(wchar_t w);\fR
+\fBchar *wunctrl(cchar_t *c);\fR
.br
\fBchar *keyname(int c);\fR
.br
@@ -52,6 +57,8 @@
.br
\fBvoid filter(void);\fR
.br
+\fBvoid nofilter(void);\fR
+.br
\fBvoid use_env(bool f);\fR
.br
\fBint putwin(WINDOW *win, FILE *filep);\fR
@@ -69,23 +76,29 @@ 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.
-
+.PP
The \fBkeyname\fR routine returns a character string corresponding to the key \fIc\fR.
Control characters are displayed in the \fB^\fR\fIX\fR notation.
Values above 128 are either meta characters, shown in the \fBM-\fR\fIX\fR notation,
-or the names of function keys, or
-"UNKNOWN STRING".
+or the names of function keys, or null.
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 "UNKNOWN STRING" where the former would display a meta character.
-
+the latter returns null where the former would display a meta character.
+.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.
-
+.PP
+The \fBnofilter\fP routine cancels the effect of a preceding \fBfilter\fP
+call.
+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.
+.PP
The \fBuse_env\fR routine, if used, is called before \fBinitscr\fR or
\fBnewterm\fR are called. When called with \fBFALSE\fR as an
argument, the values of \fBlines\fR and \fBcolumns\fR specified in the
@@ -94,39 +107,82 @@ argument, the values of \fBlines\fR and \fBcolumns\fR specified in the
\fBcurses\fR is running in a window (in which case default behavior
would be to use the window size if \fBLINES\fR and \fBCOLUMNS\fR are
not set).
-
+Note that setting \fBLINES\fR or \fBCOLUMNS\fR overrides the
+corresponding size which may be obtained from the operating system.
+.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
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.
-
+.PP
The \fBdelay_output\fR routine inserts an \fIms\fR millisecond pause
in output. This routine should not be used extensively because
padding characters are used rather than a CPU pause.
-
+If no padding character is specified, this uses \fBnapms\fR to perform the delay.
+.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.
.SH RETURN VALUE
Except for \fBflushinp\fR, routines that return an integer return \fBERR\fR
upon failure and \fBOK\fR (SVr4 specifies only "an integer value other than
\fBERR\fR") upon successful completion.
-
-\fBflushinp\fR always returns \fBOK\fR.
-
+.PP
Routines that return pointers return \fBNULL\fR on error.
+.PP
+X/Open does not define any error conditions.
+In this implementation
+.RS
+.TP 5
+\fBflushinp\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
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.
-
+.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 `^'.
+Other implementations have different conventions.
+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-1280 codes as
+printable.
+This implementation uses 8 bits but does not modify the string to reflect
+locale.
+The \fBuse_legacy_coding\fP function allows the caller to
+change the output of \fBunctrl\fP.
+.PP
+The \fBkeyname\fP function may return the names of user-defined
+string capabilities which are defined in the terminfo entry via the \fB-x\fP
+option of \fBtic\fP.
+This implementation automatically assigns at run-time keycodes to
+user-defined strings which begin with "k".
+The keycodes start at KEY_MAX, but are not guaranteed to be
+the same value for different runs because user-defined codes are
+merged from all terminal descriptions which have been loaded.
+.PP
+The \fBnofilter\fP routine is specific to ncurses.
+It was not supported on Version 7, BSD or System V implementations.
+It is recommended that any code depending on ncurses extensions
+be conditioned using NCURSES_VERSION.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_scr_dump\fR(3X).
+\fBuse_legacy_coding\fR(3),
+\fBcurses\fR(3X),
+\fBcurs_initscr\fR(3X),
+\fBcurs_kernel\fR(3X),
+\fBcurs_scr_dump\fR(3X).
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/curs_window.3x b/contrib/ncurses/man/curs_window.3x
index 4d3ca4ca00c3..552862e9e253 100644
--- a/contrib/ncurses/man/curs_window.3x
+++ b/contrib/ncurses/man/curs_window.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_window.3x,v 1.9 2000/07/01 20:08:37 tom Exp $
+.\" $Id: curs_window.3x,v 1.14 2006/02/25 21:49:19 tom Exp $
.TH curs_window 3X ""
+.na
+.hy 0
.SH NAME
\fBnewwin\fR,
\fBdelwin\fR,
@@ -40,9 +42,11 @@
\fBsyncok\fR,
\fBwcursyncup\fR,
\fBwsyncdown\fR - create \fBcurses\fR windows
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBWINDOW *newwin(int nlines, int ncols, int begin_y,\fR
\fBint begin_x);\fR
.br
@@ -75,17 +79,17 @@ 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.
-
+.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.
-
+.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.
-
+.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,
@@ -96,29 +100,29 @@ will affect both windows. The subwindow shares memory with the window
\fIorig\fR. When using this routine, it is necessary to call
\fBtouchwin\fR or \fBtouchline\fR on \fIorig\fR before calling
\fBwrefresh\fR on the subwindow.
-
+.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.
-
+.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
parts of the parent window at the same physical position on the
screen.
-
+.PP
Calling \fBdupwin\fR creates an exact duplicate of the window \fIwin\fR.
-
+.PP
Calling \fBwsyncup\fR touches all locations in ancestors of \fIwin\fR that are
changed in \fIwin\fR. If \fBsyncok\fR is called with second argument
\fBTRUE\fR then \fBwsyncup\fR is called automatically whenever there is a
change in the window.
-
+.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
\fBwrefresh\fR, so it should almost never be necessary to call it manually.
-
+.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
window.
@@ -126,23 +130,48 @@ window.
Routines that return an integer return the integer \fBERR\fR upon failure and
\fBOK\fR (SVr4 only specifies "an integer value other than \fBERR\fR") upon
successful completion.
-
-\fBdelwin\fR returns the integer \fBERR\fR upon failure and \fBOK\fR
-upon successful completion.
-
+.PP
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.
+.IP
+This implementation also maintains a list of windows,
+and checks that the pointer passed to \fBdelwin\fP is one that
+it created, returning an error if it was not..
+.TP 5
+\fBmvderwin\fP
+returns an error
+if the window pointer is null, or
+if some part of the window would be placed off-screen.
+.TP 5
+\fBmvwin\fP
+returns an error
+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
+\fBsyncok\fP
+returns an error
+if the window pointer is null.
+.RE
.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,
\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
diff --git a/contrib/ncurses/man/default_colors.3x b/contrib/ncurses/man/default_colors.3x
index 4ebb90124a8a..ce313e2b51a9 100644
--- a/contrib/ncurses/man/default_colors.3x
+++ b/contrib/ncurses/man/default_colors.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2000,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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. *
.\"***************************************************************************
.\"
-.\" Author: Thomas E. Dickey <dickey@clark.net> 1997,1999,2000
+.\" Author: Thomas E. Dickey 1997,1999,2000,2005
.\"
-.\" $Id: default_colors.3x,v 1.16 2002/02/16 22:39:52 tom Exp $
+.\" $Id: default_colors.3x,v 1.19 2006/02/25 21:49:19 tom Exp $
.TH default_colors 3X ""
.SH NAME
\fBuse_default_colors\fR,
\fBassume_default_colors\fR \- use terminal's default colors
.SH SYNOPSIS
\fB#include <curses.h>\fP
-
+.sp
\fBint use_default_colors(void);\fP
.br
\fBint assume_default_colors(int fg, int bg);\fP
@@ -107,6 +107,26 @@ error as well.
Associated with this extension, the \fBinit_pair\fR(3X) function accepts
negative arguments to specify default foreground or background
colors.
+.PP
+The \fIuse_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
+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.
+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
+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.
+.PP
+The \fIassume_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
diff --git a/contrib/ncurses/man/define_key.3x b/contrib/ncurses/man/define_key.3x
index 1019c42fd770..216a3cbce4b6 100644
--- a/contrib/ncurses/man/define_key.3x
+++ b/contrib/ncurses/man/define_key.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2004,2006 Free 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. *
.\"***************************************************************************
.\"
-.\" Author: Thomas E. Dickey <dickey@clark.net> 1997
+.\" Author: Thomas E. Dickey 1997
.\"
-.\" $Id: define_key.3x,v 1.8 2002/02/16 22:39:52 tom Exp $
+.\" $Id: define_key.3x,v 1.12 2006/02/25 21:49:19 tom Exp $
.TH define_key 3X ""
.SH NAME
\fBdefine_key\fP \- define a keycode
.SH SYNOPSIS
\fB#include <curses.h>\fP
-
-\fBint define_key(char *definition, int keycode);\fP
+.sp
+\fBint define_key(const char *definition, int keycode);\fP
.SH DESCRIPTION
This is an extension to the curses library.
It permits an application to define keycodes with their corresponding control
@@ -53,7 +53,8 @@ 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).
+\fBkeyok\fR(3X),
+\fBkey_defined\fR(3X).
.SH AUTHOR
Thomas Dickey.
.\"#
diff --git a/contrib/ncurses/man/form.3x b/contrib/ncurses/man/form.3x
index 811b9ff74739..264662e664ae 100644
--- a/contrib/ncurses/man/form.3x
+++ b/contrib/ncurses/man/form.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2002,2006 Free 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.3x,v 1.15 2002/01/19 22:48:05 tom Exp $
+.\" $Id: form.3x,v 1.20 2006/11/04 18:50:09 tom Exp $
.TH form 3X ""
.SH NAME
\fBform\fR - curses extension for programming forms
@@ -40,26 +40,26 @@ form screens on character-cell terminals. The library includes: field
routines, which create and modify form fields; and form routines, which group
fields into forms, display forms on the screen, and handle interaction with the
user.
-
+.PP
The \fBform\fR library uses the \fBcurses\fR libraries, and a curses
initialization routine such as \fBinitscr\fR must be called before using any of
these functions. To use the \fBform\fR library, link with the options
\fB-lform -lcurses\fR.
-
+.
.SS Current Default Values for Field Attributes
-
+.
The \fBform\fR library maintains a default value for field attributes. You
can get or set this default by calling the appropriate \fBset_\fR
or retrieval
routine with a \fBNULL\fR field pointer. Changing this default with a
\fBset_\fR function affects future field creations, but does not change the
rendering of fields already created.
-
+.
.SS Routine Name Index
-
+.
The following table lists each \fBform\fR routine and the name of
the manual page on which it is described.
-
+.
.TS
l l
l l .
@@ -101,11 +101,13 @@ form_term \fBform_hook\fR(3X)
form_userptr \fBform_userptr\fR(3X)
form_win \fBform_win\fR(3X)
free_field \fBform_field_new\fR(3X)
+free_fieldtype \fBform_fieldtype\fR(3X)
free_form \fBform_new\fR(3X)
link_field \fBform_field_new\fR(3X)
link_fieldtype \fBform_fieldtype\fR(3X)
move_field \fBform_field\fR(3X)
new_field \fBform_field_new\fR(3X)
+new_fieldtype \fBform_fieldtype\fR(3X)
new_form \fBform_new\fR(3X)
new_page \fBform_new_page\fR(3X)
pos_form_cursor \fBform_cursor\fR(3X)
@@ -138,60 +140,66 @@ set_new_page \fBform_new_page\fR(3X)
unpost_form \fBform_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,
+and set errno to the corresponding error-code returned by functions
+returning an integer.
+Routines that return
an integer return one of the following error codes:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_CONNECTED\fR
-The field is already connected to a form.
-.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
-.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_POSTED\fR
-The form is already posted.
-.TP 5
-\fBE_BAD_STATE\fR
+.B E_BAD_STATE
Routine was called from an initialization or termination function.
.TP 5
-\fBE_NO_ROOM\fR
-Form is too large for its window.
-.TP 5
-\fBE_NOT_POSTED\fR
-The form has not been posted.
-.TP 5
-\fBE_UNKNOWN_COMMAND\fR
-The form driver code saw an unknown request code.
+.B E_CONNECTED
+The field is already connected to a form.
.TP 5
-\fBE_INVALID_FIELD\fR
+.B E_INVALID_FIELD
Contents of a field are not valid.
.TP 5
-\fBE_NOT_CONNECTED\fR
+.B E_NOT_CONNECTED
No fields are connected to the form.
.TP 5
-\fBE_REQUEST_DENIED\fR
+.B E_NOT_POSTED
+The form has not been posted.
+.TP 5
+.B E_NO_ROOM
+Form is too large for its window.
+.TP 5
+.B E_POSTED
+The form is already posted.
+.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).
+.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 GNU \fBld\fR(1) and many other linkers).
+give you a link error using most linkers).
.SH PORTABILITY
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 ncurses by Eric
S. Raymond.
+.SH SEE ALSO
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/form_cursor.3x b/contrib/ncurses/man/form_cursor.3x
index ab37c99e7fae..bf9f28d6c61e 100644
--- a/contrib/ncurses/man/form_cursor.3x
+++ b/contrib/ncurses/man/form_cursor.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_cursor.3x,v 1.4 1998/11/29 01:05:43 Rick.Ohnemus Exp $
+.\" $Id: form_cursor.3x,v 1.6 2006/11/04 18:50:24 tom Exp $
.TH form_cursor 3X ""
.SH NAME
\fBform_cursor\fR - position a form window cursor
@@ -44,17 +44,18 @@ form operation.
.SH RETURN VALUE
This routine returns one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
-.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_NOT_POSTED\fR
+.B E_NOT_POSTED
The form has not been posted.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).
+.
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
.SH NOTES
diff --git a/contrib/ncurses/man/form_data.3x b/contrib/ncurses/man/form_data.3x
index 3767e954590c..2ba004c3387e 100644
--- a/contrib/ncurses/man/form_data.3x
+++ b/contrib/ncurses/man/form_data.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_data.3x,v 1.7 1998/11/29 01:13:22 Rick.Ohnemus Exp $
+.\" $Id: form_data.3x,v 1.8 2006/02/25 21:38:26 tom Exp $
.TH form_data 3X ""
.SH NAME
\fBform_data\fR - test for off-screen data in given forms
@@ -41,7 +41,7 @@ bool data_behind(const FORM *form);
.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).
-
+.PP
The function \fBdata_behind\fR tests whether there is off-screen data
behind in the given form. It returns TRUE (1) or FALSE (0).
.SH SEE ALSO
diff --git a/contrib/ncurses/man/form_driver.3x b/contrib/ncurses/man/form_driver.3x
index 235408910196..c88e3be0ae1c 100644
--- a/contrib/ncurses/man/form_driver.3x
+++ b/contrib/ncurses/man/form_driver.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2002,2006 Free 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: form_driver.3x,v 1.9 2002/02/16 22:39:52 tom Exp $
+.\" $Id: form_driver.3x,v 1.12 2006/11/04 18:51:00 tom Exp $
.TH form_driver 3X ""
.SH NAME
\fBform_driver\fR - command-processing loop of the form system
@@ -52,7 +52,7 @@ 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.
@@ -89,7 +89,7 @@ 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.
@@ -132,7 +132,7 @@ 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.
@@ -169,7 +169,7 @@ Enter overlay mode.
.TP 5
REQ_INS_MODE
Enter insert mode.
-
+.sp
.TP 5
REQ_SCR_FLINE
Scroll the field forward a line.
@@ -188,7 +188,7 @@ 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.
@@ -207,7 +207,7 @@ 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.
@@ -228,31 +228,32 @@ 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.
.SH RETURN VALUE
-\fBform_driver\fR return one of the following error codes:
+\fBform_driver\fR returns one of the following error codes:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
-.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_BAD_STATE\fR
+.B E_BAD_STATE
Routine was called from an initialization or termination function.
.TP 5
-\fBE_NOT_POSTED\fR
+.B E_NOT_POSTED
The form has not been posted.
.TP 5
-\fBE_UNKNOWN_COMMAND\fR
-The form driver code saw an unknown request code.
-.TP 5
-\fBE_INVALID_FIELD\fR
+.B E_INVALID_FIELD
Contents of field is invalid.
.TP 5
-\fBE_REQUEST_DENIED\fR
+.B E_REQUEST_DENIED
The form driver could not process the request.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).
+.TP 5
+.B E_UNKNOWN_COMMAND
+The form driver code saw an unknown request code.
+.
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
.SH NOTES
diff --git a/contrib/ncurses/man/form_field.3x b/contrib/ncurses/man/form_field.3x
index f452036baeab..f3a26c57dac0 100644
--- a/contrib/ncurses/man/form_field.3x
+++ b/contrib/ncurses/man/form_field.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2006 Free 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.5 1998/11/29 01:05:52 Rick.Ohnemus Exp $
+.\" $Id: form_field.3x,v 1.8 2006/11/04 18:01:38 tom Exp $
.TH form_field 3X ""
.SH NAME
\fBform_field\fR - make and break connections between fields and forms
@@ -45,36 +45,37 @@ int move_field(FIELD *field, int frow, int fcol);
.SH DESCRIPTION
The function \fBset_form_fields\fR changes the field pointer array of
the given \fIform\fR. The array must be terminated by a \fBNULL\fR.
-
+.PP
The function \fBform_fields\fR returns the field array of the given form.
-
+.PP
The function \fBfield_count\fR returns the count of fields in \fIform\fR.
-
-The function \fBmove_field\fR move the given field (which must be disconnected)
+.PP
+The function \fBmove_field\fR moves the given field (which must be disconnected)
to a specified location on the screen.
.SH RETURN VALUES
-The function \fBform_fields\fR returns \fBNULL\fR on error.
-
-The function \fBfield_count\fR returns \fBERR\fR (the general
-\fBcurses\fR error return value) on error.
-
+The function \fBform_fields\fR returns a pointer (which may be \fBNULL\fR).
+It does not set errno.
+.PP
+The function \fBfield_count\fR returns \fBERR\fR if the \fIform\fP parameter
+is \fBNULL\fP.
+.PP
The functions \fBset_form_fields\fR and \fBmove_field\fR return one of
the following codes on error:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
-.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_POSTED\fR
+.B E_CONNECTED
+The field is already connected to a form.
+.TP 5
+.B E_POSTED
The form is already posted.
.TP 5
-\fBE_CONNECTED\fR
-The field is already connected to a form.
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
.SH NOTES
@@ -83,7 +84,7 @@ The header file \fB<form.h>\fR automatically includes the header file
.SH PORTABILITY
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
diff --git a/contrib/ncurses/man/form_field_attributes.3x b/contrib/ncurses/man/form_field_attributes.3x
index ac7a3b53eece..90dc0f31b63b 100644
--- a/contrib/ncurses/man/form_field_attributes.3x
+++ b/contrib/ncurses/man/form_field_attributes.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2001,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2002,2006 Free 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_attributes.3x,v 1.7 2002/01/19 22:48:14 tom Exp $
+.\" $Id: form_field_attributes.3x,v 1.10 2006/11/04 18:51:26 tom Exp $
.TH form_field_attributes 3X ""
.SH NAME
\fBform_field_attributes\fR - color and attribute control for form fields
@@ -51,26 +51,27 @@ The function \fBset_field_fore\fR sets the foreground attribute of
\fIfield\fR. This is the highlight used to display the field contents. The
function \fBfield_fore\fR returns the foreground attribute. The default is
\fBA_STANDOUT\fR.
-
+.PP
The function \fBset_field_back\fR sets the background attribute of
\fIform\fR. This is the highlight used to display the extent fields in the
form. The function \fBfield_back\fR returns the background attribute. The
default is \fBA_NORMAL\fR.
-
+.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
default is a blank.
.SH RETURN VALUE
These routines return one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
-.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).
+.
.SH SEE ALSO
\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed
descriptions of the entry points.
diff --git a/contrib/ncurses/man/form_field_buffer.3x b/contrib/ncurses/man/form_field_buffer.3x
index 814c5d9d58f4..cac6a088e5ed 100644
--- a/contrib/ncurses/man/form_field_buffer.3x
+++ b/contrib/ncurses/man/form_field_buffer.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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_buffer.3x,v 1.9 2002/01/19 22:48:23 tom Exp $
+.\" $Id: form_field_buffer.3x,v 1.14 2006/11/04 17:12:00 tom Exp $
.TH form_field_buffer 3X ""
.SH NAME
\fBform_field_buffer\fR - field buffer control
@@ -50,40 +50,53 @@ to contain a given string. Buffer 0 is the displayed value of the field; other
numbered buffers may be allocated by applications through the \fBnbuf\fR
argument of (see \fBform_field_new\fR(3X)) but are not manipulated by the forms
library. The function \fBfield_buffer\fR returns the address of the buffer.
-Please note that this buffer has always the length of the buffer, that means
+Please note that this buffer has always the length of the buffer, that means
that it may typically contain trailing spaces. If you entered leading spaces
the buffer may also contain them. If you want the raw data, you must write your
own routine that copies the value out of the buffer and removes the leading
and trailing spaces. Please note also, that subsequent operations on the form
-will probably change the content of the buffer. So don't use it for long term
+will probably change the content of the buffer. So do not use it for long term
storage of the entered form data.
-
+.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
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.
An argument of 0 turns off any maximum size threshold for that field.
.SH RETURN VALUE
The \fBfield_buffer\fR function returns NULL on error.
-
+It sets errno according to their success:
+.TP 5
+.B E_OK
+The routine succeeded.
+.TP 5
+.B E_BAD_ARGUMENT
+Routine detected an incorrect or out-of-range argument.
+.PP
The \fBfield_status\fR function returns \fBTRUE\fR or \fBFALSE\fR.
-
+.PP
The remaining routines return one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.SH SEE ALSO
\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed
descriptions of the entry points.
.SH NOTES
The header file \fB<form.h>\fR automatically includes the header file
+.PP
+When configured for wide-characters, \fBfield_buffer\fP returns a pointer
+to temporary storage (allocated and freed by the library).
+The application should not attempt to modify the data.
+It will be freed on the next call to \fBfield_buffer\fP to return the
+same buffer.
\fB<curses.h>\fR.
.SH PORTABILITY
These routines emulate the System V forms library. They were not supported on
diff --git a/contrib/ncurses/man/form_field_info.3x b/contrib/ncurses/man/form_field_info.3x
index 56b81ac7daa0..bde312856951 100644
--- a/contrib/ncurses/man/form_field_info.3x
+++ b/contrib/ncurses/man/form_field_info.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2000,2001,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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_info.3x,v 1.8 2002/01/19 22:48:32 tom Exp $
+.\" $Id: form_field_info.3x,v 1.10 2006/11/04 17:14:31 tom Exp $
.TH form_field_info 3X ""
.SH NAME
\fBform_field_info\fR - retrieve field characteristics
@@ -44,21 +44,22 @@ 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
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
-addressed by the third argument will be set to 0. (A field can be made dynamic
-by turning off the \fBO_STATIC\fR).
+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.
.SH RETURN VALUE
These routines return one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.TP 5
-\fBE_BAD_ARGUMENT\fR
+.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
diff --git a/contrib/ncurses/man/form_field_just.3x b/contrib/ncurses/man/form_field_just.3x
index 9468d8b77512..15d6cb254df1 100644
--- a/contrib/ncurses/man/form_field_just.3x
+++ b/contrib/ncurses/man/form_field_just.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2006 Free 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_just.3x,v 1.6 2002/01/19 22:48:41 tom Exp $
+.\" $Id: form_field_just.3x,v 1.9 2006/11/04 17:12:00 tom Exp $
.TH form_field_just 3X ""
.SH NAME
\fBform_field_just\fR - retrieve field characteristics
@@ -43,20 +43,20 @@ The function \fBset_field_just\fR sets the justification attribute of
a field; \fBfield_just\fR returns a field's justification attribute.
The attribute may be one of NO_JUSTIFICATION, JUSTIFY_RIGHT,
JUSTIFY_LEFT, or JUSTIFY_CENTER.
-
+.
.SH RETURN VALUE
The function \fBfield_just\fR returns one of: NO_JUSTIFICATION,
JUSTIFY_RIGHT, JUSTIFY_LEFT, or JUSTIFY_CENTER.
-
-The function \fBset_field_just\fR return one of the following:
+.PP
+The function \fBset_field_just\fR returns one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.TP 5
-\fBE_BAD_ARGUMENT\fR
+.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
diff --git a/contrib/ncurses/man/form_field_new.3x b/contrib/ncurses/man/form_field_new.3x
index 969152057d6d..168349ee77e9 100644
--- a/contrib/ncurses/man/form_field_new.3x
+++ b/contrib/ncurses/man/form_field_new.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2006 Free 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_new.3x,v 1.11 2002/02/16 22:39:52 tom Exp $
+.\" $Id: form_field_new.3x,v 1.14 2006/11/04 17:12:00 tom Exp $
.TH form_field_new 3X ""
.SH NAME
\fBform_field_new\fR - create and destroy form fields
@@ -48,31 +48,41 @@ int free_field(FIELD *field);
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
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
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.
-
+.PP
The function \fBfree_field\fR de-allocates storage associated with a field.
.SH RETURN VALUE
The function, \fBnew_field\fR, \fBdup_field\fR, \fBlink_field\fR return
\fBNULL\fR on error.
-
-The function \fBfree_field\fR returns one of the following:
+They set errno according to their success:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
+.B E_BAD_ARGUMENT
+Routine detected an incorrect or out-of-range argument.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred, e.g., malloc failure.
+.PP
+The function \fBfree_field\fR returns one of the following:
.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_OK
+The routine succeeded.
+.TP 5
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
+.TP 5
+.B E_CONNECTED
+field is connected.
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
.SH NOTES
@@ -81,10 +91,10 @@ The header file \fB<form.h>\fR automatically includes the header file
.SH PORTABILITY
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(3X) being portable; the System V forms library documents are
-not very explicit on what gets copied and was not.
+not very explicit about what gets copied and what doesn't.
.SH AUTHORS
Juergen Pfeifer. Manual pages and adaptation for new curses by Eric
S. Raymond.
diff --git a/contrib/ncurses/man/form_field_opts.3x b/contrib/ncurses/man/form_field_opts.3x
index 8f5e2def4315..87449f224993 100644
--- a/contrib/ncurses/man/form_field_opts.3x
+++ b/contrib/ncurses/man/form_field_opts.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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_opts.3x,v 1.7 1998/11/29 01:06:54 Rick.Ohnemus Exp $
+.\" $Id: form_field_opts.3x,v 1.12 2006/11/04 17:12:00 tom Exp $
.TH form_field_opts 3X ""
.SH NAME
\fBform_field_opts\fR - set and get field options
@@ -45,20 +45,20 @@ OPTIONS field_opts(const FIELD *field);
.SH DESCRIPTION
The function \fBset_field_opts\fR sets all the given field's option bits (field
option bits may be logically-OR'ed together).
-
+.PP
The function \fBfield_opts_on\fR turns on the given option bits, and leaves
others alone.
-
+.PP
The function \fBfield_opts_off\fR turns off the given option bits, and leaves
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,
+suppressed.
.TP 5
O_ACTIVE
The field is visited during processing. If this option is off, the field will
@@ -72,34 +72,38 @@ O_EDIT
The field can be edited.
.TP 5
O_WRAP
-Words that don't fit on a line are wrapped to the next line. Words are
+Words that do not fit on a line are wrapped to the next line. Words are
blank-separated.
.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
+Skip to the next field when this one fills.
.TP 5
O_NULLOK
Allow a blank field.
.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.
.SH RETURN VALUE
Except for \fBfield_opts\fR, each routine returns one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
+.B E_BAD_ARGUMENT
+Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_CURRENT\fR
+.B E_CURRENT
The field is the current field.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
.TP 5
diff --git a/contrib/ncurses/man/form_field_userptr.3x b/contrib/ncurses/man/form_field_userptr.3x
index 2aba2083bc01..47b9ed424d19 100644
--- a/contrib/ncurses/man/form_field_userptr.3x
+++ b/contrib/ncurses/man/form_field_userptr.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_userptr.3x,v 1.6 1998/11/29 01:07:05 Rick.Ohnemus Exp $
+.\" $Id: form_field_userptr.3x,v 1.8 2006/11/04 18:04:37 tom Exp $
.TH form_field_userptr 3X ""
.SH NAME
\fBform_field_userptr\fR - associate application data with a form field
@@ -43,14 +43,10 @@ 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 field.
.SH RETURN VALUE
-The function \fBfield_userptr\fR returns \fBNULL\fR on error. The function
-\fBset_field_userptr\fR returns one of the following:
-.TP 5
-\fBE_OK\fR
-The routine succeeded.
-.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
+The function \fBfield_userptr\fR returns a pointer (which may be \fBNULL\fR).
+It does not set errno.
+.PP
+The function \fBset_field_userptr\fR returns \fBE_OK\fP (success).
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
.SH NOTES
@@ -59,9 +55,9 @@ The header file \fB<form.h>\fR automatically includes the header file
.SH PORTABILITY
These routines emulate the System V forms library. They were not supported on
Version 7 or BSD versions.
-
-The user pointer should be a void pointer. We leave it as a char pointer for
-SVr4 compatibility.
+.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.
diff --git a/contrib/ncurses/man/form_field_validation.3x b/contrib/ncurses/man/form_field_validation.3x
index cc3d508d2d32..175268b49ea9 100644
--- a/contrib/ncurses/man/form_field_validation.3x
+++ b/contrib/ncurses/man/form_field_validation.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2006 Free 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,10 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_validation.3x,v 1.12 2002/02/16 22:39:52 tom Exp $
+.\" $Id: form_field_validation.3x,v 1.15 2006/11/04 17:14:19 tom Exp $
.TH form_field_validation 3X ""
.SH NAME
-\fBform_field_validation\fR - data type validation for fields
+\fBform_field_validation\fR - data type validation for fields
.SH SYNOPSIS
\fB#include <form.h>\fR
.br
@@ -38,10 +38,25 @@ int set_field_type(FIELD *field, FIELDTYPE *type, ...);
FIELDTYPE *field_type(const FIELD *field);
.br
void *field_arg(const FIELD *field);
+.sp
+FIELDTYPE *TYPE_ALNUM;
+.br
+FIELDTYPE *TYPE_ALPHA;
+.br
+FIELDTYPE *TYPE_ENUM;
+.br
+FIELDTYPE *TYPE_INTEGER;
+.br
+FIELDTYPE *TYPE_NUMERIC;
+.br
+FIELDTYPE *TYPE_REGEXP;
+.br
+FIELDTYPE *TYPE_IPV4;
.br
.SH DESCRIPTION
The function \fBset_field_type\fR declares a data type for a given form field.
-This is the type checked by validation functions. The types are as follows:
+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.
@@ -56,27 +71,29 @@ case-sensitivity; and a fifth \fBint\fR flag argument specifying whether a parti
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 not copied, only a reference to it is stored in the
-field. So you should avoid to use a list that lives in automatic variables
+field. So you should avoid using a list that lives in automatic variables
on the stack.
.TP 5
TYPE_INTEGER
Integer data, parsable to an integer by \fBatoi(3)\fR. Requires a third
-\fBint\fR argument controlling the precision, a fourth \fBlong\fR argument
+\fBint\fR argument controlling the precision, a fourth \fBlong\fR argument
constraining minimum value, and a fifth \fBlong\fR constraining maximum value.
-If the maximum value is less or equal 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.
+If the maximum value is less than or equal to the minimum value, the range is
+simply ignored. On return the field buffer is formatted according to the
+\fBprintf\fR format specification ".*ld", where the '*' is replaced by the
+precision argument.
For details of the precision handling see \fBprintf's\fR man-page.
.TP 5
TYPE_NUMERIC
Numeric data (may have a decimal-point part). Requires a third
\fBint\fR argument controlling the precision, a fourth \fBdouble\fR
-argument constraining minimum value, and a fifth \fBdouble\fR constraining
-maximum value. If your system supports locale's, the decimal point character
+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 or equal 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.
+If the maximum value is less than or equal to the minimum value, the range is
+simply ignored. On return the field buffer is formatted according to the
+\fBprintf\fR format specification ".*f", where the '*' is replaced by the
+precision argument.
For details of the precision handling see \fBprintf's\fR man-page.
.TP 5
TYPE_REGEXP
@@ -96,17 +113,17 @@ 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.
-
+.PP
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:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
diff --git a/contrib/ncurses/man/form_fieldtype.3x b/contrib/ncurses/man/form_fieldtype.3x
index 69a8e2082466..0d42faed6cc2 100644
--- a/contrib/ncurses/man/form_fieldtype.3x
+++ b/contrib/ncurses/man/form_fieldtype.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2000,2001 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2006 Free 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.9 2001/08/04 20:36:25 William.Setzer Exp $
+.\" $Id: form_fieldtype.3x,v 1.14 2006/11/04 17:12:00 tom Exp $
.TH form_fieldtype 3X ""
.SH NAME
\fBform_fieldtype\fR - define validation-field types
@@ -57,58 +57,80 @@ FIELDTYPE *link_fieldtype(FIELDTYPE *type1,
.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
-validity of an entered data string whenever the user attempt to leave a field.
+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
argument-block structure, about which more below.
-
+.PP
You also supply \fBnew_fieldtype\fR with \fIchar_check\fR,
a function to validate input characters as they are entered; it will be passed
the character to be checked and a pointer to an argument-block structure.
-
+.PP
The function \fBfree_fieldtype\fR frees the space allocated for a given
validation type.
-
-The function \fBset_fieldtype\fR associates three storage-management functions
-with a field type. The \fImak_arg\fR function is automatically applied to the
+.PP
+The function \fBset_fieldtype_arg\fR associates three storage-management functions
+with a field type.
+The \fImake_arg\fR function is automatically applied to the
list of arguments you give \fBset_field_type\fR when attaching validation
to a field; its job is to bundle these into an allocated argument-block
-object which can later be passed to validation predicated. The other two
-hook arguments should copy and free argument-block structures. They will
-be used by the forms-driver code. You must supply the \fImak_arg\fR function,
-the other two are optional, you may supply NULL for them. In this case it
-is assumed, that \fImak_arg\fR doesn't allocate memory but simply loads the
+object which can later be passed to validation predicated.
+The other two hook arguments should copy and free argument-block structures.
+They will be used by the forms-driver code.
+You must supply the \fImake_arg\fR function,
+the other two are optional, you may supply NULL for them.
+In this case it is assumed
+that \fImake_arg\fR does not allocate memory but simply loads the
argument into a single scalar value.
-
+.PP
+The function \fBlink_fieldtype\fR creates
+a new field type from the two given types.
+They are connected by an logical 'OR'.
+.PP
The form driver requests \fBREQ_NEXT_CHOICE\fR and \fBREQ_PREV_CHOICE\fR assume
that the possible values of a field form an ordered set, and provide the forms
-user with a way to move through the set. The \fBset_fieldtype_choice\fR
+user with a way to move through the set.
+The \fBset_fieldtype_choice\fR
function allows forms programmers to define successor and predecessor functions
-for the field type. These functions take the field pointer and an
+for the field type.
+These functions take the field pointer and an
argument-block structure as arguments.
.SH RETURN VALUE
The pointer-valued routines return NULL on error.
-
+They set errno according to their success:
+.TP 5
+.B E_OK
+The routine succeeded.
+.TP 5
+.B E_BAD_ARGUMENT
+Routine detected an incorrect or out-of-range argument.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred, e.g., malloc failure.
+.PP
The integer-valued routines return one of the following codes on
error:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
-.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_CONNECTED\fR
+.B E_CONNECTED
The field is already connected to a form.
+.TP 5
+.B E_CURRENT
+The field is the current field.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
.SH NOTES
The header file \fB<form.h>\fR automatically includes the header file
\fB<curses.h>\fR.
-
+.PP
All of the \fB(char *)\fR arguments of these functions should actually be
\fB(void *)\fR. The type has been left uncorrected for strict compatibility
with System V.
diff --git a/contrib/ncurses/man/form_hook.3x b/contrib/ncurses/man/form_hook.3x
index 19c1b9fbd7a0..82b62c3f0293 100644
--- a/contrib/ncurses/man/form_hook.3x
+++ b/contrib/ncurses/man/form_hook.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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.6 1999/03/20 22:37:15 Todd.Miller Exp $
+.\" $Id: form_hook.3x,v 1.8 2006/11/04 17:12:00 tom Exp $
.TH form_hook 3X ""
.SH NAME
\fBform_hook\fR - set hooks for automatic invocation by applications
@@ -53,21 +53,21 @@ void (*)(FORM *) form_term(const FORM *form);
.SH DESCRIPTION
These functions make it possible to set hook functions to be called at various
points in the automatic processing of input event codes by \fBform_driver\fR.
-
+.PP
The function \fBset_field_init\fR sets a hook to be called at form-post time
and each time the selected field changes (after the change). \fBfield_init\fR
returns the current field init hook, if any (\fBNULL\fR if there is no such
hook).
-
+.PP
The function \fBset_field_term\fR sets a hook to be called at form-unpost time
and each time the selected field changes (before the change). \fBfield_term\fR
returns the current field term hook, if any (\fBNULL\fR if there is no such
hook).
-
+.PP
The function \fBset_form_init\fR sets a hook to be called at form-post time and
just after a page change once it is posted. \fBform_init\fR returns the
current form init hook, if any (\fBNULL\fR if there is no such hook).
-
+.PP
The function \fBset_form_term\fR sets a hook to be called at form-unpost time
and just before a page change once it is posted. \fBform_init\fR
returns the current form term hook, if any (\fBNULL\fR if there is no such
@@ -76,10 +76,10 @@ hook).
Routines that return pointers return \fBNULL\fR on error. Other routines
return one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
diff --git a/contrib/ncurses/man/form_new.3x b/contrib/ncurses/man/form_new.3x
index 0f4c5015d11b..cac4f508b38b 100644
--- a/contrib/ncurses/man/form_new.3x
+++ b/contrib/ncurses/man/form_new.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_new.3x,v 1.5 1998/11/29 01:07:37 Rick.Ohnemus Exp $
+.\" $Id: form_new.3x,v 1.7 2006/11/04 17:12:00 tom Exp $
.TH form_new 3X ""
.SH NAME
\fBform_new\fR - create and destroy forms
@@ -41,24 +41,34 @@ int free_form(FORM *form);
.SH DESCRIPTION
The function \fBnew_form\fR creates a new form connected to a specified field
pointer array (which must be \fBNULL\fR-terminated).
-
+.PP
The function \fBfree_form\fR disconnects \fIform\fR from its field array
and frees the storage allocated for the form.
.SH RETURN VALUE
The function \fBnew_form\fR returns \fBNULL\fR on error.
-
-The function \fBfree_form\fR returns one of the following:
+It sets errno according to the function's success:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
+.B E_BAD_ARGUMENT
+Routine detected an incorrect or out-of-range argument.
+.TP 5
+.B E_CONNECTED
+The field is already connected to a form.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred, e.g., malloc failure.
+.PP
+The function \fBfree_form\fR returns one of the following:
+.TP 5
+.B E_OK
+The routine succeeded.
.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_POSTED\fR
+.B E_POSTED
The form has already been posted.
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
diff --git a/contrib/ncurses/man/form_new_page.3x b/contrib/ncurses/man/form_new_page.3x
index 432f624f5298..5b7f58d4a46a 100644
--- a/contrib/ncurses/man/form_new_page.3x
+++ b/contrib/ncurses/man/form_new_page.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2002,2006 Free 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_new_page.3x,v 1.6 2002/01/19 22:48:51 tom Exp $
+.\" $Id: form_new_page.3x,v 1.8 2006/11/04 17:12:00 tom Exp $
.TH form_new_page 3X ""
.SH NAME
\fBform_new_page\fR - form pagination functions
@@ -41,21 +41,21 @@ bool new_page(const FIELD *field);
.SH DESCRIPTION
The function \fBset_new_page\fR sets or resets a flag marking the given field
as the beginning of a new page on its form.
-
+.PP
The function \fBnew_page\fR is a predicate which tests if a given field marks
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:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.TP 5
-\fBE_CONNECTED\fR
+.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
diff --git a/contrib/ncurses/man/form_opts.3x b/contrib/ncurses/man/form_opts.3x
index 7921b3772563..4bf5b1e2c8d8 100644
--- a/contrib/ncurses/man/form_opts.3x
+++ b/contrib/ncurses/man/form_opts.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_opts.3x,v 1.6 1998/11/29 01:07:53 Rick.Ohnemus Exp $
+.\" $Id: form_opts.3x,v 1.8 2006/11/04 17:12:00 tom Exp $
.TH form_opts 3X ""
.SH NAME
\fBform_opts\fR - set and get form options
@@ -45,15 +45,15 @@ OPTIONS form_opts(const FORM *form);
.SH DESCRIPTION
The function \fBset_form_opts\fR sets all the given form's option bits (form
option bits may be logically-OR'ed together).
-
+.PP
The function \fBform_opts_on\fR turns on the given option bits, and leaves
others alone.
-
+.PP
The function \fBform_opts_off\fR turns off the given option bits, and leaves
others alone.
-
+.PP
The function \fBform_opts\fR returns the form's current option bits.
-
+.PP
The following options are defined (all are on by default):
.TP 5
O_NL_OVERLOAD
@@ -66,10 +66,10 @@ beginning of a field goes to the previous field.
.SH RETURN VALUE
Except for \fBform_opts\fR, each routine returns one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
diff --git a/contrib/ncurses/man/form_page.3x b/contrib/ncurses/man/form_page.3x
index 4b5d15aec18e..50ed54db4cc5 100644
--- a/contrib/ncurses/man/form_page.3x
+++ b/contrib/ncurses/man/form_page.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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.8 1998/11/29 01:08:02 Rick.Ohnemus Exp $
+.\" $Id: form_page.3x,v 1.10 2006/11/04 18:52:32 tom Exp $
.TH form_page 3X ""
.SH NAME
\fBform_page\fR - set and get form page number
@@ -59,23 +59,24 @@ 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:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
-.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_BAD_STATE\fR
+.B E_BAD_STATE
Routine was called from an initialization or termination function.
.TP 5
-\fBE_INVALID_FIELD\fR
+.B E_INVALID_FIELD
Contents of a field are not valid.
.TP 5
-\fBE_REQUEST_DENIED\fR
+.B E_REQUEST_DENIED
The form driver could not process the request.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).
+.
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
.SH NOTES
diff --git a/contrib/ncurses/man/form_post.3x b/contrib/ncurses/man/form_post.3x
index 56e86ab94692..6bf1607799c6 100644
--- a/contrib/ncurses/man/form_post.3x
+++ b/contrib/ncurses/man/form_post.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_post.3x,v 1.4 1998/11/29 01:08:10 Rick.Ohnemus Exp $
+.\" $Id: form_post.3x,v 1.7 2006/11/04 18:53:20 tom Exp $
.TH form_post 3X ""
.SH NAME
\fBform_post\fR - write or erase forms from associated subwindows
@@ -43,34 +43,35 @@ The function \fBpost_form\fR displays a form to its associated subwindow. To
trigger physical display of the subwindow, use \fBrefresh\fR or some equivalent
\fBcurses\fR routine (the implicit \fBdoupdate\fR triggered by an \fBcurses\fR
input request will do).
-
+.PP
The function \fBunpost_form\fR erases form from its associated subwindow.
.SH RETURN VALUE
These routines return one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
-.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_POSTED\fR
-The form has already been posted.
-.TP 5
-\fBE_BAD_STATE\fR
+.B E_BAD_STATE
Routine was called from an initialization or termination function.
.TP 5
-\fBE_NO_ROOM\fR
-Form is too large for its window.
-.TP 5
-\fBE_NOT_POSTED\fR
+.B E_NOT_POSTED
The form has not been posted.
.TP 5
-\fBE_NOT_CONNECTED\fR
+.B E_NOT_CONNECTED
No items are connected to the form.
+.TP 5
+.B E_NO_ROOM
+Form is too large for its window.
+.TP 5
+.B E_POSTED
+The form has already been posted.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).
+.
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
.SH NOTES
diff --git a/contrib/ncurses/man/form_requestname.3x b/contrib/ncurses/man/form_requestname.3x
index df1f701b382e..a172f857b1e3 100644
--- a/contrib/ncurses/man/form_requestname.3x
+++ b/contrib/ncurses/man/form_requestname.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_requestname.3x,v 1.6 1998/11/29 01:08:18 Rick.Ohnemus Exp $
+.\" $Id: form_requestname.3x,v 1.7 2006/11/04 17:57:49 tom Exp $
.TH form_requestname 3X ""
.SH NAME
\fBform_requestname\fR - handle printable form request names
@@ -49,6 +49,7 @@ with the given name and returns its request code. Otherwise E_NO_MATCH is return
to \fBE_BAD_ARGUMENT\fR.
.br
\fBform_request_by_name\fR returns \fBE_NO_MATCH\fR on error.
+It does not set errno.
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
.SH NOTES
diff --git a/contrib/ncurses/man/form_userptr.3x b/contrib/ncurses/man/form_userptr.3x
index 00e3d71aa40e..7be0bf860480 100644
--- a/contrib/ncurses/man/form_userptr.3x
+++ b/contrib/ncurses/man/form_userptr.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_userptr.3x,v 1.9 1998/11/29 01:08:39 Rick.Ohnemus Exp $
+.\" $Id: form_userptr.3x,v 1.11 2006/11/04 18:43:24 tom Exp $
.TH form_userptr 3X ""
.SH NAME
\fBform_userptr\fR - associate application data with a form item
@@ -43,14 +43,10 @@ Every form and every form item has a field that can be used to hold
application-specific data (that is, the form-driver code leaves it alone).
These functions get and set the form user pointer field.
.SH RETURN VALUE
-The function \fBform_userptr\fR returns \fBNULL\fR on error.
-The function \fBset_form_userptr\fR returns one of the following:
-.TP 5
-\fBE_OK\fR
-The routine succeeded.
-.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
+The function \fBform_userptr\fR returns a pointer (which may be \fBNULL\fR).
+It does not set errno.
+.PP
+The function \fBset_form_userptr\fR returns \fBE_OK\fP (success).
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
.SH NOTES
@@ -59,9 +55,9 @@ The header file \fB<form.h>\fR automatically includes the header file
.SH PORTABILITY
These routines emulate the System V forms library. They were not supported on
Version 7 or BSD versions.
-
-The user pointer should be a void pointer. We leave it as a char pointer for
-SVr4 compatibility.
+.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.
diff --git a/contrib/ncurses/man/form_win.3x b/contrib/ncurses/man/form_win.3x
index e56597028868..c8f64f2e04ad 100644
--- a/contrib/ncurses/man/form_win.3x
+++ b/contrib/ncurses/man/form_win.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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.8 1999/04/10 23:36:08 tom Exp $
+.\" $Id: form_win.3x,v 1.10 2006/11/04 17:12:00 tom Exp $
.TH form_win 3X ""
.SH NAME
\fBform_win\fR - make and break form window and subwindow associations
@@ -48,33 +48,33 @@ int scale_form(const FORM *form, int *rows, int *columns);
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
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
it were \fBstsdcr\fR. A form argument of \fBNULL\fR is treated as a request
to change the system default form window or subwindow.
-
+.PP
The function \fBscale_form\fR returns the minimum size required for the
subwindow of \fIform\fR.
.SH RETURN VALUE
Routines that return pointers return \fBNULL\fR on error. Routines that return
an integer return one of the following error codes:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_POSTED\fR
+.B E_POSTED
The form has already been posted.
.TP 5
-\fBE_NOT_CONNECTED\fR
+.B E_NOT_CONNECTED
No items are connected to the form.
.SH SEE ALSO
\fBcurses\fR(3X), \fBform\fR(3X).
diff --git a/contrib/ncurses/man/infocmp.1m b/contrib/ncurses/man/infocmp.1m
index 8ee2840c27da..a7feb4495766 100644
--- a/contrib/ncurses/man/infocmp.1m
+++ b/contrib/ncurses/man/infocmp.1m
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2000,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2004,2006 Free 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,40 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: infocmp.1m,v 1.29 2002/02/16 22:40:59 tom Exp $
+.\" $Id: infocmp.1m,v 1.43 2006/05/13 15:14:01 tom Exp $
.TH infocmp 1M ""
.ds n 5
.ds d @TERMINFO@
.SH NAME
\fBinfocmp\fR - compare or print out \fIterminfo\fR descriptions
.SH SYNOPSIS
-\fBinfocmp\fR [\fB-dceEGgnpqrILCuV1\fR] [\fB-v\fR \fIn\fR] [\fB-s d\fR| \fBi\fR| \fBl\fR| \fBc\fR]
+\fBinfocmp\fR [\fB-\
+1\
+C\
+E\
+F\
+G\
+I\
+L\
+T\
+U\
+V\
+c\
+d\
+e\
+g\
+i\
+l\
+n\
+p\
+q\
+r\
+t\
+u\
+x\
+\fR]
+.br
+ [\fB-v\fR \fIn\fR] [\fB-s d\fR| \fBi\fR| \fBl\fR| \fBc\fR] [\fB-R \fR\fBsubset\fR]
.br
[\fB-w\fR\ \fIwidth\fR] [\fB-A\fR\ \fIdirectory\fR] [\fB-B\fR\ \fIdirectory\fR]
.br
@@ -57,15 +83,15 @@ 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.
-
+.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.
-
+.PP
The \fB-c\fR option produces a list of each capability that is common between
two 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 neither
entry. 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
@@ -73,7 +99,7 @@ check to see if anything was left out of a description.
.SS Source Listing Options [-I] [-L] [-C] [-r]
The \fB-I\fR, \fB-L\fR, and \fB-C\fR options will produce a source listing for
each terminal named.
-
+.
.TS
center tab(/) ;
l l .
@@ -82,27 +108,27 @@ l l .
\fB-C\fR/use the \fBtermcap\fR names
\fB-r\fR/when using \fB-C\fR, put out all capabilities in \fBtermcap\fR form
.TE
-
+.PP
If no \fItermnames\fR are given, the environment variable \fBTERM\fR will be
used for the terminal name.
-
+.PP
The source produced by the \fB-C\fR option may be used directly as a
\fBtermcap\fR entry, but not all parameterized strings can be changed to
the \fBtermcap\fR format. \fBinfocmp\fR will attempt to convert most of the
parameterized information, and anything not converted will be plainly marked in
the output and commented out. These should be edited by hand.
-
+.PP
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.
-
+.PP
All \fBtermcap\fR variables no longer supported by \fBterminfo\fR, but which
are derivable from other \fBterminfo\fR variables, will be output. Not all
\fBterminfo\fR capabilities will be translated; only those variables which were
part of \fBtermcap\fR will normally be output. Specifying the \fB-r\fR option
will take off this restriction, allowing all capabilities to be output in
\fItermcap\fR form.
-
+.PP
Note that because padding is collected to the beginning of the capability, not
all capabilities are output. Mandatory padding is not supported. Because
\fBtermcap\fR strings are not as flexible, it is not always possible to convert
@@ -110,10 +136,10 @@ 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.
-
+.PP
Some common \fBterminfo\fR parameter sequences, their \fBtermcap\fR
equivalents, and some terminal types which commonly have such sequences, are:
-
+.
.TS
center tab(/) ;
l c l
@@ -138,27 +164,27 @@ 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 \fBinfocmp\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
first \fItermname\fR, but one of the other \fItermname\fR entries contains a
value for it. A capability's value gets printed if the value in the first
\fItermname\fR is not found in any of the other \fItermname\fR entries, or if
the first of the other \fItermname\fR entries that has this capability gives a
different value for the capability than that in the first \fItermname\fR.
-
+.PP
The order of the other \fItermname\fR entries is significant. Since the
terminfo compiler \fBtic\fR does a left-to-right scan of the capabilities,
specifying two \fBuse=\fR entries that contain differing entries for the same
capabilities will produce different results depending on the order that the
entries are given in. \fBinfocmp\fR will flag any such inconsistencies between
the other \fItermname\fR entries as they are found.
-
+.PP
Alternatively, specifying a capability \fIafter\fR a \fBuse=\fR entry that
contains that capability will cause the second specification to be ignored.
Using \fBinfocmp\fR to recreate a description can be a useful check to make
sure that everything was specified correctly in the original source
description.
-
+.PP
Another error that does not cause incorrect compiled files, but will slow down
the compilation time, is specifying extra \fBuse=\fR fields that are
superfluous. \fBinfocmp\fR will flag any other \fItermname use=\fR fields that
@@ -174,79 +200,17 @@ set \fBTERMINFO\fR for the other \fItermnames\fR. With this, it is possible to
compare descriptions for a terminal with the same name located in two different
databases. This is useful for comparing descriptions for the same terminal
created by different people.
-.SS Other Options [-s d|i|l|c] [-1FTVefip] [-Rsubset] [-v \fIn\fR] [-w \fIwidth\fR]
-The \fB-s\fR option sorts the fields within each type according to the argument
-below:
-.TP 5
-\fBd\fR
-leave fields in the order that they are stored in the \fIterminfo\fR database.
-.TP 5
-\fBi\fR
-sort by \fIterminfo\fR name.
-.TP 5
-\fBl\fR
-sort by the long C variable name.
-.TP 5
-\fBc\fR
-sort by the \fItermcap\fR name.
-
-If the \fB-s\fR option is not given, the fields printed out will be
-sorted alphabetically by the \fBterminfo\fR name within each type,
-except in the case of the \fB-C\fR or the \fB-L\fR options, which cause the
-sorting to be done by the \fBtermcap\fR name or the long C variable
-name, respectively.
+.SS Other Options
.TP 5
\fB-1\fR
causes the fields to be printed out one to a line. Otherwise,
the fields will be printed several to a line to a maximum width
of 60 characters.
-.TP 5
-\fB-F\fR
-compare terminfo files. This assumes that two following arguments are
-filenames. The files are searched for pairwise matches between
-entries, with two entries considered to match if any of their names do.
-The report printed to standard output lists entries with no matches in
-the other file, and entries with more than one match. For entries
-with exactly one match it includes a difference report. Normally,
-to reduce the volume of the report, use references are
-not resolved before looking for differences, but resolution can be forced
-by also specifying \fB-r\fR.
-.TP
-\fB-G\fR
-Display constant literals in decimal form
-rather than their character equivalents.
.TP
\fB-a\fR
tells \fBinfocmp\fP to retain commented-out capabilities rather than discarding
them. Capabilities are commented by prefixing them with a period.
.TP 5
-\fB-q\fR
-Make the comparison listing shorter by omitting subheadings, and using
-"-" for absent capabilities, "@" for canceled rather than "NULL".
-.TP 5
-\fB-R\fR\fIsubset\fR
-Restrict output to a given subset. This option is for use with archaic
-versions of terminfo like those on SVr1, Ultrix, or HP/UX that do not support
-the full set of SVR4/XSI Curses terminfo; and variants such as AIX
-that have their own extensions incompatible with SVr4/XSI. 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
-with termcap equivalents recognized by 4.4BSD.
-.TP 5
-\fB-T\fR
-eliminates size-restrictions on the generated text.
-This is mainly useful for testing and analysis, since the compiled
-descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
-.TP 5
-\fB-V\fR
-reports the version of ncurses which was used in this program, and exits.
-.TP 5
-\fB-e\fR
-Dump the capabilities of the given terminal as a C initializer for a
-TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fR).
-This option is useful for preparing versions of the curses library hardwired
-for a given terminal type.
-.TP 5
\fB-E\fR
Dump the capabilities of the given terminal as tables, needed in
the C initializer for a
@@ -256,14 +220,35 @@ for a given terminal type.
The tables are all declared static, and are named according to the type
and the name of the corresponding terminal entry.
.sp
-Before ncurses 5.0, the split between the \fB\-e\fP and \fB\-E\fP
+Before ncurses 5.0, the split between the \fB-e\fP and \fB-E\fP
options was not needed; but support for extended names required making
the arrays of terminal capabilities separate from the TERMTYPE structure.
-.TP
+.TP 5
+\fB-e\fR
+Dump the capabilities of the given terminal as a C initializer for a
+TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fR).
+This option is useful for preparing versions of the curses library hardwired
+for a given terminal type.
+.TP 5
+\fB-F\fR
+compare terminfo files. This assumes that two following arguments are
+filenames. The files are searched for pairwise matches between
+entries, with two entries considered to match if any of their names do.
+The report printed to standard output lists entries with no matches in
+the other file, and entries with more than one match. For entries
+with exactly one match it includes a difference report. Normally,
+to reduce the volume of the report, use references are
+not resolved before looking for differences, but resolution can be forced
+by also specifying \fB-r\fR.
+.TP 5
\fB-f\fR
Display complex terminfo strings which contain if/then/else/endif expressions
indented for readability.
-.TP
+.TP 5
+\fB-G\fR
+Display constant literals in decimal form
+rather than their character equivalents.
+.TP 5
\fB-g\fR
Display constant character literals in quoted form
rather than their decimal equivalents.
@@ -279,7 +264,7 @@ 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. Here is a list of the DEC/ANSI
special sequences recognized:
-
+i.
.TS
center tab(/) ;
l l
@@ -291,18 +276,26 @@ SC/save cursor
RC/restore cursor
LL/home-down
RSR/reset scroll region
-
+=
+DECSTR/soft reset (VT320)
+S7C1T/7-bit controls (VT220)
+=
ISO DEC G0/enable DEC graphics for G0
ISO UK G0/enable UK chars for G0
ISO US G0/enable US chars for G0
ISO DEC G1/enable DEC graphics for G1
ISO UK G1/enable UK chars for G1
ISO US G1/enable US chars for G1
-
+=
DECPAM/application keypad mode
DECPNM/normal keypad mode
DECANSI/enter ANSI mode
-
+=
+ECMA[+-]AM/keyboard action mode
+ECMA[+-]IRM/insert replace mode
+ECMA[+-]SRM/send receive mode
+ECMA[+-]LNM/linefeed mode
+=
DEC[+-]CKM/application cursor keys
DEC[+-]ANM/set VT52 mode
DEC[+-]COLM/132-column mode
@@ -316,18 +309,83 @@ 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
An SGR0 designates an empty highlight sequence (equivalent to {SGR:NORMAL}).
.TP 5
+\fB-l\fR
+Set output format to terminfo.
+.TP 5
\fB-p\fR
Ignore padding specifications when comparing strings.
.TP 5
+\fB-q\fR
+Make the comparison listing shorter by omitting subheadings, and using
+"-" for absent capabilities, "@" for canceled rather than "NULL".
+.TP 5
+\fB-R\fR\fIsubset\fR
+Restrict output to a given subset. This option is for use with archaic
+versions of terminfo like those on SVr1, Ultrix, or HP/UX that do not support
+the full set of SVR4/XSI Curses terminfo; and variants such as AIX
+that have their own extensions incompatible with SVr4/XSI. 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
+with termcap equivalents recognized by 4.4BSD.
+.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
+below:
+.br
+.RS 5
+.TP 5
+\fBd\fR
+leave fields in the order that they are stored in the \fIterminfo\fR database.
+.TP 5
+\fBi\fR
+sort by \fIterminfo\fR name.
+.TP 5
+\fBl\fR
+sort by the long C variable name.
+.TP 5
+\fBc\fR
+sort by the \fItermcap\fR name.
+.RE
+.IP
+If the \fB-s\fR option is not given, the fields printed out will be
+sorted alphabetically by the \fBterminfo\fR name within each type,
+except in the case of the \fB-C\fR or the \fB-L\fR options, which cause the
+sorting to be done by the \fBtermcap\fR name or the long C variable
+name, respectively.
+.TP 5
+\fB-T\fR
+eliminates size-restrictions on the generated text.
+This is mainly useful for testing and analysis, since the compiled
+descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
+.TP
+\fB-t\fR
+tells \fBtic\fP to discard commented-out capabilities.
+Normally when translating from terminfo to termcap,
+untranslatable capabilities are commented-out.
+.TP 5
+\fB-U\fR
+tells \fBinfocmp\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 \fBinfocmp\fP makes to fill in missing
+data.
+.TP 5
+\fB-V\fR
+reports the version of ncurses which was used in this program, and exits.
+.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.
.TP 5
\fB-w\fR \fIwidth\fR
changes the output to \fIwidth\fR characters.
+.TP
+\fB-x\fR
+print information for user-defined capabilities.
+These are extensions to the terminfo repertoire which can be loaded
+using the \fB-x\fR option of \fBtic\fP.
.SH FILES
.TP 20
\*d
@@ -345,23 +403,32 @@ The
\fB-f\fR,
\fB-g\fR,
\fB-i\fR,
-\fB-p\fR, and
-\fB-q\fR
+\fB-l\fR,
+\fB-p\fR,
+\fB-q\fR and
+\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.
Actual BSD curses versions will have a more restricted set. To see only the
-4.4BSD set, use -r -RBSD.
+4.4BSD set, use \fB-r\fR \fB-RBSD\fR.
.SH BUGS
-The -F option of \fBinfocmp\fR(1M) should be a \fBtoe\fR(1M) mode.
+The \fB-F\fR option of \fBinfocmp\fR(1M) should be a \fBtoe\fR(1M) mode.
.SH SEE ALSO
-\fBinfocmp\fR(1M), \fBcaptoinfo\fR(1M), \fBinfotocap\fR(1M),
-\fBtic\fR(1M), \fBtoe\fR(1M),
-\fBcurses\fR(3X), \fBterminfo\fR(\*n).
+\fB@CAPTOINFO@\fR(1M),
+\fB@INFOTOCAP@\fR(1M),
+\fB@TIC@\fR(1M),
+\fB@TOE@\fR(1M),
+\fBcurses\fR(3X),
+\fBterminfo\fR(\*n).
+.PP
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.SH AUTHOR
Eric S. Raymond <esr@snark.thyrsus.com>
and
-Thomas E. Dickey <dickey@herndon4.his.com>
+.br
+Thomas E. Dickey <dickey@invisible-island.net>
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/infotocap.1m b/contrib/ncurses/man/infotocap.1m
index ef8735b7be54..1d20ef081e7f 100644
--- a/contrib/ncurses/man/infotocap.1m
+++ b/contrib/ncurses/man/infotocap.1m
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1999,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1999-2004,2006 Free 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: infotocap.1m,v 1.3 2000/08/13 01:56:03 tom Exp $
+.\" $Id: infotocap.1m,v 1.6 2006/05/13 15:35:45 tom Exp $
.TH infotocap 1M ""
.ds n 5
.ds d @TERMINFO@
@@ -66,6 +66,9 @@ You can use other \fItic\fR options such as \fB-f\fR and \fB-x\fR.
\fBtic\fR(1M),
\fBinfocmp\fR(1M),
\fBterminfo\fR(\*n)
+.PP
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/key_defined.3x b/contrib/ncurses/man/key_defined.3x
new file mode 100644
index 000000000000..d7413da6fe35
--- /dev/null
+++ b/contrib/ncurses/man/key_defined.3x
@@ -0,0 +1,60 @@
+.\"***************************************************************************
+.\" Copyright (c) 2003-2004,2006 Free 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 2003
+.\"
+.\" $Id: key_defined.3x,v 1.4 2006/02/25 21:50:01 tom Exp $
+.TH key_defined 3X ""
+.SH NAME
+\fBkey_defined\fP \- check if a keycode is defined
+.SH SYNOPSIS
+\fB#include <curses.h>\fP
+.sp
+\fBint key_defined(const char *definition);\fP
+.SH DESCRIPTION
+This is an extension to the curses library.
+It permits an application to determine if a string is currently bound
+to any keycode.
+.SH RETURN VALUE
+If the string is bound to a keycode, its value (greater than zero) is returned.
+If no keycode is bound, zero is returned.
+If the string conflicts with longer strings which are bound to keys, -1 is returned.
+.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
+\fBdefine_key\fR(3X).
+.SH AUTHOR
+Thomas Dickey.
+.\"#
+.\"# The following sets edit modes for GNU EMACS
+.\"# Local Variables:
+.\"# mode:nroff
+.\"# fill-column:79
+.\"# End:
diff --git a/contrib/ncurses/man/keybound.3x b/contrib/ncurses/man/keybound.3x
index 79c480cfd386..93e17945a31a 100644
--- a/contrib/ncurses/man/keybound.3x
+++ b/contrib/ncurses/man/keybound.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1999,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1999-2003,2006 Free 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,24 +26,27 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" Author: Thomas E. Dickey <dickey@clark.net> 1999
+.\" Author: Thomas E. Dickey 1999
.\"
-.\" $Id: keybound.3x,v 1.3 2002/02/16 22:30:36 tom Exp $
+.\" $Id: keybound.3x,v 1.6 2006/02/25 21:47:06 tom Exp $
.TH keyok 3X ""
.SH NAME
\fBkeybound\fP \- return definition of keycode
.SH SYNOPSIS
\fB#include <curses.h>\fP
-
+.sp
\fBchar * keybound(int keycode, int count);\fP
.SH DESCRIPTION
This is an extension to the curses library.
It permits an application to determine the string which is defined
in the terminfo for specific keycodes.
.SH RETURN VALUE
-The keycode must be greater than zero, else NULL is returned.
+The \fIkeycode\fP parameter must be greater than zero, else NULL is returned.
If it does not correspond to a defined key, then NULL is returned.
-Otherwise, the function returns a string, which must be freed by the caller.
+The \fIcount\fP parameter is used to allow the application to iterate
+through multiple definitions, counting from zero.
+When successful,
+the function returns a string which must be freed by the caller.
.SH PORTABILITY
These routines are specific to ncurses. They were not supported on
Version 7, BSD or System V implementations. It is recommended that
diff --git a/contrib/ncurses/man/keyok.3x b/contrib/ncurses/man/keyok.3x
index e3f2287abb13..08c2a27778ea 100644
--- a/contrib/ncurses/man/keyok.3x
+++ b/contrib/ncurses/man/keyok.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2006 Free 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,15 +26,15 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" Author: Thomas E. Dickey <dickey@clark.net> 1997
+.\" Author: Thomas E. Dickey 1997
.\"
-.\" $Id: keyok.3x,v 1.7 2002/02/16 22:40:59 tom Exp $
+.\" $Id: keyok.3x,v 1.9 2006/02/25 21:47:06 tom Exp $
.TH keyok 3X ""
.SH NAME
\fBkeyok\fP \- enable or disable a keycode
.SH SYNOPSIS
\fB#include <curses.h>\fP
-
+.sp
\fBint keyok(int keycode, bool enable);\fP
.SH DESCRIPTION
This is an extension to the curses library.
diff --git a/contrib/ncurses/man/legacy_coding.3x b/contrib/ncurses/man/legacy_coding.3x
new file mode 100644
index 000000000000..b8b0561072a6
--- /dev/null
+++ b/contrib/ncurses/man/legacy_coding.3x
@@ -0,0 +1,82 @@
+.\"***************************************************************************
+.\" Copyright (c) 2005,2006 Free 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: legacy_coding.3x,v 1.2 2006/02/25 21:50:01 tom Exp $
+.TH legacy_coding 3X ""
+.SH NAME
+\fBuse_legacy_coding\fR \- use terminal's default colors
+.SH SYNOPSIS
+\fB#include <curses.h>\fP
+.sp
+\fBint use_legacy_coding(int level);\fP
+.SH DESCRIPTION
+The
+.I use_legacy_coding()
+function is an extension to the curses library.
+It allows the caller to change the result of \fBunctrl\fP,
+and suppress related checks within the library that would normally
+cause nonprinting characters to be rendered in visible form.
+This affects only 8-bit characters.
+.PP
+The \fIlevel\fP parameter controls the result:
+.RS
+.TP 5
+0
+the library functions normally,
+rendering nonprinting characters as described in \fBunctrl\fP(3X).
+.TP
+1
+the library ignores \fBisprintf\fP for codes in the range 160-255.
+.TP
+2
+the library ignores \fBisprintf\fP for codes in the range 128-255.
+It also modifies the output of \fBunctrl\fP, showing codes in the
+range 128-159 as is.
+.RE
+.SH RETURN VALUE
+If the screen has not been initialized,
+or the \fIlevel\fP parameter is out of range,
+the function returns \fBERR\fP.
+Otherwise, it returns the previous level: \fB0\fP, \fB1\fP or \fB2\fP.
+.SH PORTABILITY
+This routine is specific to ncurses.
+It was not supported on Version 7, BSD or System V implementations.
+It is recommended that any code depending on ncurses extensions
+be conditioned using NCURSES_VERSION.
+.SH SEE ALSO
+\fBunctrl\fR.
+.SH AUTHOR
+Thomas Dickey (to support lynx's font-switching feature).
+.\"#
+.\"# The following sets edit modes for GNU EMACS
+.\"# Local Variables:
+.\"# mode:nroff
+.\"# fill-column:79
+.\"# End:
diff --git a/contrib/ncurses/man/make_sed.sh b/contrib/ncurses/man/make_sed.sh
index c6c37c25b0d5..f2afac93ebc8 100755
--- a/contrib/ncurses/man/make_sed.sh
+++ b/contrib/ncurses/man/make_sed.sh
@@ -1,7 +1,7 @@
#!/bin/sh
-# $Id: make_sed.sh,v 1.5 1998/02/11 12:13:48 tom Exp $
+# $Id: make_sed.sh,v 1.9 2005/07/16 18:15:31 tom Exp $
##############################################################################
-# Copyright (c) 1998 Free Software Foundation, Inc. #
+# Copyright (c) 1998-2003,2005 Free Software Foundation, Inc. #
# #
# Permission is hereby granted, free of charge, to any person obtaining a #
# copy of this software and associated documentation files (the "Software"), #
@@ -28,7 +28,7 @@
# authorization. #
##############################################################################
#
-# Author: Thomas E. Dickey <dickey@clark.net> 1997
+# Author: Thomas E. Dickey 1997-2005
#
# Construct a sed-script to perform renaming within man-pages. Originally
# written in much simpler form, this one accounts for the common cases of
@@ -47,7 +47,7 @@ RESULT=result$$
rm -f $UPPER $SCRIPT $RESULT
trap "rm -f $COL.* $INPUT $UPPER $SCRIPT $RESULT" 0 1 2 5 15
fgrep -v \# $1 | \
-sed -e 's/[ ]\+/ /g' >$INPUT
+sed -e 's/[ ][ ]*/ /g' >$INPUT
for F in 1 2 3 4
do
@@ -63,7 +63,7 @@ paste $COL.* | \
sed -e 's/^/s\/\\</' \
-e 's/$/\//' >$UPPER
-# Do the TH lines
+echo "# Do the TH lines" >>$RESULT
sed -e 's/\//\/TH /' \
-e 's/ / /' \
-e 's/ / ""\/TH /' \
@@ -71,7 +71,7 @@ sed -e 's/\//\/TH /' \
-e 's/\/$/ ""\//' \
$UPPER >>$RESULT
-# Do the embedded references
+echo "# Do the embedded references" >>$RESULT
sed -e 's/</<fB/' \
-e 's/ /\\\\fR(/' \
-e 's/ /)\/fB/' \
@@ -79,5 +79,11 @@ sed -e 's/</<fB/' \
-e 's/\/$/)\//' \
$UPPER >>$RESULT
+echo "# Do the \fBxxx\fR references in the .NAME section" >>$RESULT
+sed -e 's/\\</^\\\\fB/' \
+ -e 's/ [^ ]* /\\\\f[RP] -\/\\\\fB/' \
+ -e 's/ .*$/\\\\fR -\//' \
+ $UPPER >>$RESULT
+
# Finally, send the result to standard output
cat $RESULT
diff --git a/contrib/ncurses/man/man_db.renames b/contrib/ncurses/man/man_db.renames
index 7aaf1de28610..8e968ac47f74 100644
--- a/contrib/ncurses/man/man_db.renames
+++ b/contrib/ncurses/man/man_db.renames
@@ -1,4 +1,31 @@
-# $Id: man_db.renames,v 0.31 2002/04/13 21:49:08 tom Exp $
+##############################################################################
+# Copyright (c) 1998-2005,2006 Free Software Foundation, Inc. #
+# #
+# Permission is hereby granted, free of charge, to any person obtaining a #
+# copy of this software and associated documentation files (the "Software"), #
+# to deal in the Software without restriction, including without limitation #
+# the rights to use, copy, modify, merge, publish, distribute, distribute #
+# with modifications, sublicense, and/or sell copies of the Software, and to #
+# permit persons to whom the Software is furnished to do so, subject to the #
+# following conditions: #
+# #
+# The above copyright notice and this permission notice shall be included in #
+# all copies or substantial portions of the Software. #
+# #
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR #
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, #
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL #
+# THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER #
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING #
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER #
+# DEALINGS IN THE SOFTWARE. #
+# #
+# Except as contained in this notice, the name(s) of the above copyright #
+# holders shall not be used in advertising or otherwise to promote the sale, #
+# use or other dealings in this Software without prior written #
+# authorization. #
+##############################################################################
+# $Id: man_db.renames,v 0.36 2006/05/13 23:47:25 tom Exp $
# Manual-page renamings for the man_db program
#
# Files:
@@ -89,6 +116,8 @@ infocmp.1m infocmp.1
infotocap.1m infotocap.1
keybound.3x keybound.3ncurses
keyok.3x keyok.3ncurses
+key_defined.3x key_defined.3ncurses
+legacy_coding.3x legacy_coding.3ncurses
menu.3x menu.3menu
menu_attributes.3x attributes.3menu
menu_cursor.3x cursor.3menu
@@ -136,3 +165,6 @@ can_change_color.3x can_change_color.3ncurses
curs_attr_get.3x attr_get.3ncurses
dup_field.3x dup_field.3ncurses
init_pair.3x init_pair.3ncurses
+#
+# Other:
+tack.1m tack.1
diff --git a/contrib/ncurses/man/manlinks.sed b/contrib/ncurses/man/manlinks.sed
index e175148aab9a..4da7790dfd97 100644
--- a/contrib/ncurses/man/manlinks.sed
+++ b/contrib/ncurses/man/manlinks.sed
@@ -1,6 +1,6 @@
-# $Id: manlinks.sed,v 1.9 2000/09/30 23:32:24 tom Exp $
+# $Id: manlinks.sed,v 1.12 2003/12/20 13:17:56 tom Exp $
##############################################################################
-# Copyright (c) 2000 Free Software Foundation, Inc. #
+# Copyright (c) 2000-2002,2003 Free 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"), #
@@ -29,40 +29,73 @@
# Given a manpage (nroff) as input, writes a list of the names that are
# listed in the "NAME" section, i.e., the names that we would like to use
# as aliases for the manpage -T.Dickey
+#
+# eliminate formatting controls that get in the way
/^'\\"/d
/\.\\"/d
/^\.br/d
/^\.sp/d
+s/^\.IX//
s/\\f.//g
s/[:,]/ /g
+#
+# eliminate unnecessary whitespace, convert multiple blanks to single space
s/^[ ][ ]*//
s/[ ][ ]*$//
s/[ ][ ]*/ /g
+#
+# convert ".SH" into a more manageable form
s/\.SH[ ][ ]*/.SH_(/
#
+# in ".SH NAME"
+# change "\-" to "-", eliminate text after "-", and split the remaining lines
+# at each space, making a list of names:
/^\.SH_(NAME/,/^\.SH_(SYNOPSIS/{
s/\\-.*/ -/
/ -/{
- s/ -.*//
- s/ /\
+s/ -.*//
+s/ /\
/g
}
/^-/{
- d
+d
}
s/ /\
/g
}
+#
+# in ".SH SYNOPSIS"
+# remove any line that does not contain a '(', since we only want functions.
+# then strip off return-type of each function.
+# finally, remove the parameter list, which begins with a '('.
/^\.SH_(SYNOPSIS/,/^\.SH_(DESCRIPTION/{
- /^#/d
- /^[^(]*$/d
- s/^\([^ (]* [^ (]* [*]*\)//g
- s/^\([^ (]* [*]*\)//g
- s/\.SH_(/.SH_/
- s/(.*//
- s/\.SH_/.SH_(/
+/^[^(]*$/d
+# reduce
+# .B "int add_wch( const cchar_t *\fIwch\fB );"
+# to
+# add_wch( const cchar_t *\fIwch\fB );"
+s/^\([^ (]* [^ (]* [*]*\)//g
+s/^\([^ (]* [*]*\)//g
+# trim blanks in case we have
+# void (*) (FORM *) field_init(const FORM *form);
+s/) (/)(/g
+# reduce stuff like
+# void (*)(FORM *) field_init(const FORM *form);
+# to
+# field_init(const FORM *form);
+s/^\(([^)]*)\)\(([^)]*)\)*[ ]*//g
+# rename marker temporarily
+s/\.SH_(/.SH_/
+# kill lines with ");", and trim off beginning of argument list.
+s/[()].*//
+# rename marker back
+s/\.SH_/.SH_(/
}
+#
+# delete ".SH DESCRIPTION" and following lines
/^\.SH_(DESCRIPTION/,${
- d
+d
}
+#
+# delete any remaining directives
/^\./d
diff --git a/contrib/ncurses/man/menu.3x b/contrib/ncurses/man/menu.3x
index e81913c43cb9..17d6fc120cba 100644
--- a/contrib/ncurses/man/menu.3x
+++ b/contrib/ncurses/man/menu.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2000,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2002,2006 Free 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.3x,v 1.15 2002/01/19 22:48:58 tom Exp $
+.\" $Id: menu.3x,v 1.19 2006/11/04 18:38:29 tom Exp $
.TH menu 3X ""
.SH NAME
\fBmenu\fR - curses extension for programming menus
@@ -39,25 +39,25 @@ The \fBmenu\fR library provides terminal-independent facilities for composing
menu systems on character-cell terminals. The library includes: item routines,
which create and modify menu items; and menu routines, which group items into
menus, display menus on the screen, and handle interaction with the user.
-
+.PP
The \fBmenu\fR library uses the \fBcurses\fR libraries, and a curses
initialization routine such as \fBinitscr\fR must be called before using any of
these functions. To use the \fBmenu\fR library, link with the options
\fB-lmenu -lcurses\fR.
-
+.
.SS Current Default Values for Item Attributes
-
+.
The \fBmenu\fR library maintains a default value for item attributes. You can
get or set this default by calling the appropriate \fBget_\fR or \fBset_\fR
routine with a \fBNULL\fR item pointer. Changing this default with a
\fBset_\fR function affects future item creations, but does not change the
rendering of items already created.
-
+.
.SS Routine Name Index
-
+.
The following table lists each \fBmenu\fR routine and the name of
the manual page on which it is described.
-
+.
.TS
l l .
\fBcurses\fR Routine Name Manual Page Name
@@ -131,57 +131,60 @@ unpost_menu \fBmenu_post\fR(3X)
Routines that return pointers return \fBNULL\fR on error. Routines that return
an integer return one of the following error codes:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
-.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_POSTED\fR
-The menu is already posted.
-.TP 5
-\fBE_BAD_STATE\fR
+.B E_BAD_STATE
Routine was called from an initialization or termination function.
.TP 5
-\fBE_NO_ROOM\fR
-Menu is too large for its window.
+.B E_NO_MATCH
+Character failed to match.
.TP 5
-\fBE_NOT_POSTED\fR
-The menu has not been posted.
+.B E_NO_ROOM
+Menu is too large for its window.
.TP 5
-\fBE_UNKNOWN_COMMAND\fR
-The menu driver code saw an unknown request code.
+.B E_NOT_CONNECTED
+No items are connected to the menu.
.TP 5
-\fBE_NO_MATCH\fR
-Character failed to match.
+.B E_NOT_POSTED
+The menu has not been posted.
.TP 5
-\fBE_NOT_SELECTABLE\fR
+.B E_NOT_SELECTABLE
The designated item cannot be selected.
.TP 5
-\fBE_NOT_CONNECTED\fR
-No items are connected to the menu.
+.B E_POSTED
+The menu is already posted.
.TP 5
-\fBE_REQUEST_DENIED\fR
+.B E_REQUEST_DENIED
The menu driver could not process the request.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).
+.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
-give you a link error using GNU \fBld\fR(1) and many other linkers).
+usually give a link-error).
.SH PORTABILITY
These routines emulate the System V menu library. They were not supported on
Version 7 or BSD versions.
.SH AUTHORS
Juergen Pfeifer. Manual pages and adaptation for ncurses by Eric
S. Raymond.
+.SH SEE ALSO
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/menu_attributes.3x b/contrib/ncurses/man/menu_attributes.3x
index 99a2ac2bc101..d96ea234fd84 100644
--- a/contrib/ncurses/man/menu_attributes.3x
+++ b/contrib/ncurses/man/menu_attributes.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2002,2006 Free 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_attributes.3x,v 1.7 2002/01/19 22:49:06 tom Exp $
+.\" $Id: menu_attributes.3x,v 1.9 2006/11/04 17:12:00 tom Exp $
.TH menu_attributes 3X ""
.SH NAME
\fBmenu_attributes\fR - color and attribute control for menus
@@ -55,30 +55,30 @@ The function \fBset_menu_fore\fR sets the foreground attribute of
\fImenu\fR. This is the highlight used for selected menu items.
\fBmenu_fore\fR returns the foreground attribute. The default
is \fBA_STANDOUT\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.
-
+.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.
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.
.SH RETURN VALUE
These routines return one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.TP 5
-\fBE_BAD_ARGUMENT\fR
+.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
diff --git a/contrib/ncurses/man/menu_cursor.3x b/contrib/ncurses/man/menu_cursor.3x
index 2cc58507de66..4ade0bf96269 100644
--- a/contrib/ncurses/man/menu_cursor.3x
+++ b/contrib/ncurses/man/menu_cursor.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_cursor.3x,v 1.5 1998/11/29 01:09:30 Rick.Ohnemus Exp $
+.\" $Id: menu_cursor.3x,v 1.6 2006/11/04 17:13:57 tom Exp $
.TH menu_cursor 3X ""
.SH NAME
\fBmenu_cursor\fR - position a menu's cursor
@@ -43,16 +43,16 @@ routines have been called to do screen-painting in response to a menu select.
.SH RETURN VALUE
This routine returns one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_NOT_POSTED\fR
+.B E_NOT_POSTED
The menu has not been posted.
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
diff --git a/contrib/ncurses/man/menu_driver.3x b/contrib/ncurses/man/menu_driver.3x
index 0e6f9e02f38f..a256141ae7db 100644
--- a/contrib/ncurses/man/menu_driver.3x
+++ b/contrib/ncurses/man/menu_driver.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2006 Free 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: menu_driver.3x,v 1.10 2002/02/16 22:40:59 tom Exp $
+.\" $Id: menu_driver.3x,v 1.12 2006/11/04 17:13:50 tom Exp $
.TH menu_driver 3X ""
.SH NAME
\fBmenu_driver\fR - command-processing loop of the menu system
@@ -115,10 +115,10 @@ is positioned to that item. If you double-click at an item a REQ_TOGGLE_ITEM
is generated and \fBE_UNKNOWN_COMMAND\fR is returned. This return value makes
sense, because a double click usually means that an item-specific action should
be returned. It's exactly the purpose of this return value to signal that an
-application specific command should be executed. If a translation
+application specific command should be executed. If a translation
into a request was done, \fBmenu_driver\fR returns the result of this request.
If you clicked outside the user window or the mouse event couldn't be translated
-into a menu request an \fBE_REQUEST_DENIED\fR is returned.
+into a menu request an \fBE_REQUEST_DENIED\fR is returned.
.PP
If the second argument is neither printable ASCII nor one of the above
pre-defined menu requests or KEY_MOUSE, the drive assumes it is an application-specific
@@ -128,28 +128,28 @@ pre-defined requests.
.SH RETURN VALUE
\fBmenu_driver\fR return one of the following error codes:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_BAD_STATE\fR
+.B E_BAD_STATE
Routine was called from an initialization or termination function.
.TP 5
-\fBE_NOT_POSTED\fR
+.B E_NOT_POSTED
The menu has not been posted.
.TP 5
-\fBE_UNKNOWN_COMMAND\fR
+.B E_UNKNOWN_COMMAND
The menu driver code saw an unknown request code.
.TP 5
-\fBE_NO_MATCH\fR
+.B E_NO_MATCH
Character failed to match.
.TP 5
-\fBE_REQUEST_DENIED\fR
+.B E_REQUEST_DENIED
The menu driver could not process the request.
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
diff --git a/contrib/ncurses/man/menu_format.3x b/contrib/ncurses/man/menu_format.3x
index 7dde28face88..f4d456f6f960 100644
--- a/contrib/ncurses/man/menu_format.3x
+++ b/contrib/ncurses/man/menu_format.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2001 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2001,2006 Free 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_format.3x,v 1.8 2001/08/04 20:36:19 William.Setzer Exp $
+.\" $Id: menu_format.3x,v 1.10 2006/11/04 17:12:00 tom Exp $
.TH menu_format 3X ""
.SH NAME
\fBmenu_format\fR - set and get menu sizes
@@ -43,28 +43,31 @@ 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.
-
+.PP
The default format is 16 rows, 1 column. Calling \fBset_menu_format\fR with a
null menu pointer will change this default. A zero row or column argument to
\fBset_menu_format\fR is interpreted as a request not to change the current
value.
-
+.PP
The function \fBmenu_format\fR returns the maximum-size constraints for the
given menu into the storage addressed by \fBrows\fR and \fBcols\fR.
.SH RETURN VALUE
These routines returns one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_POSTED\fR
+.B E_POSTED
The menu is already posted.
+.TP 5
+.B E_NOT_CONNECTED
+No items are connected to the menu.
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
.SH NOTES
diff --git a/contrib/ncurses/man/menu_hook.3x b/contrib/ncurses/man/menu_hook.3x
index 531528a60783..840552315675 100644
--- a/contrib/ncurses/man/menu_hook.3x
+++ b/contrib/ncurses/man/menu_hook.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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.6 1998/11/29 01:09:47 Rick.Ohnemus Exp $
+.\" $Id: menu_hook.3x,v 1.8 2006/11/04 17:12:00 tom Exp $
.TH menu_hook 3X ""
.SH NAME
\fBmenu_hook\fR - set hooks for automatic invocation by applications
@@ -53,22 +53,22 @@ void (*)(MENU *) menu_term(const MENU *menu);
.SH DESCRIPTION
These functions make it possible to set hook functions to be called at various
points in the automatic processing of input event codes by \fBmenu_driver\fR.
-
+.PP
The function \fBset_item_init\fR sets a hook to be called at menu-post time and
each time the selected item changes (after the change). \fBitem_init\fR
returns the current item init hook, if any (\fBNULL\fR if there is no such
hook).
-
+.PP
The function \fBset_item_term\fR sets a hook to be called at menu-unpost time
and each time the selected item changes (before the change). \fBitem_term\fR
returns the current item term hook, if any (\fBNULL\fR if there is no such
hook).
-
+.PP
The function \fBset_menu_init\fR sets a hook to be called at menu-post time and
just after the top row on the menu changes once it is posted. \fBmenu_init\fR
returns the current menu init hook, if any (\fBNULL\fR if there is no such
hook).
-
+.PP
The function \fBset_menu_term\fR sets a hook to be called at menu-unpost time
and just before the top row on the menu changes once it is posted.
\fBmenu_term\fR returns the current menu term hook, if any (\fBNULL\fR if there
@@ -77,10 +77,10 @@ is no such hook).
Routines that return pointers return \fBNULL\fR on error. Other routines
return one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
diff --git a/contrib/ncurses/man/menu_items.3x b/contrib/ncurses/man/menu_items.3x
index 7ec7db5604ba..091534385368 100644
--- a/contrib/ncurses/man/menu_items.3x
+++ b/contrib/ncurses/man/menu_items.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_items.3x,v 1.5 1998/11/29 01:09:56 Rick.Ohnemus Exp $
+.\" $Id: menu_items.3x,v 1.7 2006/11/04 18:35:31 tom Exp $
.TH menu_items 3X ""
.SH NAME
\fBmenu_items\fR - make and break connections between items and menus
@@ -43,32 +43,34 @@ int item_count(const MENU *menu);
.SH DESCRIPTION
The function \fBset_menu_items\fR changes the item pointer array of the given
\fImenu\fR. The array must be terminated by a \fBNULL\fR.
-
+.PP
The function \fBmenu_items\fR returns the item array of the given menu.
-
+.PP
The function \fBitem_count\fR returns the count of items in \fImenu\fR.
.SH RETURN VALUES
-The function \fBmenu_items\fR returns \fBNULL\fR on error.
-
+The function \fBmenu_items\fR returns a pointer (which may be \fBNULL\fR).
+It does not set errno.
+.PP
The function \fBitem_count\fR returns \fBERR\fR (the general \fBcurses\fR error
-return value) on error.
-
+return value) if its \fImenu\fP parameter is \fBNULL\fP.
+.PP
The function \fBset_menu_items\fR returns one of the following codes on error:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
-.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_POSTED\fR
+.B E_NOT_CONNECTED
+No items are connected to the menu.
+.TP 5
+.B E_POSTED
The menu is already posted.
.TP 5
-\fBE_NOT_CONNECTED\fR
-No items are connected to the menu.
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).
+.
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
.SH NOTES
@@ -77,7 +79,7 @@ The header file \fB<menu.h>\fR automatically includes the header file
.SH PORTABILITY
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
diff --git a/contrib/ncurses/man/menu_mark.3x b/contrib/ncurses/man/menu_mark.3x
index 72ea000335e4..1db2b3ee1974 100644
--- a/contrib/ncurses/man/menu_mark.3x
+++ b/contrib/ncurses/man/menu_mark.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_mark.3x,v 1.6 1998/11/29 01:10:03 Rick.Ohnemus Exp $
+.\" $Id: menu_mark.3x,v 1.9 2006/11/04 18:33:18 tom Exp $
.TH menu_mark 3X ""
.SH NAME
\fBmenu_mark\fR - get and set the menu mark string
@@ -42,29 +42,31 @@ const char *menu_mark(const MENU *menu);
In order to make menu selections visible on older terminals without
highlighting or color capability, the menu library marks selected items
in a menu with a prefix string.
-
+.PP
The function \fBset_menu_mark\fR sets the mark string for the given menu.
Calling \fBset_menu_mark\fR with a null menu item will abolish the mark string.
Note that changing the length of the mark string for a menu while the
menu is posted is likely to produce unhelpful behavior.
-
+.PP
The default string is "-" (a dash). Calling \fBset_menu_mark\fR with
-a \fBNULL\fR menu argument will change this default.
-
+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
there is none).
.SH RETURN VALUE
-The function \fBmenu_mark\fR returns \fBNULL\fR on error. The function
-\fBset_menu_mark\fR may return the following error codes:
+The function \fBmenu_mark\fR returns a pointer (which may be \fBNULL\fR).
+It does not set errno.
+.PP
+The function \fBset_menu_mark\fR may return the following error codes:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
-.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
.SH NOTES
diff --git a/contrib/ncurses/man/menu_new.3x b/contrib/ncurses/man/menu_new.3x
index c53bd9b8cb65..c2b98e499055 100644
--- a/contrib/ncurses/man/menu_new.3x
+++ b/contrib/ncurses/man/menu_new.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_new.3x,v 1.7 1998/11/29 01:10:13 Rick.Ohnemus Exp $
+.\" $Id: menu_new.3x,v 1.9 2006/11/04 18:31:37 tom Exp $
.TH menu_new 3X ""
.SH NAME
\fBmenu_new\fR - create and destroy menus
@@ -41,24 +41,31 @@ int free_menu(MENU *menu);
.SH DESCRIPTION
The function \fBnew_menu\fR creates a new menu connected to a specified item
pointer array (which must be \fBNULL\fR-terminated).
-
+.PP
The function \fBfree_menu\fR disconnects \fImenu\fR from its item array
and frees the storage allocated for the menu.
.SH RETURN VALUE
The function \fBnew_menu\fR returns \fBNULL\fR on error.
-
+It sets errno according to the function's failure:
+.TP 5
+.B E_NOT_CONNECTED
+No items are connected to the menu.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred, e.g., malloc failure.
+.PP
The function \fBfree_menu\fR returns one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_POSTED\fR
+.B E_POSTED
The menu has already been posted.
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
diff --git a/contrib/ncurses/man/menu_opts.3x b/contrib/ncurses/man/menu_opts.3x
index 30cad58d4957..890b2c265134 100644
--- a/contrib/ncurses/man/menu_opts.3x
+++ b/contrib/ncurses/man/menu_opts.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_opts.3x,v 1.7 1998/11/29 01:10:21 Rick.Ohnemus Exp $
+.\" $Id: menu_opts.3x,v 1.9 2006/11/04 17:12:00 tom Exp $
.TH menu_opts 3X ""
.SH NAME
\fBmenu_opts\fR - set and get menu options
@@ -45,15 +45,15 @@ OPTIONS menu_opts(const MENU *menu);
.SH DESCRIPTION
The function \fBset_menu_opts\fR sets all the given menu's option bits (menu
option bits may be logically-OR'ed together).
-
+.PP
The function \fBmenu_opts_on\fR turns on the given option bits, and leaves
others alone.
-
+.PP
The function \fBmenu_opts_off\fR turns off the given option bits, and leaves
others alone.
-
+.PP
The function \fBmenu_opts\fR returns the menu's current option bits.
-
+.PP
The following options are defined (all are on by default):
.TP 5
O_ONEVALUE
@@ -77,13 +77,13 @@ requests to the other end of the menu.
.SH RETURN VALUE
Except for \fBmenu_opts\fR, each routine returns one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.TP 5
-\fBE_POSTED\fR
+.B E_POSTED
The menu is already posted.
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
diff --git a/contrib/ncurses/man/menu_pattern.3x b/contrib/ncurses/man/menu_pattern.3x
index 990a9dc52bac..50dee87a1e84 100644
--- a/contrib/ncurses/man/menu_pattern.3x
+++ b/contrib/ncurses/man/menu_pattern.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2006 Free 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: menu_pattern.3x,v 1.7 2002/02/16 22:40:59 tom Exp $
+.\" $Id: menu_pattern.3x,v 1.10 2006/11/04 18:25:24 tom Exp $
.TH menu_pattern 3X ""
.SH NAME
\fBmenu_pattern\fR - get and set a menu's pattern buffer
@@ -41,28 +41,37 @@ char *menu_pattern(const MENU *menu);
Every menu has an associated pattern match buffer. As input events that are
printable ASCII 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.
-
+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 \fBNULL\fR on error. The function
-\fBset_menu_pattern\fR may return the following error codes:
+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:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
-.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_NO_MATCH\fR
+.B E_BAD_STATE
+Routine was called from an initialization or termination function.
+.TP 5
+.B E_NOT_CONNECTED
+No items are connected to menu.
+.TP 5
+.B E_NO_MATCH
Character failed to match.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
.SH NOTES
diff --git a/contrib/ncurses/man/menu_post.3x b/contrib/ncurses/man/menu_post.3x
index a4182d649520..e47facc9e4d9 100644
--- a/contrib/ncurses/man/menu_post.3x
+++ b/contrib/ncurses/man/menu_post.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_post.3x,v 1.7 1998/11/29 01:10:33 Rick.Ohnemus Exp $
+.\" $Id: menu_post.3x,v 1.9 2006/11/04 17:12:00 tom Exp $
.TH menu_post 3X ""
.SH NAME
\fBmenu_post\fR - write or erase menus from associated subwindows
@@ -43,34 +43,34 @@ The function \fBpost_menu\fR displays a menu to its associated subwindow. To
trigger physical display of the subwindow, use \fBrefresh\fR or some equivalent
\fBcurses\fR routine (the implicit \fBdoupdate\fR triggered by an \fBcurses\fR
input request will do). \fBpost_menu\fR resets the selection status of all items.
-
+.PP
The function \fBunpost_menu\fR erases menu from its associated subwindow.
.SH RETURN VALUE
These routines return one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_POSTED\fR
+.B E_POSTED
The menu has already been posted.
.TP 5
-\fBE_BAD_STATE\fR
+.B E_BAD_STATE
Routine was called from an initialization or termination function.
.TP 5
-\fBE_NO_ROOM\fR
+.B E_NO_ROOM
Menu is too large for its window. You should consider to use
\fBset_menu_format()\fR to solve the problem.
.TP 5
-\fBE_NOT_POSTED\fR
+.B E_NOT_POSTED
The menu has not been posted.
.TP 5
-\fBE_NOT_CONNECTED\fR
+.B E_NOT_CONNECTED
No items are connected to the menu.
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
diff --git a/contrib/ncurses/man/menu_requestname.3x b/contrib/ncurses/man/menu_requestname.3x
index f4b646a455fc..1345aa784851 100644
--- a/contrib/ncurses/man/menu_requestname.3x
+++ b/contrib/ncurses/man/menu_requestname.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_requestname.3x,v 1.6 1998/11/29 01:10:40 Rick.Ohnemus Exp $
+.\" $Id: menu_requestname.3x,v 1.7 2006/11/04 17:56:09 tom Exp $
.TH menu_requestname 3X ""
.SH NAME
\fBmenu_requestname\fR - handle printable menu request names
@@ -43,12 +43,14 @@ The function \fBmenu_request_name\fR returns the printable name of a menu
request code.
.br
The function \fBmenu_request_by_name\fR searches in the name-table for a request
-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
-\fBmenu_request_name\fR returns \fBNULL\fR on error and sets errno
-to \fBE_BAD_ARGUMENT\fR.
+\fBmenu_request_name\fR returns \fBNULL\fR on error
+and sets errno to \fBE_BAD_ARGUMENT\fR.
.br
\fBmenu_request_by_name\fR returns \fBE_NO_MATCH\fR on error.
+It does not set errno.
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
.SH NOTES
diff --git a/contrib/ncurses/man/menu_spacing.3x b/contrib/ncurses/man/menu_spacing.3x
index 183162193204..dfe03a8a55b1 100644
--- a/contrib/ncurses/man/menu_spacing.3x
+++ b/contrib/ncurses/man/menu_spacing.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2001 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2001,2004 Free 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_spacing.3x,v 1.6 2001/08/04 20:36:16 William.Setzer Exp $
+.\" $Id: menu_spacing.3x,v 1.8 2004/12/11 23:39:07 tom Exp $
.TH menu_spacing 3X ""
.SH NAME
\fBmenu_spacing\fR - Control spacing between menu items.
@@ -51,7 +51,7 @@ description. It must not be larger than \fBTABSIZE\fR. The menu system puts in t
middle of this spacing area the pad character. The remaining parts are filled with
spaces.
\fBspc_rows\fR controls the number of rows that are used for an item. It must not be
-larger than 3. The menu system inserts then blank lines between item rows, these lines
+larger than 3. The menu system inserts the blank lines between item rows, these lines
will contain the pad character in the appropriate positions.
\fBspc_columns\fR controls the number of blanks between columns of items. It must not
be larger than TABSIZE.
diff --git a/contrib/ncurses/man/menu_userptr.3x b/contrib/ncurses/man/menu_userptr.3x
index 1fe354183d83..b7be2adcd8d0 100644
--- a/contrib/ncurses/man/menu_userptr.3x
+++ b/contrib/ncurses/man/menu_userptr.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_userptr.3x,v 1.6 1998/11/29 01:11:02 Rick.Ohnemus Exp $
+.\" $Id: menu_userptr.3x,v 1.8 2006/11/04 18:21:03 tom Exp $
.TH menu_userptr 3X ""
.SH NAME
\fBmenu_userptr\fR - associate application data with a menu item
@@ -43,14 +43,10 @@ Every menu and every menu item has a field that can be used to hold
application-specific data (that is, the menu-driver code leaves it alone).
These functions get and set the menu user pointer field.
.SH RETURN VALUE
-Except for \fBmenu_userptr\fR (which returns \fBNULL\fR on error), each
-function returns one of the following:
-.TP 5
-\fBE_OK\fR
-The routine succeeded.
-.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
+\fBmenu_userptr\fR returns a pointer (which may be \fBNULL\fR).
+It does not set errno.
+.PP
+\fBset_menu_userptr\fP returns \fBE_OK\fP (success).
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
.SH NOTES
@@ -59,9 +55,9 @@ The header file \fB<menu.h>\fR automatically includes the header file
.SH PORTABILITY
These routines emulate the System V menu library. They were not supported on
Version 7 or BSD versions.
-
-The user pointer should be a void pointer. We leave it as a char pointer for
-SVr4 compatibility.
+.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.
diff --git a/contrib/ncurses/man/menu_win.3x b/contrib/ncurses/man/menu_win.3x
index 336da44b0c5b..aa356e18de7e 100644
--- a/contrib/ncurses/man/menu_win.3x
+++ b/contrib/ncurses/man/menu_win.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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.6 1998/11/29 01:11:11 Rick.Ohnemus Exp $
+.\" $Id: menu_win.3x,v 1.8 2006/11/04 17:12:00 tom Exp $
.TH menu_win 3X ""
.SH NAME
\fBmenu_win\fR - make and break menu window and subwindow associations
@@ -48,33 +48,33 @@ int scale_menu(const MENU *menu, int *rows, int *columns);
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
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
it were \fBstsdcr\fR. A menu argument of \fBNULL\fR is treated as a request
to change the system default menu window or subwindow.
-
+.PP
The function \fBscale_menu\fR returns the minimum size required for the
subwindow of \fImenu\fR.
.SH RETURN VALUE
Routines that return pointers return \fBNULL\fR on error. Routines that return
an integer return one of the following error codes:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_POSTED\fR
+.B E_POSTED
The menu has already been posted.
.TP 5
-\fBE_NOT_CONNECTED\fR
+.B E_NOT_CONNECTED
No items are connected to the menu.
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
diff --git a/contrib/ncurses/man/mitem_current.3x b/contrib/ncurses/man/mitem_current.3x
index 179a23be3b2e..979f401341fe 100644
--- a/contrib/ncurses/man/mitem_current.3x
+++ b/contrib/ncurses/man/mitem_current.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_current.3x,v 1.9 1998/12/26 19:52:34 tom Exp $
+.\" $Id: mitem_current.3x,v 1.11 2006/11/04 18:18:19 tom Exp $
.TH mitem_current 3X ""
.SH NAME
\fBmitem_current\fR - set and get current_menu_item
@@ -48,37 +48,38 @@ int item_index(const ITEM *item);
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
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
row being displayed.
-
+.PP
The function \fBitem_index\fR returns the (zero-origin) index of \fIitem\fR in
the menu's item pointer list.
.SH RETURN VALUE
-\fBcurrent_item\fR returns \fBNULL\fR on error.
-
+\fBcurrent_item\fR returns a pointer (which may be \fBNULL\fR).
+It does not set errno.
+.PP
\fBtop_row\fR and \fBitem_index\fR return \fBERR\fR (the general \fBcurses\fR
-error value) on error.
-
+error value) if their \fImenu\fP parameter is \fBNULL\fP.
+.PP
\fBset_current_item\fR and \fBset_top_row\fR return one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
-.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_BAD_STATE\fR
+.B E_BAD_STATE
Routine was called from an initialization or termination function.
.TP 5
-\fBE_NOT_CONNECTED\fR
+.B E_NOT_CONNECTED
No items are connected to the menu.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
.SH NOTES
@@ -87,7 +88,7 @@ The header file \fB<menu.h>\fR automatically includes the header file
.SH PORTABILITY
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
diff --git a/contrib/ncurses/man/mitem_name.3x b/contrib/ncurses/man/mitem_name.3x
index 007752e0bbe4..12009edace35 100644
--- a/contrib/ncurses/man/mitem_name.3x
+++ b/contrib/ncurses/man/mitem_name.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_name.3x,v 1.5 1998/11/29 01:11:29 Rick.Ohnemus Exp $
+.\" $Id: mitem_name.3x,v 1.6 2006/11/04 17:53:40 tom Exp $
.TH mitem_name 3X ""
.SH NAME
\fBmitem_name\fR - get menu item name and description fields
@@ -44,15 +44,16 @@ The function \fBitem_name\fR returns the name part of the given item.
The function \fBitem_description\fR returns the description part of the given
item.
.SH RETURN VALUE
-These routines returns \fBNULL\fR on error.
+These routines return a pointer (which may be \fBNULL\fR).
+They do not set errno.
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
.SH NOTES
The header file \fB<menu.h>\fR automatically includes the header file
\fB<curses.h>\fR.
.SH PORTABILITY
-These routines emulate the System V menu library. They were not supported on
-Version 7 or BSD versions.
+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.
diff --git a/contrib/ncurses/man/mitem_new.3x b/contrib/ncurses/man/mitem_new.3x
index 0653840167bd..c0fa6edcf64a 100644
--- a/contrib/ncurses/man/mitem_new.3x
+++ b/contrib/ncurses/man/mitem_new.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2006 Free 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_new.3x,v 1.7 1998/11/29 01:11:38 Rick.Ohnemus Exp $
+.\" $Id: mitem_new.3x,v 1.10 2006/11/04 18:16:36 tom Exp $
.TH mitem_new 3X ""
.SH NAME
\fBmitem_new\fR - create and destroy menu items
@@ -42,7 +42,7 @@ int free_item(ITEM *item);
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 carefull with names
+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
@@ -50,20 +50,27 @@ is the responsibility of the application to release the memory for the
name or the description of the item.
.SH RETURN VALUE
The function \fBnew_item\fR returns \fBNULL\fR on error.
-
+It sets errno according to the function's failure:
+.TP 5
+.B E_BAD_ARGUMENT
+Routine detected an incorrect or out-of-range argument.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred, e.g., malloc failure.
+.PP
The function \fBfree_item\fR returns one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
-.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
Routine detected an incorrect or out-of-range argument.
.TP 5
-\fBE_CONNECTED\fR
+.B E_CONNECTED
Item is connected to a menu.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
.SH NOTES
diff --git a/contrib/ncurses/man/mitem_opts.3x b/contrib/ncurses/man/mitem_opts.3x
index 99e4e5ea7e99..2a4a8761d081 100644
--- a/contrib/ncurses/man/mitem_opts.3x
+++ b/contrib/ncurses/man/mitem_opts.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_opts.3x,v 1.6 1998/11/29 01:12:37 Rick.Ohnemus Exp $
+.\" $Id: mitem_opts.3x,v 1.8 2006/11/04 17:12:00 tom Exp $
.TH mitem_opts 3X ""
.SH NAME
\fBmitem_opts\fR - set and get menu item options
@@ -45,25 +45,25 @@ OPTIONS item_opts(const ITEM *item);
.SH DESCRIPTION
The function \fBset_item_opts\fR sets all the given item's option bits (menu
option bits may be logically-OR'ed together).
-
+.PP
The function \fBitem_opts_on\fR turns on the given option bits, and leaves
others alone.
-
+.PP
The function \fBitem_opts_off\fR turns off the given option bits, and leaves
others alone.
-
+.PP
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
to on.
.SH RETURN VALUE
Except for \fBitem_opts\fR, each routine returns one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
diff --git a/contrib/ncurses/man/mitem_userptr.3x b/contrib/ncurses/man/mitem_userptr.3x
index 2dd564fd61e8..58951930244c 100644
--- a/contrib/ncurses/man/mitem_userptr.3x
+++ b/contrib/ncurses/man/mitem_userptr.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998,2006 Free 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_userptr.3x,v 1.6 1998/11/29 01:12:47 Rick.Ohnemus Exp $
+.\" $Id: mitem_userptr.3x,v 1.9 2006/11/04 18:21:03 tom Exp $
.TH mitem_userptr 3X ""
.SH NAME
\fBmitem_userptr\fR - associate application data with a menu item
@@ -43,13 +43,11 @@ 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 field.
.SH RETURN VALUE
-Except for \fBitem_userptr\fR (which returns \fBNULL\fR on error), each function returns one of the following:
-.TP 5
-\fBE_OK\fR
-The routine succeeded.
-.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
+The function \fBitem_userptr\fR returns a pointer (possibly \fBNULL\fR).
+It does not set errno.
+.PP
+The \fBset_item_userptr\fP always returns \fBE_OK\fP (success).
+.
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
.SH NOTES
@@ -58,9 +56,9 @@ The header file \fB<menu.h>\fR automatically includes the header file
.SH PORTABILITY
These routines emulate the System V menu library. They were not supported on
Version 7 or BSD versions.
-
-The user pointer should be a void pointer. We leave it as a char pointer for
-SVr4 compatibility.
+.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.
diff --git a/contrib/ncurses/man/mitem_value.3x b/contrib/ncurses/man/mitem_value.3x
index 5817d8d277b6..748fd528675c 100644
--- a/contrib/ncurses/man/mitem_value.3x
+++ b/contrib/ncurses/man/mitem_value.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2002,2006 Free 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: mitem_value.3x,v 1.6 2002/02/16 22:40:59 tom Exp $
+.\" $Id: mitem_value.3x,v 1.8 2006/11/04 17:12:00 tom Exp $
.TH mitem_value 3X ""
.SH NAME
\fBmitem_value\fR - set and get menu item values
@@ -42,20 +42,20 @@ If you turn off the menu option \fBO_ONEVALUE\fR (e.g., with
\fBset_menu_opts\fR or \fBmenu_opts_off\fR; see \fBmenu_opts\fR(3X)), the menu
becomes multi-valued; that is, more than one item may simultaneously be
selected.
-
+.PP
In a multi_valued menu, you can used \fBset_item_value\fR to select the
given menu item (second argument \fBTRUE\fR) or deselect it (second argument
\fBFALSE\fR).
.SH RETURN VALUE
The function \fBset_item_value\fR returns one of the following:
.TP 5
-\fBE_OK\fR
+.B E_OK
The routine succeeded.
.TP 5
-\fBE_SYSTEM_ERROR\fR
+.B E_SYSTEM_ERROR
System error occurred (see \fBerrno\fR).
.TP 5
-\fBE_REQUEST_DENIED\fR
+.B E_REQUEST_DENIED
The menu driver could not process the request.
.SH SEE ALSO
\fBcurses\fR(3X), \fBmenu\fR(3X).
diff --git a/contrib/ncurses/man/ncurses.3x b/contrib/ncurses/man/ncurses.3x
index 84ead5cab868..19678daab005 100644
--- a/contrib/ncurses/man/ncurses.3x
+++ b/contrib/ncurses/man/ncurses.3x
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,1999,2001,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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.61 2002/05/11 21:15:32 tom Exp $
+.\" $Id: ncurses.3x,v 1.81 2006/12/02 19:23:11 tom Exp $
.hy 0
.TH ncurses 3X ""
.ds n 5
@@ -42,79 +42,82 @@ The \fBncurses\fR library routines give the user a terminal-independent method
of updating character screens with reasonable optimization. This
implementation is ``new curses'' (ncurses) and is the approved replacement for
4.4BSD classic curses, which has been discontinued.
-
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
+.PP
The \fBncurses\fR routines emulate the \fBcurses\fR(3X) library of System V
Release 4 UNIX, and the XPG4 curses standard (XSI curses) but the \fBncurses\fR
library is freely redistributable in source form. Differences from the SVr4
-curses are summarized under the EXTENSIONS and BUGS sections below and
-described in detail in the EXTENSIONS and BUGS sections of individual man
-pages.
-
+curses are summarized under the \fBEXTENSIONS\fP and \fBPORTABILITY\fP sections below and
+described in detail in the respective \fBEXTENSIONS\fP, \fBPORTABILITY\fP and \fBBUGS\fP sections
+of individual man pages.
+.PP
A program using these routines must be linked with the \fB-lncurses\fR option,
or (if it has been generated) with the debugging library \fB-lncurses_g\fR.
(Your system integrator may also have installed these libraries under
the names \fB-lcurses\fR and \fB-lcurses_g\fR.)
The ncurses_g library generates trace logs (in a file called 'trace' in the
current directory) that describe curses actions.
-
+See also the section on \fBALTERNATE CONFIGURATIONS\fP.
+.PP
The \fBncurses\fR package supports: overall screen, window and pad
manipulation; output to windows and pads; reading terminal input; control over
terminal and \fBcurses\fR input and output options; environment query
routines; color manipulation; use of soft label keys; terminfo capabilities;
and access to low-level terminal-manipulation routines.
-
+.PP
To initialize the routines, the routine \fBinitscr\fR or \fBnewterm\fR
must be called before any of the other routines that deal with windows
and screens are used. The routine \fBendwin\fR must be called before
exiting. To get character-at-a-time input without echoing (most
interactive, screen oriented programs want this), the following
sequence should be used:
-
+.sp
\fBinitscr(); cbreak(); noecho();\fR
-
+.sp
Most programs would additionally use the sequence:
-
+.sp
\fBnonl();\fR
\fBintrflush(stdscr, FALSE);\fR
\fBkeypad(stdscr, TRUE);\fR
-
+.sp
Before a \fBcurses\fR program is run, the tab stops of the terminal
should be set and its initialization strings, if defined, must be
output. This can be done by executing the \fBtput init\fR command
after the shell environment variable \fBTERM\fR has been exported.
\fBtset(1)\fR is usually responsible for doing this.
[See \fBterminfo\fR(\*n) for further details.]
-
+.PP
The \fBncurses\fR library permits manipulation of data structures,
called \fIwindows\fR, which can be thought of as two-dimensional
arrays of characters representing all or part of a CRT screen. A
default window called \fBstdscr\fR, which is the size of the terminal
screen, is supplied. Others may be created with \fBnewwin\fR.
-
+.PP
Note that \fBcurses\fR does not handle overlapping windows, that's done by
the \fBpanel\fR(3X) library. This means that you can either use
\fBstdscr\fR or divide the screen into tiled windows and not using
\fBstdscr\fR at all. Mixing the two will result in unpredictable, and
undesired, effects.
-
+.PP
Windows are referred to by variables declared as \fBWINDOW *\fR.
These data structures are manipulated with routines described here and
-elsewhere in the \fBncurses\fR manual pages. Among which the most basic
+elsewhere in the \fBncurses\fR manual pages. Among those, the most basic
routines are \fBmove\fR and \fBaddch\fR. More general versions of
these routines are included with names beginning with \fBw\fR,
allowing the user to specify a window. The routines not beginning
-with \fBw\fR affect \fBstdscr\fR.)
-
+with \fBw\fR affect \fBstdscr\fR.
+.PP
After using routines to manipulate a window, \fBrefresh\fR is called,
telling \fBcurses\fR to make the user's CRT screen look like
\fBstdscr\fR. The characters in a window are actually of type
\fBchtype\fR, (character and attribute data) so that other information
about the character may also be stored with each character.
-
+.PP
Special windows called \fIpads\fR may also be manipulated. These are windows
which are not constrained to the size of the screen and whose contents need not
be completely displayed. See \fBcurs_pad\fR(3X) for more information.
-
+.PP
In addition to drawing characters on the screen, video attributes and colors
may be supported, causing the characters to show up in such modes as
underlined, in reverse video, or in color on terminals that support such
@@ -123,75 +126,74 @@ On input, \fBcurses\fR is also able to translate arrow and function keys that
transmit escape sequences into single values. The video attributes, line
drawing characters, and input values use names, defined in \fB<curses.h>\fR,
such as \fBA_REVERSE\fR, \fBACS_HLINE\fR, and \fBKEY_LEFT\fR.
-
+.PP
If the environment variables \fBLINES\fR and \fBCOLUMNS\fR are set, or if the
program is executing in a window environment, line and column information in
the environment will override information read by \fIterminfo\fR. This would
effect a program running in an AT&T 630 layer, for example, where the size of a
screen is changeable (see \fBENVIRONMENT\fR).
-
+.PP
If the environment variable \fBTERMINFO\fR is defined, any program using
\fBcurses\fR checks for a local terminal definition before checking in the
standard place. For example, if \fBTERM\fR is set to \fBatt4424\fR, then the
compiled terminal definition is found in
-
+.sp
\fB\*d/a/att4424\fR.
-
+.sp
(The \fBa\fR is copied from the first letter of \fBatt4424\fR to avoid
creation of huge directories.) However, if \fBTERMINFO\fR is set to
\fB$HOME/myterms\fR, \fBcurses\fR first checks
-
+.sp
\fB$HOME/myterms/a/att4424\fR,
-
+.sp
and if that fails, it then checks
-
+.sp
\fB\*d/a/att4424\fR.
-
+.sp
This is useful for developing experimental definitions or when write
permission in \fB\*d\fR is not available.
-
+.PP
The integer variables \fBLINES\fR and \fBCOLS\fR are defined in
\fB<curses.h>\fR and will be filled in by \fBinitscr\fR with the size of the
screen. The constants \fBTRUE\fR and \fBFALSE\fR have the values \fB1\fR and
\fB0\fR, respectively.
-
+.PP
The \fBcurses\fR routines also define the \fBWINDOW *\fR variable \fBcurscr\fR
which is used for certain low-level operations like clearing and redrawing a
screen containing garbage. The \fBcurscr\fR can be used in only a few
routines.
-
+.
.SS Routine and Argument Names
Many \fBcurses\fR routines have two or more versions. The routines prefixed
with \fBw\fR require a window argument. The routines prefixed with \fBp\fR
require a pad argument. Those without a prefix generally use \fBstdscr\fR.
-
+.PP
The routines prefixed with \fBmv\fR require a \fIy\fR and \fIx\fR
coordinate to move to before performing the appropriate action. The
\fBmv\fR routines imply a call to \fBmove\fR before the call to the
other routine. The coordinate \fIy\fR always refers to the row (of
the window), and \fIx\fR always refers to the column. The upper
left-hand corner is always (0,0), not (1,1).
-
+.PP
The routines prefixed with \fBmvw\fR take both a window argument and
\fIx\fR and \fIy\fR coordinates. The window argument is always
specified before the coordinates.
-
+.PP
In each case, \fIwin\fR is the window affected, and \fIpad\fR is the
pad affected; \fIwin\fR and \fIpad\fR are always pointers to type
\fBWINDOW\fR.
-
+.PP
Option setting routines require a Boolean flag \fIbf\fR with the value
\fBTRUE\fR or \fBFALSE\fR; \fIbf\fR is always of type \fBbool\fR. The
variables \fIch\fR and \fIattrs\fR below are always of type
\fBchtype\fR. The types \fBWINDOW\fR, \fBSCREEN\fR, \fBbool\fR, and
\fBchtype\fR are defined in \fB<curses.h>\fR. The type \fBTERMINAL\fR
is defined in \fB<term.h>\fR. All other arguments are integers.
-
.SS Routine Name Index
The following table lists each \fBcurses\fR routine and the name of
the manual page on which it is described. Routines flagged with `*'
are ncurses-specific, not described by XPG4 or present in SVr4.
-
+.PP
.TS
center tab(/);
l l
@@ -322,6 +324,7 @@ inwstr/\fBcurs_inwstr\fR(3X)
is_linetouched/\fBcurs_touch\fR(3X)
is_wintouched/\fBcurs_touch\fR(3X)
isendwin/\fBcurs_initscr\fR(3X)
+key_defined/\fBkey_defined\fR(3X)*
key_name/\fBcurs_util\fR(3X)
keybound/\fBkeybound\fR(3X)*
keyname/\fBcurs_util\fR(3X)
@@ -612,13 +615,13 @@ wvline_set/\fBcurs_border_set\fR(3X)
Routines that return an integer return \fBERR\fR upon failure and an
integer value other than \fBERR\fR upon successful completion, unless
otherwise noted in the routine descriptions.
-
+.PP
All macros return the value of the \fBw\fR version, except \fBsetscrreg\fR,
-\fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, \fBgetmaxyx\fR. The return
+\fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and \fBgetmaxyx\fR. The return
values of \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and
-\fBgetmaxyx\fR are undefined (\fIi\fR.\fIe\fR., these should not be used as the
+\fBgetmaxyx\fR are undefined (i.e., these should not be used as the
right-hand side of assignment statements).
-
+.PP
Routines that return pointers return \fBNULL\fR on error.
.SH ENVIRONMENT
The following environment symbols are useful for customizing the
@@ -629,7 +632,7 @@ BAUDRATE
The debugging library checks this environment symbol when the application
has redirected output to a file.
The symbol's numeric value is used for the baudrate.
-If no value is found \fBncurses\fR uses 9600.
+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
@@ -643,45 +646,55 @@ COLUMNS
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 $COLUMNS value nor the terminal's screen size is available,
+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
It is important that your application use a correct size for the screen.
-However, this is not always possible because your application may be
+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.
-
-Either COLUMNS or LINES symbols may be specified independently.
+However, setting \fBCOLUMNS\fP and/or \fBLINES\fP overrides the library's
+use of the screen size obtained from the operating system.
+.IP
+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.
-
-Use the \fBuse_env\fR function to disable this feature.
+.IP
+Use the \fBuse_env\fR function to disable all use of external environment
+(including system calls) to determine the screen size.
.TP 5
ESCDELAY
Specifies the total time, in milliseconds, for which ncurses will
await a character sequence, e.g., a function key.
The default value, 1000 milliseconds, is enough for most uses.
However, it is made a variable to accommodate unusual applications.
-
+.IP
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
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
+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
Tells \fBncurses\fR where your home directory is.
That is where it may read and write auxiliary terminal descriptions:
-
+.IP
$HOME/.termcap
.br
$HOME/.terminfo
@@ -695,17 +708,41 @@ This applies only to the OS/2 EMX port.
It specifies the order of buttons on the mouse.
OS/2 numbers a 3-button mouse inconsistently from other
platforms:
-
+.sp
1 = left
.br
2 = right
.br
3 = middle.
-
+.sp
This symbol lets you customize the mouse.
The symbol 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
+Override the compiled-in assumption that the
+terminal's default colors are white-on-black
+(see \fBassume_default_colors\fR(3X)).
+You may set the foreground and background color values with this environment
+variable by proving a 2-element list: foreground,background.
+For example, to tell ncurses to not assume anything
+about the colors, set this to "-1,-1".
+To make it green-on-black, set it to "2,0".
+Any positive value from zero to the terminfo \fBmax_colors\fR value is allowed.
+.TP 5
+NCURSES_NO_HARD_TABS
+\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
+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
Most of the terminal descriptions in the terminfo database are written
for real "hardware" terminals.
@@ -722,11 +759,11 @@ 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
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
Set the NCURSES_NO_PADDING symbol to disable all but mandatory
padding. Mandatory padding is used as a part of special control
sequences such as \fIflash\fR.
@@ -739,12 +776,30 @@ this feature is made optional. Setting the NCURSES_NO_SETBUF variable
disables output buffering, leaving the output in the original (usually
line buffered) mode.
.TP 5
+NCURSES_NO_UTF8_ACS
+During initialization, the \fBncurses\fR library
+checks for special cases where VT100 line-drawing (and the corresponding
+alternate character set capabilities) described in the terminfo are known
+to be missing.
+Specifically, when running in a UTF-8 locale,
+the Linux console emulator and the GNU screen program ignore these.
+Ncurses checks the TERM environment variable for these.
+For other special cases, you should set this environment variable.
+Doing this tells ncurses to use Unicode values which correspond to
+the VT100 line-drawing glyphs.
+That works for the special cases cited,
+and is likely to work for terminal emulators.
+.IP
+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.
+.TP 5
NCURSES_TRACE
During initialization, the \fBncurses\fR debugging library
checks the NCURSES_TRACE symbol.
If it is defined, to a numeric value, \fBncurses\fR calls the \fBtrace\fR
function, using that value as the argument.
-
+.IP
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
@@ -758,7 +813,7 @@ 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 symbol contains either a terminal description (with
newlines stripped out),
or a file name telling where the information denoted by the TERM symbol exists.
@@ -773,7 +828,7 @@ The complete list of directories in order follows:
.RS
.TP 3
-
-the last directory to which \fBncurses\fR wrote, if any, is searched first.
+the last directory to which \fBncurses\fR wrote, if any, is searched first
.TP 3
-
the directory specified by the TERMINFO symbol
@@ -807,6 +862,76 @@ 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:
$TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
+.SH ALTERNATE CONFIGURATIONS
+Several different configurations are possible,
+depending on the configure script options used when building \fBncurses\fP.
+There are a few main options whose effects are visible to the applications
+developer using \fBncurses\fP:
+.TP 5
+--disable-overwrite
+The standard include for \fBncurses\fP is as noted in \fBSYNOPSIS\fP:
+.RS
+.sp
+\fB#include <curses.h>\fR
+.RE
+.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
+\fB#include <ncurses/curses.h>\fR
+.RE
+.IP
+It also omits a symbolic link which would allow you to use \fB-lcurses\fP
+to build executables.
+.TP 5
+--enable-widec
+The configure script renames the library and (if the \fB--disable-overwrite\fP
+option is used) puts the header files in a different subdirectory.
+All of the library names have a "w" appended to them,
+i.e., instead of
+.RS
+.sp
+\fB-lncurses\fR
+.RE
+.IP
+you link with
+.RS
+.sp
+\fB-lncursesw\fR
+.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.
+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-shared
+.TP
+--with-normal
+.TP
+--with-debug
+.TP
+--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,
+e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP.
+.TP 5
+--with-trace
+The \fBtrace\fP function normally resides in the debug library,
+but it is sometimes useful to configure this in the shared library.
+Configure scripts should check for the function's existence rather
+than assuming it is always in the debug library.
.SH FILES
.TP 5
@DATADIR@/tabset
@@ -822,23 +947,24 @@ that falls back to the old-style /etc/termcap file if the terminal setup code
cannot find a terminfo entry corresponding to \fBTERM\fR. Use of this feature
is not recommended, as it essentially includes an entire termcap compiler in
the \fBncurses\fR startup code, at significant cost in core and startup cycles.
-
+.PP
The \fBncurses\fR library includes facilities for capturing mouse events on
certain terminals (including xterm). See the \fBcurs_mouse\fR(3X)
manual page for details.
-
+.PP
The \fBncurses\fR library includes facilities for responding to window
resizing events, e.g., when running in an xterm.
See the \fBresizeterm\fR(3X)
and \fBwresize\fR(3X) manual pages for details.
In addition, the library may be configured with a SIGWINCH handler.
-
+.PP
The \fBncurses\fR library extends the fixed set of function key capabilities
of terminals by allowing the application designer to define additional
key sequences at runtime.
See the \fBdefine_key\fR(3X)
+\fBkey_defined\fR(3X),
and \fBkeyok\fR(3X) manual pages for details.
-
+.PP
The \fBncurses\fR library can exploit the capabilities of terminals which
implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an application
to reset the terminal to its original foreground and background colors.
@@ -846,17 +972,14 @@ From the users' perspective, the application is able to draw colored
text on a background whose color is set independently, providing better
control over color contrasts.
See the \fBdefault_colors\fR(3X) manual page for details.
-
+.PP
The \fBncurses\fR library includes a function for directing application output
to a printer attached to the terminal device. See the \fBcurs_print\fR(3X)
manual page for details.
.SH PORTABILITY
The \fBncurses\fR library is intended to be BASE-level conformant with the XSI
-Curses standard. Certain portions of the EXTENDED XSI Curses functionality
-(including color support) are supported. The following EXTENDED XSI Curses
-calls in support of wide (multibyte) characters are not yet implemented:
-\fBpecho_wchar\fP,
-\fBslk_wset\fP.
+Curses standard. The EXTENDED XSI Curses functionality
+(including color support) is supported.
.PP
A small number of local differences (that is, individual differences between
the XSI Curses and \fBncurses\fR calls) are described in \fBPORTABILITY\fR
@@ -885,22 +1008,10 @@ bits in the UNIX tty driver. In this implementation, all padding is done by
NUL sends. This method is slightly more expensive, but narrows the interface
to the UNIX kernel significantly and increases the package's portability
correspondingly.
-.PP
-In the XSI standard and SVr4 manual pages, many entry points have prototype
-arguments of the for \fBchar *const\fR (or \fBcchar_t *const\fR, or
-\fBwchar_t *const\fR, or \fBvoid *const\fR). Depending on one's interpretation of the
-ANSI C standard (see section 3.5.4.1), these declarations are either (a)
-meaningless, or (b) meaningless and illegal. The declaration
-\fBconst char *x\fR is a modifiable pointer to unmodifiable data, but
-\fBchar *const x\fR' is
-an unmodifiable pointer to modifiable data. Given that C passes arguments by
-value, \fB<type> *const\fR as a formal type is at best dubious. Some compilers
-choke on the prototypes. Therefore, in this implementation, they have been
-changed to \fBconst <type> *\fR globally.
.SH NOTES
The header file \fB<curses.h>\fR automatically includes the header files
\fB<stdio.h>\fR and \fB<unctrl.h>\fR.
-
+.PP
If standard output from a \fBncurses\fR program is re-directed to something
which is not a tty, screen updates will be directed to standard error. This
was an undocumented feature of AT&T System V Release 3 curses.
diff --git a/contrib/ncurses/man/panel.3x b/contrib/ncurses/man/panel.3x
index 7ebecc00ff46..2896f01adc49 100644
--- a/contrib/ncurses/man/panel.3x
+++ b/contrib/ncurses/man/panel.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2006 Free 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: panel.3x,v 1.10 2000/08/13 01:56:47 tom Exp $
+.\" $Id: panel.3x,v 1.12 2006/05/13 15:35:45 tom Exp $
.TH panel 3X ""
.ds n 5
.ds d @TERMINFO@
@@ -77,7 +77,7 @@ The set of currently visible panels is the stack of panels. The
of the stack.
.P
A window is associated with every panel. The panel routines enable
-you to create, move, hides, and show panels, as well as position a
+you to create, move, hide, and show panels, as well as position a
panel at any desired location in the stack.
.P
Panel routines are a functional layer added to \fBcurses\fR(3X), make only
@@ -166,7 +166,7 @@ function to ensure compatibility with native panel libraries.
.SH NOTE
In your library list, libpanel.a should be before libncurses.a; that is,
you want to say `-lpanel -lncurses', not the other way around (which would
-give you a link error using GNU \fBld\fR(1) and some other linkers).
+usually give a link-error).
.SH FILES
.P
panel.h
@@ -176,6 +176,9 @@ libpanel.a
the panels library itself
.SH SEE ALSO
\fBcurses\fR(3X)
+.PP
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.SH AUTHOR
Originally written by Warren Tucker <wht@n4hgf.mt-park.ga.us>,
primarily to assist in porting u386mon to systems without a native
diff --git a/contrib/ncurses/man/resizeterm.3x b/contrib/ncurses/man/resizeterm.3x
index 562c35328901..888eaaf318d1 100644
--- a/contrib/ncurses/man/resizeterm.3x
+++ b/contrib/ncurses/man/resizeterm.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2005 Free 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,9 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" Author: Thomas E. Dickey <dickey@clark.net> 1996,1997,2002
+.\" Author: Thomas E. Dickey 1996-2005
.\"
-.\" $Id: resizeterm.3x,v 1.9 2002/02/16 22:32:24 tom Exp $
+.\" $Id: resizeterm.3x,v 1.11 2005/06/25 22:19:42 tom Exp $
.TH resizeterm 3X ""
.SH NAME
\fBis_term_resized\fR,
@@ -36,7 +36,7 @@
\fBresizeterm\fR - change the curses terminal size
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBbool is_term_resized(int lines, int columns);\fR
.br
\fBint resize_term(int lines, int columns);\fR
@@ -49,7 +49,7 @@ primarily for use by programs running in an X Window terminal (e.g., xterm).
The function \fBresizeterm\fR resizes the standard and current windows
to the specified dimensions, and adjusts other bookkeeping data used by
the \fBncurses\fR library that record the window dimensions.
-
+.LP
Most of the work is done by the inner function \fBresize_term\fR.
The outer function \fBresizeterm\fR adds bookkeeping for the SIGWINCH handler.
When resizing the windows,
@@ -59,7 +59,7 @@ The \fBresize_term\fR function attempts to resize all windows.
However, due to the calling convention of pads,
it is not possible to resize these
without additional interaction with the application.
-
+.LP
A support function \fBis_term_resized\fR is provided so that applications
can check if the \fBresize_term\fR function would modify the window structures.
It returns TRUE if the windows would be modified, and FALSE otherwise.
@@ -80,6 +80,14 @@ will be read on the next call to \fBgetch\fR.
This is used to alert an application that the screen size has changed,
and that it should repaint special features such as pads that cannot
be done automatically.
+.PP
+If the environment variables \fBLINES\fP or \fBCOLUMNS\fP are set,
+this overrides the library's use of the window size obtained from
+the operating system.
+Thus, even if a SIGWINCH is received,
+no screen size change may be recorded.
+In that case, no \fBKEY_RESIZE\fP is queued for the next call to \fBgetch\fP;
+an \fBERR\fP will be returned instead.
.SH SEE ALSO
\fBwresize\fR(3X).
.SH AUTHOR
diff --git a/contrib/ncurses/man/term.5 b/contrib/ncurses/man/term.5
index a8cf6e5ed47b..cd7e79ae9d36 100644
--- a/contrib/ncurses/man/term.5
+++ b/contrib/ncurses/man/term.5
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2004,2006 Free 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: term.5,v 1.13 2002/04/20 16:49:17 tom Exp $
+.\" $Id: term.5,v 1.17 2006/12/03 01:08:16 tom Exp $
.TH TERM 5
.ds n 5
.ds d @TERMINFO@
@@ -35,11 +35,13 @@ term \- format of compiled term file.
.SH SYNOPSIS
.B term
.SH DESCRIPTION
-.PP
+.SS STORAGE LOCATION
Compiled terminfo descriptions are placed under the directory \fB\*d\fP.
-In order to avoid a linear search of a huge \s-1UNIX\s+1 system directory, a
-two-level scheme is used: \fB\*b/c/name\fP
-where
+Two configurations are supported (when building the ncurses libraries):
+.TP 5
+.B directory tree
+A two-level scheme is used to avoid a linear search
+of a huge \s-1UNIX\s+1 system directory: \fB\*d/c/name\fP where
.I name
is the name of the terminal, and
.I c
@@ -50,13 +52,29 @@ Thus,
can be found in the file \fB\*d/a/act4\fP.
Synonyms for the same terminal are implemented by multiple
links to the same compiled file.
-.PP
+.TP 5
+.B hashed database
+Using Berkeley database, two types of records are stored:
+the terminfo data in the same format as stored in a directory tree with
+the terminfo's primary name as a key,
+and records containing only aliases pointing to the primary name.
+.IP
+If built to write hashed databases,
+ncurses can still read terminfo databases organized as a directory tree,
+but cannot write entries into the directory tree.
+It can write (or rewrite) entries in the hashed database.
+.IP
+ncurses distinguishes the two cases in the TERMINFO and TERMINFO_DIRS
+environment variable by assuming a directory tree for entries that
+correspond to an existing directory,
+and hashed database otherwise.
+.SS STORAGE FORMAT
The format has been chosen so that it will be the same on all hardware.
An 8 or more bit byte is assumed, but no assumptions about byte ordering
or sign extension are made.
.PP
The compiled file is created with the
-.I tic
+.I tic
program, and read by the routine
.IR setupterm .
The file is divided into six parts:
@@ -72,19 +90,27 @@ The header section begins the file.
This section contains six short integers in the format
described below.
These integers are
+.RS 5
+.TP 5
(1) the magic number (octal 0432);
+.TP 5
(2) the size, in bytes, of the names section;
+.TP 5
(3) the number of bytes in the boolean section;
+.TP 5
(4) the number of short integers in the numbers section;
+.TP 5
(5) the number of offsets (short integers) in the strings section;
+.TP 5
(6) the size, in bytes, of the string table.
+.RE
.PP
Short integers are stored in two 8-bit bytes.
The first byte contains the least significant 8 bits of the value,
and the second byte contains the most significant 8 bits.
(Thus, the value represented is 256*second+first.)
-The value \-1 is represented by the two bytes 0377, 0377; other negative
-values are illegal. This value generally
+The value -1 is represented by the two bytes 0377, 0377; other negative
+values are illegal. This value generally
means that the corresponding capability is missing from this terminal.
Note that this format corresponds to the hardware of the \s-1VAX\s+1
and \s-1PDP\s+1-11 (that is, little-endian machines).
@@ -112,11 +138,11 @@ All short integers are aligned on a short word boundary.
The numbers section is similar to the flags section.
Each capability takes up two bytes,
and is stored as a little-endian short integer.
-If the value represented is \-1, the capability is taken to be missing.
+If the value represented is -1, the capability is taken to be missing.
.PP
The strings section is also similar.
Each capability is stored as a short integer, in the format above.
-A value of \-1 means the capability is missing.
+A value of -1 means the capability is missing.
Otherwise, the value is taken as an offset from the beginning
of the string table.
Special characters in ^X or \ec notation are stored in their
@@ -128,7 +154,48 @@ The final section is the string table.
It contains all the values of string capabilities referenced in
the string section.
Each string is null terminated.
+.SS EXTENDED STORAGE FORMAT
+The previous section describes the conventional terminfo binary format.
+With some minor variations of the offsets (see PORTABILITY),
+the same binary format is used in all modern UNIX systems.
+Each system uses a predefined set of boolean, number or string capabilities.
+.PP
+The ncurses libraries and applications support extended terminfo binary format,
+allowing users to define capabilities which are loaded at runtime. This
+extension is made possible by using the fact that the other implementations
+stop reading the terminfo data when they have reached the end of the size given
+in the header.
+ncurses checks the size, and if it exceeds that due to the predefined data,
+continues to parse according to its own scheme.
+.PP
+First, it reads the extended header (5 short integers):
+.RS 5
+.TP 5
+(1)
+count of extended boolean capabilities
+.TP 5
+(2)
+count of extended numeric capabilities
+.TP 5
+(3)
+count of extended string capabilities
+.TP 5
+(4)
+size of the extended string table in bytes.
+.TP 5
+(5)
+last offset of the extended string table in bytes.
+.RE
.PP
+Using the counts and sizes, ncurses allocates arrays and reads data
+for the extended capabilties in the same order as the header information.
+.PP
+The extended string table contains values for string capabilities.
+After the end of these values, it contains the names for each of
+the extended capabilities in order, e.g., booleans, then numbers and
+finally strings.
+.
+.SH PORTABILITY
Note that it is possible for
.I setupterm
to expect a different set of capabilities
@@ -155,17 +222,17 @@ diverged from System V terminfo after SVr1, and have added extension
capabilities to the string table that (in the binary format) collide with
System V and XSI Curses extensions. See \fBterminfo\fR(\*n) for detailed
discussion of terminfo source compatibility issues.
-.PP
+.SH EXAMPLE
As an example, here is a hex dump of the description for the Lear-Siegler
ADM-3, a popular though rather stupid early terminal:
.nf
.sp
-adm3a|lsi adm3a,
- am,
- cols#80, lines#24,
- bel=^G, clear=\032$<1>, cr=^M, cub1=^H, cud1=^J,
- cuf1=^L, cup=\\E=%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K,
- home=^^, ind=^J,
+adm3a|lsi adm3a,
+ am,
+ cols#80, lines#24,
+ bel=^G, clear=\032$<1>, cr=^M, cub1=^H, cud1=^J,
+ cuf1=^L, cup=\\E=%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K,
+ home=^^, ind=^J,
.sp
.ft CW
\s-20000 1a 01 10 00 02 00 03 00 82 00 31 00 61 64 6d 33 ........ ..1.adm3
@@ -193,13 +260,21 @@ adm3a|lsi adm3a,
.ft R
.fi
.sp
-.PP
+.SH LIMITS
Some limitations: total compiled entries cannot exceed 4096 bytes.
The name field cannot exceed 128 bytes.
.SH FILES
\*d/*/* compiled terminal capability data base
.SH SEE ALSO
\fBcurses\fR(3X), \fBterminfo\fR(\*n).
+.SH AUTHORS
+Thomas E. Dickey
+.br
+extended terminfo format for ncurses 5.0
+.br
+hashed database support for ncurses 5.6
+.sp
+Eric S. Raymond
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/term.7 b/contrib/ncurses/man/term.7
index 5d51e92e6ed4..0a77cf694bd3 100644
--- a/contrib/ncurses/man/term.7
+++ b/contrib/ncurses/man/term.7
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998-2000,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2006 Free 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: term.7,v 1.13 2002/04/20 16:50:47 tom Exp $
+.\" $Id: term.7,v 1.15 2006/02/25 21:47:06 tom Exp $
.TH TERM 7
.ds n 5
.ds d @TERMINFO@
@@ -65,16 +65,16 @@ which you wish to override the system default type for your line.
.PP
Terminal type descriptions are stored as files of capability data underneath
\*d. To browse a list of all terminal names recognized by the system, do
-
+.sp
toe | more
-
+.sp
from your shell. These capability files are in a binary format optimized for
retrieval speed (unlike the old text-based \fBtermcap\fR format they replace);
to examine an entry, you must use the \fBinfocmp\fR(1) command. Invoke it as
follows:
-
+.sp
infocmp \fIentry-name\fR
-
+.sp
where \fIentry-name\fR is the name of the type you wish to examine (and the
name of its capability file the subdirectory of \*d named for its first
letter). This command dumps a capability file in the text format described by
@@ -96,7 +96,7 @@ terminals that also explains how to parse them:
First, choose a root name. The root will consist of a lower-case letter
followed by up to seven lower-case letters or digits. You need to avoid using
punctuation characters in root names, because they are used and interpreted as
-filenames and shell meta-characters (such as !, $, *, ? etc.) embedded in them
+filenames and shell meta-characters (such as !, $, *, ?, etc.) embedded in them
may cause odd and unhelpful behavior. The slash (/), or any other character
that may be interpreted by anyone's file system (\e, $, [, ]), is especially
dangerous (terminfo is platform-independent, and choosing names with special
@@ -136,29 +136,29 @@ with another that has this suffix and uses magic cookies to support multiple
attributes.
.TP 5
-am
-Enable auto-margin (right-margin wraparound)
+Enable auto-margin (right-margin wraparound).
.TP 5
-m
-Mono mode - suppress color support
+Mono mode - suppress color support.
.TP 5
-na
No arrow keys - termcap ignores arrow keys which are actually there on the
terminal, so the user can use the arrow keys locally.
.TP 5
-nam
-No auto-margin - suppress am capability
+No auto-margin - suppress am capability.
.TP 5
-nl
-No labels - suppress soft labels
+No labels - suppress soft labels.
.TP 5
-nsl
-No status line - suppress status line
+No status line - suppress status line.
.TP 5
-pp
Has a printer port which is used.
.TP 5
-rv
-Terminal in reverse video mode (black on white)
+Terminal in reverse video mode (black on white).
.TP 5
-s
Enable status line.
@@ -190,10 +190,10 @@ should be unique within the first 14 characters.
compiled terminal capability data base
.TP 5
/etc/inittab
-tty line initialization (AT&T-like UNIXes).
+tty line initialization (AT&T-like UNIXes)
.TP 5
/etc/ttys
-tty line initialization (BSD-like UNIXes).
+tty line initialization (BSD-like UNIXes)
.SH SEE ALSO
\fBcurses\fR(3X), \fBterminfo\fR(\*n), \fBterm\fR(\*n).
.\"#
diff --git a/contrib/ncurses/man/terminfo.head b/contrib/ncurses/man/terminfo.head
index 36945ff2502b..28006d3b68c7 100644
--- a/contrib/ncurses/man/terminfo.head
+++ b/contrib/ncurses/man/terminfo.head
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2004,2006 Free 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: terminfo.head,v 1.9 2000/08/13 01:56:40 tom Exp $
+.\" $Id: terminfo.head,v 1.13 2006/05/13 15:35:45 tom Exp $
.TH TERMINFO 5 "" "" "File Formats"
.ds n 5
.ds d @TERMINFO@
@@ -45,11 +45,13 @@ and libraries such as
describes terminals by giving a set of capabilities which they
have, by specifying how to perform screen operations, and by
specifying padding requirements and initialization sequences.
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.PP
Entries in
.I terminfo
consist of a sequence of `,' separated fields (embedded commas may be
-escaped with a backslash or notated as \e072).
+escaped with a backslash or notated as \e054).
White space after the `,' separator is ignored.
The first entry for each terminal gives the names which are known for the
terminal, separated by `|' characters.
@@ -59,6 +61,16 @@ and all others are understood as synonyms for the terminal name.
All names but the last should be in lower case and contain no blanks;
the last name may well contain upper case and blanks for readability.
.PP
+Lines beginning with a `#' in the first column are treated as comments.
+While comment lines are legal at any point, the output of \fIcaptoinfo\fP
+and \fIinfotocap\fP (aliases for \fItic\fP)
+will move comments so they occur only between entries.
+.PP
+Newlines and leading tabs may be used for formatting entries for readability.
+These are removed from parsed entries.
+The \fIinfocmp\ -f\fP option relies on this to format if-then-else expressions:
+the result can be read by \fItic\fP.
+.PP
Terminal names (except for the last, verbose entry) should
be chosen using the following conventions.
The particular piece of hardware making up the terminal should
diff --git a/contrib/ncurses/man/terminfo.tail b/contrib/ncurses/man/terminfo.tail
index bd585b1268e5..fa9a90d86654 100644
--- a/contrib/ncurses/man/terminfo.tail
+++ b/contrib/ncurses/man/terminfo.tail
@@ -1,9 +1,11 @@
-.\" $Id: terminfo.tail,v 1.35 2002/04/20 16:49:33 tom Exp $
+.\" $Id: terminfo.tail,v 1.44 2006/04/01 22:47:01 tom Exp $
.\" Beginning of terminfo.tail file
+.\" This file is part of ncurses.
+.\" See "terminfo.head" for copyright.
.ps +1
-.PP
+..
.SS A Sample Entry
-.PP
+..
The following entry, describing an ANSI-standard terminal, is representative
of what a \fBterminfo\fR entry for a modern terminal typically looks like.
.PP
@@ -271,22 +273,22 @@ Thus the model 33 teletype is described as
.DT
.nf
.ft CW
-.in -7
- \s-133\||\|tty33\||\|tty\||\|model 33 teletype,
+.\".in -2
+\s-133\||\|tty33\||\|tty\||\|model 33 teletype,
bel=^G, cols#72, cr=^M, cud1=^J, hc, ind=^J, os,\s+1
-.in +7
+.\".in +2
.ft R
.PP
-while the Lear Siegler \s-1ADM\-3\s0 is described as
+while the Lear Siegler \s-1ADM-3\s0 is described as
.PP
.DT
.nf
.ft CW
-.in -7
- \s-1adm3\||\|3\||\|lsi adm3,
+.\".in -2
+\s-1adm3\||\|3\||\|lsi adm3,
am, bel=^G, clear=^Z, cols#80, cr=^M, cub1=^H, cud1=^J,
ind=^J, lines#24,\s+1
-.in +7
+.\".in +2
.ft R
.fi
.PP
@@ -311,42 +313,93 @@ The parameter mechanism uses a stack and special \fB%\fP codes
to manipulate it.
Typically a sequence will push one of the
parameters onto the stack and then print it in some format.
-Often more complex operations are necessary.
+Print (e.g., "%d") is a special case.
+Other operations, including "%t" pop their operand from the stack.
+It is noted that more complex operations are often necessary,
+e.g., in the \fBsgr\fP string.
.PP
The \fB%\fR encodings have the following meanings:
.PP
-.DT
-.nf
-.ta .5i 1.5i
- \s-1%% outputs `%'
- %\fI[[\fP:\fI]flags][width[.precision]][\fPdoxXs\fI]\fP
- as in \fBprintf\fP, flags are [-+#] and space
- %c print pop() like %c in printf()
- %s print pop() like %s in printf()
-
- %p[1-9] push \fIi\fP'th parm
- %P[a-z] set dynamic variable [a-z] to pop()
- %g[a-z] get dynamic variable [a-z] and push it
- %P[A-Z] set static variable [a-z] to pop()
- %g[A-Z] get static variable [a-z] and push it
- %'\fIc\fP' char constant \fIc\fP
- %{\fInn\fP} integer constant \fInn\fP
- %l push strlen(pop)
-
- %+ %- %* %/ %m
- arithmetic (%m is mod): push(pop() op pop())
- %& %| %^ bit operations: push(pop() op pop())
- %= %> %< logical operations: push(pop() op pop())
- %A, %O logical and & or operations (for conditionals)
- %! %~ unary operations push(op pop())
- %i add 1 to first two parameters (for ANSI terminals)
-
- %? expr %t thenpart %e elsepart %;
- if-then-else, %e elsepart is optional.
- else-if's are possible a la Algol 68:
- %? c\d1\u %t b\d1\u %e c\d2\u %t b\d2\u %e c\d3\u %t b\d3\u %e c\d4\u %t b\d4\u %e %;
-\s+1 c\di\u are conditions, b\di\u are bodies.
-.fi
+.TP 5
+\s-1%%
+outputs `%'
+.TP
+%\fI[[\fP:\fI]flags][width[.precision]][\fPdoxXs\fI]\fP
+as in \fBprintf\fP, flags are [-+#] and space
+.TP
+%c
+print pop() like %c in \fBprintf\fP
+.TP
+%s
+print pop() like %s in \fBprintf\fP
+.TP
+%p[1-9]
+push \fIi\fP'th parameter
+.TP
+%P[a-z]
+set dynamic variable [a-z] to pop()
+.TP
+%g[a-z]
+get dynamic variable [a-z] and push it
+.TP
+%P[A-Z]
+set static variable [a-z] to pop()
+.TP
+%g[A-Z]
+get static variable [a-z] and push it
+.IP
+The terms "static" and "dynamic" are misleading.
+Historically, these are simply two different sets of variables,
+whose values are not reset between calls to \fBtparm\fP.
+However, that fact is not documented in other implementations.
+Relying on it will adversely impact portability to other implementations.
+.TP
+%'\fIc\fP'
+char constant \fIc\fP
+.TP
+%{\fInn\fP}
+integer constant \fInn\fP
+.TP
+%l
+push strlen(pop)
+.TP
+%+ %- %* %/ %m
+arithmetic (%m is mod): push(pop() op pop())
+.TP
+%& %| %^
+bit operations (AND, OR and exclusive-OR): push(pop() op pop())
+.TP
+%= %> %<
+logical operations: push(pop() op pop())
+.TP
+%A, %O
+logical AND and OR operations (for conditionals)
+.TP
+%! %~
+unary operations (logical and bit complement): push(op pop())
+.TP
+%i
+add 1 to first two parameters (for ANSI terminals)
+.TP
+%? \fIexpr\fP %t \fIthenpart\fP %e \fIelsepart\fP %;
+This forms an if-then-else.
+The %e \fIelsepart\fP is optional.
+Usually the %? \fIexpr\fP part pushes a value onto the stack,
+and %t pops it from the stack, testing if it is nonzero (true).
+If it is zero (false), control passes to the %e (else) part.
+.IP
+It is possible to form else-if's a la Algol 68:
+.RS
+%? c\d1\u %t b\d1\u %e c\d2\u %t b\d2\u %e c\d3\u %t b\d3\u %e c\d4\u %t b\d4\u %e %;
+.RE
+.IP
+where c\di\u are conditions, b\di\u are bodies.
+.IP
+Use the \fB-f\fP option of \fBtic\fP or \fBinfocmp\fP to see
+the structure of if-the-else's.
+Some strings, e.g., \fBsgr\fP can be very complicated when written
+on one line.
+The \fB-f\fP option splits the string into lines with the parts indented.
.PP
Binary operations are in postfix form with the operands in the usual order.
That is, to get x-5 one would use "%gx%{5}%-".
@@ -762,6 +815,12 @@ Putting this all together into the sgr sequence gives:
.fi
.PP
Remember that if you specify sgr, you must also specify sgr0.
+Also, some implementations rely on sgr being given if sgr0 is,
+Not all terminfo entries necessarily have an sgr string, however.
+Many terminfo entries are derived from termcap entries
+which have no sgr string.
+The only drawback to adding an sgr string is that termcap also
+assumes that sgr0 does not exit alternate character set mode.
.PP
Terminals with the ``magic cookie'' glitch
.RB ( xmc )
@@ -937,25 +996,33 @@ option of the
.IR tput
program, each time the user logs in.
They will be printed in the following order:
+.RS
+.TP
run the program
-.BR iprog ;
+.BR iprog
+.TP
output
-.BR is1 ;
-.BR is2 ;
+.BR is1
+.BR is2
+.TP
set the margins using
.BR mgc ,
.BR smgl
and
-.BR smgr ;
+.BR smgr
+.TP
set tabs using
.B tbc
and
-.BR hts ;
+.BR hts
+.TP
print the file
-.BR if ;
+.BR if
+.TP
and finally
output
.BR is3 .
+.RE
.PP
Most initialization is done with
.BR is2 .
@@ -966,17 +1033,21 @@ and special cases in
.B is1
and
.BR is3 .
-A pair of sequences that does a harder reset from a totally unknown state
-can be analogously given as
+.PP
+A set of sequences that does a harder reset from a totally unknown state
+can be given as
.BR rs1 ,
.BR rs2 ,
-.BR rf ,
+.BR rf
and
.BR rs3 ,
analogous to
-.B is2
+.B is1 ,
+.B is2 ,
+.B if
and
-.BR if .
+.BR is3
+respectively.
These strings are output by the
.IR reset
program, which is used when the terminal gets into a wedged state.
@@ -994,6 +1065,28 @@ normally be part of
but it causes an annoying glitch of the screen and is not normally
needed since the terminal is usually already in 80 column mode.
.PP
+The
+.IR reset
+program writes strings
+including
+.BR iprog ,
+etc., in the same order as the
+.IR init
+program, using
+.BR rs1 ,
+etc., instead of
+.BR is1 ,
+etc.
+If any of
+.BR rs1 ,
+.BR rs2 ,
+.BR rs3 ,
+or
+.BR rf
+reset capability strings are missing, the
+.IR reset
+program falls back upon the corresponding initialization capability string.
+.PP
If there are commands to set and clear tab stops, they can be given as
.B tbc
(clear all tab stops)
@@ -1007,7 +1100,7 @@ or
.BR if .
.SS Delays and Padding
.PP
-Many older and slower terminals don't support either XON/XOFF or DTR
+Many older and slower terminals do not support either XON/XOFF or DTR
handshaking, including hard copy terminals and some very archaic CRTs
(including, for example, DEC VT100s).
These may require padding characters
@@ -1019,7 +1112,7 @@ close to full), set
.BR xon .
This capability suppresses the emission of padding.
You can also set it
-for memory-mapped console devices effectively that don't have a speed limit.
+for memory-mapped console devices effectively that do not have a speed limit.
Padding information should still be included so that routines can
make better decisions about relative costs, but actual pad characters will
not be transmitted.
@@ -1170,7 +1263,7 @@ defined."
.PP
The \fBsetaf\fR/\fBsetab\fR and \fBsetf\fR/\fBsetb\fR capabilities take a
single numeric argument each.
-Argument values 0-7 are portably defined as
+Argument values 0-7 of \fBsetaf\fR/\fBsetab\fR are portably defined as
follows (the middle column is the symbolic #define available in the header for
the \fBcurses\fR or \fBncurses\fR libraries).
The terminal hardware is free to
@@ -1192,6 +1285,25 @@ cyan \fBCOLOR_CYAN\fR 6 0,max,max
white \fBCOLOR_WHITE\fR 7 max,max,max
.TE
.PP
+The argument values of \fBsetf\fR/\fBsetb\fR historically correspond to
+a different mapping, i.e.,
+.TS H
+center;
+l c c c
+l l n l.
+\fBColor #define Value RGB\fR
+black \fBCOLOR_BLACK\fR 0 0, 0, 0
+blue \fBCOLOR_BLUE\fR 1 0,0,max
+green \fBCOLOR_GREEN\fR 2 0,max,0
+cyan \fBCOLOR_CYAN\fR 3 0,max,max
+red \fBCOLOR_RED\ \fR 4 max,0,0
+magenta \fBCOLOR_MAGENTA\fR 5 max,0,max
+yellow \fBCOLOR_YELLOW\fR 6 max,max,0
+white \fBCOLOR_WHITE\fR 7 max,max,max
+.TE
+It is important to not confuse the two sets of color capabilities;
+otherwise red/blue will be interchanged on the display.
+.PP
On an HP-like terminal, use \fBscp\fR with a color-pair number parameter to set
which color pair is current.
.PP
@@ -1421,39 +1533,39 @@ user preferences.
.SS Pitfalls of Long Entries
.PP
Long terminfo entries are unlikely to be a problem; to date, no entry has even
-approached terminfo's 4K string-table maximum.
+approached terminfo's 4096-byte string-table maximum.
Unfortunately, the termcap
-translations are much more strictly limited (to 1K), thus termcap translations
+translations are much more strictly limited (to 1023 bytes), thus termcap translations
of long terminfo entries can cause problems.
.PP
-The man pages for 4.3BSD and older versions of tgetent() instruct the user to
-allocate a 1K buffer for the termcap entry.
+The man pages for 4.3BSD and older versions of \fBtgetent()\fP instruct the user to
+allocate a 1024-byte buffer for the termcap entry.
The entry gets null-terminated by
the termcap library, so that makes the maximum safe length for a termcap entry
1k-1 (1023) bytes.
Depending on what the application and the termcap library
-being used does, and where in the termcap file the terminal type that tgetent()
+being used does, and where in the termcap file the terminal type that \fBtgetent()\fP
is searching for is, several bad things can happen.
.PP
Some termcap libraries print a warning message or exit if they find an
-entry that's longer than 1023 bytes; others don't; others truncate the
+entry that's longer than 1023 bytes; others do not; others truncate the
entries to 1023 bytes.
Some application programs allocate more than
-the recommended 1K for the termcap entry; others don't.
+the recommended 1K for the termcap entry; others do not.
.PP
Each termcap entry has two important sizes associated with it: before
"tc" expansion, and after "tc" expansion.
"tc" is the capability that
tacks on another termcap entry to the end of the current one, to add
on its capabilities.
-If a termcap entry doesn't use the "tc"
+If a termcap entry does not use the "tc"
capability, then of course the two lengths are the same.
.PP
The "before tc expansion" length is the most important one, because it
affects more than just users of that particular terminal.
This is the
length of the entry as it exists in /etc/termcap, minus the
-backslash-newline pairs, which tgetent() strips out while reading it.
+backslash-newline pairs, which \fBtgetent()\fP strips out while reading it.
Some termcap libraries strip off the final newline, too (GNU termcap does not).
Now suppose:
.TP 5
@@ -1469,12 +1581,12 @@ the whole entry into the buffer, no matter what its length, to see
if it's the entry it wants,
.TP 5
*
-and tgetent() is searching for a terminal type that either is the
+and \fBtgetent()\fP is searching for a terminal type that either is the
long entry, appears in the termcap file after the long entry, or
-doesn't appear in the file at all (so that tgetent() has to search
+does not appear in the file at all (so that \fBtgetent()\fP has to search
the whole termcap file).
.PP
-Then tgetent() will overwrite memory, perhaps its stack, and probably core dump
+Then \fBtgetent()\fP will overwrite memory, perhaps its stack, and probably core dump
the program.
Programs like telnet are particularly vulnerable; modern telnets
pass along values like the terminal type automatically.
@@ -1487,7 +1599,7 @@ here but will return incorrect data for the terminal.
.PP
The "after tc expansion" length will have a similar effect to the
above, but only for people who actually set TERM to that terminal
-type, since tgetent() only does "tc" expansion once it's found the
+type, since \fBtgetent()\fP only does "tc" expansion once it's found the
terminal type it was looking for, not while searching.
.PP
In summary, a termcap entry that is longer than 1023 bytes can cause,
@@ -1511,12 +1623,12 @@ of terminfo (under HP-UX and AIX) which diverged from System V terminfo after
SVr1, and have added extension capabilities to the string table that (in the
binary format) collide with System V and XSI Curses extensions.
.SH EXTENSIONS
-Some SVr4 \fBcurses\fR implementations, and all previous to SVr4, don't
+Some SVr4 \fBcurses\fR implementations, and all previous to SVr4, do not
interpret the %A and %O operators in parameter strings.
.PP
SVr4/XPG4 do not specify whether \fBmsgr\fR licenses movement while in
an alternate-character-set mode (such modes may, among other things, map
-CR and NL to characters that don't trigger local motions).
+CR and NL to characters that do not trigger local motions).
The \fBncurses\fR implementation ignores \fBmsgr\fR in \fBALTCHARSET\fR
mode.
This raises the possibility that an XPG4
@@ -1573,7 +1685,11 @@ Supports both the SVr4 set and the AIX extensions.
\*d/?/*
files containing terminal descriptions
.SH SEE ALSO
-\fBtic\fR(1M), \fBcurses\fR(3X), \fBprintf\fR(3S), \fBterm\fR(\*n).
+\fB@TIC@\fR(1M),
+\fB@INFOCMP@\fR(1M),
+\fBcurses\fR(3X),
+\fBprintf\fR(3S),
+\fBterm\fR(\*n).
.SH AUTHORS
Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
Based on pcurses by Pavel Curtis.
diff --git a/contrib/ncurses/man/tic.1m b/contrib/ncurses/man/tic.1m
index e3a095453d3c..f13e0fd31f6c 100644
--- a/contrib/ncurses/man/tic.1m
+++ b/contrib/ncurses/man/tic.1m
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,1999,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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: tic.1m,v 1.29 2000/08/19 18:51:05 tom Exp $
+.\" $Id: tic.1m,v 1.43 2006/05/13 15:14:01 tom Exp $
.TH tic 1M ""
.ds n 5
.ds d @TERMINFO@
@@ -34,23 +34,28 @@
\fBtic\fR - the \fIterminfo\fR entry-description compiler
.SH SYNOPSIS
\fBtic\fR
-[\fB\-\
+[\fB-\
1\
C\
+G\
I\
+L\
N\
-R\
T\
+U\
V\
a\
c\
f\
+g\
r\
s\
+t\
x\
\fR]
[\fB-e\fR \fInames\fR]
[\fB-o\fR \fIdir\fR]
+[\fB-R\fR \fIsubset\fR]
[\fB-v\fR[\fIn\fR]]
[\fB-w\fR[\fIn\fR]]
\fIfile\fR
@@ -74,11 +79,23 @@ Libraries that read terminfo entries are expected to check for a TERMINFO
directory first, look at \fI$HOME/.terminfo\fR if TERMINFO is not set, and
finally look in \fI\*d\fR.
.TP
+\fB-1\fR
+restricts the output to a single column
+.TP
\fB-a\fR
tells \fBtic\fP to retain commented-out capabilities rather than discarding
them. Capabilities are commented by prefixing them with a period.
This sets the \fB-x\fR option, because it treats the commented-out
entries as user-defined names.
+If the source is termcap, accept the 2-character names required by version 6.
+Otherwise these are ignored.
+.TP
+\fB-C\fR
+Force source translation to termcap format. Note: this differs from the \fB-C\fR
+option of \fIinfocmp\fR(1M) in that it does not merely translate capability
+names, but also translates terminfo strings to termcap format. Capabilities
+that are not translatable are left in the entry under their terminfo names
+but commented out with two preceding dots.
.TP
\fB-c\fR
tells \fBtic\fP to only check \fIfile\fR for errors, including syntax problems and
@@ -88,35 +105,28 @@ will print warnings about entries which, after use resolution, are more than
libraries (and a documented limit in terminfo), these entries may cause core
dumps.
.TP
-\fB-v\fR\fIn\fR
-specifies that (verbose) output be written to standard error trace
-information showing \fBtic\fR's progress. The optional integer
-\fIn\fR is a number from 1 to 10, inclusive, indicating the desired
-level of detail of information. If \fIn\fR is omitted, the default
-level is 1. If \fIn\fR is specified and greater than 1, the level of
-detail is increased.
-.TP
-\fB-o\fR\fIdir\fR
-Write compiled entries to given directory. Overrides the TERMINFO environment
-variable.
-.TP
-\fB-w\fR\fIn\fR
-specifies the width of the output.
-.TP
-\fB-1\fR
-restricts the output to a single column
+\fB-e \fR\fInames\fR
+Limit writes and translations to the following comma-separated list of
+terminals.
+If any name or alias of a terminal matches one of the names in
+the list, the entry will be written or translated as normal.
+Otherwise no output will be generated for it.
+The option value is interpreted as a file containing the list if it
+contains a '/'.
+(Note: depending on how tic was compiled, this option may require \fB-I\fR or \fB-C\fR.)
.TP
-\fB-C\fR
-Force source translation to termcap format. Note: this differs from the -C
-option of \fIinfocmp\fR(1M) in that it does not merely translate capability
-names, but also translates terminfo strings to termcap format. Capabilities
-that are not translatable are left in the entry under their terminfo names
-but commented out with two preceding dots.
+\fB-f\fR
+Display complex terminfo strings which contain if/then/else/endif expressions
+indented for readability.
.TP
\fB-G\fR
Display constant literals in decimal form
rather than their character equivalents.
.TP
+\fB-g\fR
+Display constant character literals in quoted form
+rather than their decimal equivalents.
+.TP
\fB-I\fR
Force source translation to terminfo format.
.TP
@@ -125,10 +135,10 @@ Force source translation to terminfo format
using the long C variable names listed in <\fBterm.h\fR>
.TP
\fB-N\fR
-Disable smart defaults.
-Normally, when translating from termcap to terminfo, the compiler makes
+Disable smart defaults.
+Normally, when translating from termcap to terminfo, the compiler makes
a number of assumptions about the defaults of string capabilities
-\fBreset1_string\fR, \fBcarriage_return\fR, \fBcursor_left\fR,
+\fBreset1_string\fR, \fBcarriage_return\fR, \fBcursor_left\fR,
\fBcursor_down\fR, \fBscroll_forward\fR, \fBtab\fR, \fBnewline\fR,
\fBkey_backspace\fR, \fBkey_left\fR, and \fBkey_down\fR, then attempts
to use obsolete termcap capabilities to deduce correct values. It also
@@ -136,55 +146,67 @@ normally suppresses output of obsolete termcap capabilities such as \fBbs\fR.
This option forces a more literal translation that also preserves the
obsolete capabilities.
.TP
+\fB-o\fR\fIdir\fR
+Write compiled entries to given directory. Overrides the TERMINFO environment
+variable.
+.TP
\fB-R\fR\fIsubset\fR
Restrict output to a given subset. This option is for use with archaic
-versions of terminfo like those on SVr1, Ultrix, or HP/UX that don't support
+versions of terminfo like those on SVr1, Ultrix, or HP/UX that do not support
the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX 3.x
that have their own extensions incompatible with SVr4/XSI. Available subsets
are "SVr1", "Ultrix", "HP", "BSD" and "AIX"; see \fBterminfo\fR(\*n) for details.
.TP
+\fB-r\fR
+Force entry resolution (so there are no remaining tc capabilities) even
+when doing translation to termcap format. This may be needed if you are
+preparing a termcap file for a termcap library (such as GNU termcap through
+version 1.3 or BSD termcap through 4.3BSD) that does not handle multiple
+tc capabilities per entry.
+.TP
+\fB-s\fR
+Summarize the compile by showing the directory into which entries
+are written, and the number of entries which are compiled.
+.TP
\fB-T\fR
eliminates size-restrictions on the generated text.
This is mainly useful for testing and analysis, since the compiled
descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
.TP
+\fB-t\fR
+tells \fBtic\fP to discard commented-out capabilities.
+Normally when translating from terminfo to termcap,
+untranslatable capabilities are commented-out.
+.TP 5
+\fB-U\fR
+tells \fBtic\fP to not post-process the data after parsing the source file.
+Normally, it infers data which is commonly missing in older terminfo data,
+or in termcaps.
+.TP
\fB-V\fR
reports the version of ncurses which was used in this program, and exits.
.TP
-\fB-r\fR
-Force entry resolution (so there are no remaining tc capabilities) even
-when doing translation to termcap format. This may be needed if you are
-preparing a termcap file for a termcap library (such as GNU termcap up
-to version 1.3 or BSD termcap up to 4.3BSD) that doesn't handle multiple
-tc capabilities per entry.
-.TP
-\fB-e\fR
-Limit writes and translations to the following comma-separated list of
-terminals.
-If any name or alias of a terminal matches one of the names in
-the list, the entry will be written or translated as normal.
-Otherwise no output will be generated for it.
-The option value is interpreted as a file containing the list if it
-contains a '/'.
-(Note: depending on how tic was compiled, this option may require -I or -C.)
-.TP
-\fB-f\fR
-Display complex terminfo strings which contain if/then/else/endif expressions
-indented for readability.
-.TP
-\fB-g\fR
-Display constant character literals in quoted form
-rather than their decimal equivalents.
+\fB-v\fR\fIn\fR
+specifies that (verbose) output be written to standard error trace
+information showing \fBtic\fR's progress.
+The optional parameter \fIn\fR is a number from 1 to 10, inclusive,
+indicating the desired level of detail of information.
+If \fIn\fR is omitted, the default level is 1.
+If \fIn\fR is specified and greater than 1, the level of
+detail is increased.
.TP
-\fB-s\fR
-Summarize the compile by showing the directory into which entries
-are written, and the number of entries which are compiled.
+\fB-w\fR\fIn\fR
+specifies the width of the output.
+The parameter is optional.
+If it is omitted, it defaults to 60.
.TP
\fB-x\fR
Treat unknown capabilities as user-defined.
That is, if you supply a capability name which \fBtic\fP does not recognize,
it will infer its type (boolean, number or string) from the syntax and
make an extended table entry for that.
+User-defined capability strings
+whose name begins with ``k'' are treated as function keys.
.TP
\fIfile\fR
contains one or more \fBterminfo\fR terminal descriptions in source
@@ -214,11 +236,11 @@ List of tokens encountered by scanner
9
All values computed in construction of the hash table
.LP
-If n is not given, it is taken to be one.
+If the debug level \fIn\fR is not given, it is taken to be one.
.PP
All but one of the capabilities recognized by \fBtic\fR are documented
in \fBterminfo\fR(\*n). The exception is the \fBuse\fR capability.
-
+.PP
When a \fBuse\fR=\fIentry\fR-\fIname\fR field is discovered in a
terminal entry currently being compiled, \fBtic\fR reads in the binary
from \fB\*d\fR to complete the entry. (Entries created from
@@ -227,16 +249,16 @@ from \fB\*d\fR to complete the entry. (Entries created from
\fB\*d\fR.) \fBtic\fR duplicates the capabilities in
\fIentry\fR-\fIname\fR for the current entry, with the exception of
those capabilities that explicitly are defined in the current entry.
-
+.PP
When an entry, e.g., \fBentry_name_1\fR, contains a
\fBuse=\fR\fIentry\fR_\fIname\fR_\fI2\fR field, any canceled
capabilities in \fIentry\fR_\fIname\fR_\fI2\fR must also appear in
\fBentry_name_1\fR before \fBuse=\fR for these capabilities to be
canceled in \fBentry_name_1\fR.
-
+.PP
If the environment variable \fBTERMINFO\fR is set, the compiled
results are placed there instead of \fB\*d\fR.
-
+.PP
Total compiled entries cannot exceed 4096 bytes. The name field cannot
exceed 512 bytes. Terminal names exceeding the maximum alias length
(32 characters on systems with long filenames, 14 characters otherwise)
@@ -252,7 +274,7 @@ Unlike the stock SVr4 \fBtic\fR command, this implementation can actually
compile termcap sources. In fact, entries in terminfo and termcap syntax can
be mixed in a single source file. See \fBterminfo\fR(\*n) for the list of
termcap names taken to be equivalent to terminfo names.
-
+.PP
The SVr4 manual pages are not clear on the resolution rules for \fBuse\fR
capabilities.
This implementation of \fBtic\fR will find \fBuse\fR targets anywhere
@@ -260,10 +282,10 @@ in the source file, or anywhere in the file tree rooted at \fBTERMINFO\fR (if
\fBTERMINFO\fR is defined), or in the user's \fI$HOME/.terminfo\fR directory
(if it exists), or (finally) anywhere in the system's file tree of
compiled entries.
-
+.PP
The error messages from this \fBtic\fR have the same format as GNU C
error messages, and can be parsed by GNU Emacs's compile facility.
-
+.PP
The
\fB-C\fR,
\fB-G\fR,
@@ -278,12 +300,13 @@ The
\fB-g\fR,
\fB-o\fR,
\fB-r\fR,
-\fB-s\fR and
+\fB-s\fR,
+\fB-t\fR and
\fB-x\fR
options
are not supported under SVr4.
-The SVr4 -c mode does not report bad use links.
-
+The SVr4 \fB-c\fR mode does not report bad use links.
+.PP
System V does not compile entries to or read entries from your
\fI$HOME/.terminfo\fR directory unless TERMINFO is explicitly set to it.
.SH FILES
@@ -291,8 +314,15 @@ System V does not compile entries to or read entries from your
\fB\*d/?/*\fR
Compiled terminal description database.
.SH SEE ALSO
-\fB@INFOCMP@\fR(1M), \fB@CAPTOINFO@\fR(1M), \fB@INFOTOCAP@\fR(1M),
-\fB@TOE@\fR(1M), \fBcurses\fR(3X), \fBterminfo\fR(\*n).
+\fB@INFOCMP@\fR(1M),
+\fB@CAPTOINFO@\fR(1M),
+\fB@INFOTOCAP@\fR(1M),
+\fB@TOE@\fR(1M),
+\fBcurses\fR(3X),
+\fBterminfo\fR(\*n).
+.PP
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/toe.1m b/contrib/ncurses/man/toe.1m
index 399cf614f3f3..1419674b3958 100644
--- a/contrib/ncurses/man/toe.1m
+++ b/contrib/ncurses/man/toe.1m
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2004,2006 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
@@ -26,25 +26,29 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: toe.1m,v 1.10 2000/08/19 18:51:05 tom Exp $
+.\" $Id: toe.1m,v 1.18 2006/05/13 15:14:01 tom Exp $
.TH toe 1M ""
.ds n 5
.ds d @TERMINFO@
.SH NAME
\fBtoe\fR - table of (terminfo) entries
.SH SYNOPSIS
-\fBtoe\fR [\fB-v\fR[\fIn\fR]] [\fB-huUV\fR] \fIfile...\fR
+\fBtoe\fR [\fB-v\fR[\fIn\fR]] [\fB-ahuUV\fR] \fIfile...\fR
.br
.SH DESCRIPTION
.PP
With no options, \fBtoe\fR lists all available terminal types by primary name
with descriptions. File arguments specify the directories to be scanned; if no
such arguments are given, your default terminfo directory is scanned. If you
-also specify the -h option, a directory header will be issued as each
-directory is entered.
+also specify the \fB-h\fR option, a directory header will be issued as each
+directory is entered.
.PP
There are other options intended for use by terminfo file maintainers:
.TP
+\fB-a\fR
+report on all of the terminal databases which ncurses would search,
+rather than only the first one that it finds.
+.TP
\fB-u\fR \fIfile\fR
says to issue a report on dependencies in the given file. This report condenses
the `use' relation: each line consists of the primary name of a terminal that
@@ -60,10 +64,11 @@ whitespace-separated primary names of all terminals which depend on it,
followed by a newline.
.TP
\fB-v\fR\fIn\fR
-specifies that (verbose) output be written to standard error trace
-information showing \fBtoe\fR's progress. The optional integer
-\fIn\fR is a number from 1 to 10, interpreted as for \fBtic\fR(1).
-.TP 5
+specifies that (verbose) output be written to standard error,
+showing \fBtoe\fR's progress.
+The optional parameter \fIn\fR is a number from 1 to 10,
+interpreted as for \fBtic\fR(1).
+.TP
\fB-V\fR
reports the version of ncurses which was used in this program, and exits.
.SH FILES
@@ -71,8 +76,15 @@ reports the version of ncurses which was used in this program, and exits.
\fB\*d/?/*\fR
Compiled terminal description database.
.SH SEE ALSO
-\fB@TIC@\fR(1M), \fB@INFOCMP@\fR(1M), \fB@CAPTOINFO@\fR(1M),
-\fB@INFOTOCAP@\fR(1M), \fBcurses\fR(3X), \fBterminfo\fR(\*n).
+\fB@TIC@\fR(1M),
+\fB@INFOCMP@\fR(1M),
+\fB@CAPTOINFO@\fR(1M),
+\fB@INFOTOCAP@\fR(1M),
+\fBcurses\fR(3X),
+\fBterminfo\fR(\*n).
+.PP
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/tput.1 b/contrib/ncurses/man/tput.1
index 898df1e606f5..4de0b73a3a82 100644
--- a/contrib/ncurses/man/tput.1
+++ b/contrib/ncurses/man/tput.1
@@ -1,6 +1,6 @@
'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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: tput.1,v 1.16 2000/09/09 20:43:33 tom Exp $
+.\" $Id: tput.1,v 1.25 2006/05/13 15:14:01 tom Exp $
.TH tput 1 ""
.ds d @TERMINFO@
-.ds n 5
+.ds n 1
.SH NAME
\fBtput\fR, \fBreset\fR - initialize a terminal or query terminfo database
.SH SYNOPSIS
@@ -50,14 +50,28 @@
The \fBtput\fR utility uses the \fBterminfo\fR database to make the
values of terminal-dependent capabilities and information available to
the shell (see \fBsh\fR(1)), to initialize or reset the terminal, or
-return the long name of the requested terminal type. \fBtput\fR
-outputs a string if the attribute (\fIcap\fRability \fIname\fR) is of
-type string, or an integer if the attribute is of type integer. If
-the attribute is of type boolean, \fBtput\fR simply sets the exit code
-(\fB0\fR for TRUE if the terminal has the capability, \fB1\fR for
-FALSE if it does not), and produces no output. Before using a value
-returned on standard output, the user should test the exit code
-[\fB$?\fR, see \fBsh\fR(1)] to be sure it is \fB0\fR.
+return the long name of the requested terminal type.
+The result depends upon the capability's type:
+.RS
+.TP 5
+string
+\fBtput\fR writes the string to the standard output.
+No trailing newline is supplied.
+.TP
+integer
+\fBtput\fR writes the decimal value to the standard output,
+with a trailing newline.
+.TP
+boolean
+\fBtput\fR simply sets the exit code
+(\fB0\fR for TRUE if the terminal has the capability,
+\fB1\fR for FALSE if it does not),
+and writes nothing to the standard output.
+.RE
+.PP
+Before using a value returned on the standard output,
+the application should test the exit code
+(e.g., \fB$?\fR, see \fBsh\fR(1)) to be sure it is \fB0\fR.
(See the \fBEXIT CODES\fR and \fBDIAGNOSTICS\fR sections.)
For a complete list of capabilities
and the \fIcapname\fR associated with each, see \fBterminfo\fR(\*n).
@@ -70,22 +84,33 @@ variables \fBLINES\fR and \fBCOLUMNS\fR will be ignored,and the
operating system will not be queried for the actual screen size.
.TP
\fIcapname\fR
-indicates the attribute from the \fBterminfo\fR database. When
+indicates the capability from the \fBterminfo\fR database. When
\fBtermcap\fR support is compiled in, the \fBtermcap\fR name for
-the attribute is also accepted.
+the capability is also accepted.
.TP
\fIparms\fR
-If the attribute is a string that takes parameters, the arguments
-\fIparms\fR will be instantiated into the string. An all numeric
-argument will be passed to the attribute as a number.
+If the capability is a string that takes parameters, the arguments
+\fIparms\fR will be instantiated into the string.
+.IP
+Most parameters are numbers.
+Only a few terminfo capabilities require string parameters;
+\fBtput\fR uses a table to decide which to pass as strings.
+Normally \fBtput\fR uses \fBtparm\fR (3X) to perform the substitution.
+If no parameters are given for the capability,
+\fBtput\fR writes the string without performing the substitution.
.TP
\fB-S\fR
allows more than one capability per invocation of \fBtput\fR. The
capabilities must be passed to \fBtput\fR from the standard input
-instead of from the command line (see example). Only one
-\fIcapname\fR is allowed per line. The \fB-S\fR option changes the
+instead of from the command line (see example).
+Only one \fIcapname\fR is allowed per line.
+The \fB-S\fR option changes the
meaning of the \fB0\fR and \fB1\fR boolean and string exit codes (see the
EXIT CODES section).
+.IP
+Again, \fBtput\fR uses a table and the presence of parameters in its input
+to decide whether to use \fBtparm\fR (3X),
+and how to interpret the parameters.
.TP
\fB-V\fR
reports the version of ncurses which was used in this program, and exits.
@@ -93,12 +118,28 @@ reports the version of ncurses which was used in this program, and exits.
\fBinit\fR
If the \fBterminfo\fR database is present and an entry for the user's
terminal exists (see \fB-T\fR\fItype\fR, above), the following will
-occur: (1) if present, the terminal's initialization strings will be
-output (\fBis1\fR, \fBis2\fR, \fBis3\fR, \fBif\fR, \fBiprog\fR), (2)
-any delays (e.g., newline) specified in the entry will be set in the
-tty driver, (3) tabs expansion will be turned on or off according to
-the specification in the entry, and (4) if tabs are not expanded,
-standard tabs will be set (every 8 spaces). If an entry does not
+occur:
+.RS
+.TP
+(1)
+if present, the terminal's initialization strings will be
+output as detailed in the \fBterminfo\fR(5) section on
+.IR "Tabs and Initialization" ,
+.TP
+(2)
+any delays (e.g., newline) specified in the entry will
+be set in the tty driver,
+.TP
+(3)
+tabs expansion will be turned on or off according to
+the specification in the entry, and
+.TP
+(4)
+if tabs are not expanded,
+standard tabs will be set (every 8 spaces).
+.RE
+.IP
+If an entry does not
contain the information needed for any of the four above activities,
that activity will silently be skipped.
.TP
@@ -126,7 +167,7 @@ Initialize the terminal according to the type of
terminal in the environmental variable \fBTERM\fR. This
command should be included in everyone's .profile after
the environmental variable \fBTERM\fR has been exported, as
-illustrated on the \fBprofile\fR(4) manual page.
+illustrated on the \fBprofile\fR(5) manual page.
.TP 5
\fBtput -T5620 reset\fR
Reset an AT&T 5620 terminal, overriding the type of
@@ -158,6 +199,9 @@ Set exit code to indicate if the current terminal is a hard copy terminal.
\fBtput cup 23 4\fR
Send the sequence to move the cursor to row 23, column 4.
.TP 5
+\fBtput cup\fR
+Send the terminfo string for cursor-movement, with no parameters substituted.
+.TP 5
\fBtput longname\fR
Print the long name from the \fBterminfo\fR database for the
type of terminal specified in the environmental
@@ -176,59 +220,65 @@ variable \fBTERM\fR.
.RE
.TP 5
\&
-This example shows tput processing several capabilities in one
-invocation. This example clears the screen, moves the cursor to
-position 10, 10 and turns on bold (extra bright) mode. The list is
-terminated by an exclamation mark (\fB!\fR) on a line by itself.
+This example shows \fBtput\fR processing several capabilities in one invocation.
+It clears the screen,
+moves the cursor to position 10, 10
+and turns on bold (extra bright) mode.
+The list is terminated by an exclamation mark (\fB!\fR) on a line by itself.
.SH FILES
.TP
\fB\*d\fR
compiled terminal description database
.TP
-\fB/usr/include/curses.h\fR
-\fBcurses\fR(3X) header file
-.TP
-\fB/usr/include/term.h\fR
-\fBterminfo\fR header file
-.TP
\fB@DATADIR@/tabset/*\fR
tab settings for some terminals, in a format
appropriate to be output to the terminal (escape
sequences that set margins and tabs); for more
information, see the "Tabs and Initialization"
-section of \fBterminfo\fR(4)
-.SH SEE ALSO
-\fB@CLEAR@\fR(1), \fBstty\fR(1), \fBtabs\fR(\*n). \fBprofile\fR(\*n),
-\fBterminfo\fR(4) in the \fISystem\fR \fIAdministrator\fR'\fIs\fR
-\fIReference\fR \fIManual\fR. Chapter 10 of the
-\fIProgrammer\fR'\fIs\fR \fIGuide\fR.
+section of \fBterminfo\fR(5)
.SH EXIT CODES
-If \fIcapname\fR is of type boolean, a value of \fB0\fR is set for
-TRUE and \fB1\fR for FALSE unless the \fB-S\fR option is used.
-.PP
-If \fIcapname\fR is of type string, a value of \fB0\fR is set if the
-\fIcapname\fR is defined for this terminal \fItype\fR (the value of
-\fIcapname\fR is returned on standard output); a value of \fB1\fR is
-set if \fIcapname\fR is not defined for this terminal \fItype\fR (a
-null value is returned on standard output).
-.PP
-If \fIcapname\fR is of type boolean or string and the \fB-S\fR option
-is used, a value of \fB0\fR is returned to indicate that all lines
-were successful. No indication of which line failed can be given so
+If the \fB-S\fR option is used,
+\fBtput\fR checks for errors from each line,
+and if any errors are found, will set the exit code to 4 plus the
+number of lines with errors.
+If no errors are found, the exit code is \fB0\fR.
+No indication of which line failed can be given so
exit code \fB1\fR will never appear. Exit codes \fB2\fR, \fB3\fR, and
\fB4\fR retain their usual interpretation.
-.PP
-If \fIcapname\fR is of type integer, a value of \fB0\fR is always set,
+If the \fB-S\fR option is not used,
+the exit code depends on the type of \fIcapname\fR:
+.RS 5
+.TP
+.I boolean
+a value of \fB0\fR is set for TRUE and \fB1\fR for FALSE.
+.TP
+.I string
+a value of \fB0\fR is set if the
+\fIcapname\fR is defined for this terminal \fItype\fR (the value of
+\fIcapname\fR is returned on standard output);
+a value of \fB1\fR is set if \fIcapname\fR
+is not defined for this terminal \fItype\fR
+(nothing is written to standard output).
+.TP
+.I integer
+a value of \fB0\fR is always set,
whether or not \fIcapname\fR is defined for this terminal \fItype\fR.
To determine if \fIcapname\fR is defined for this terminal \fItype\fR,
-the user must test the value of standard output. A value of \fB-1\fR
+the user must test the value written to standard output.
+A value of \fB-1\fR
means that \fIcapname\fR is not defined for this terminal \fItype\fR.
+.TP
+.I other
+\fBreset\fR or \fBinit\fR may fail to find their respective files.
+In that case, the exit code is set to 4 + \fBerrno\fR.
+.RE
.PP
Any other exit code indicates an error; see the DIAGNOSTICS section.
.SH DIAGNOSTICS
\fBtput\fR prints the following error messages and sets the corresponding exit
codes.
.PP
+.ne 15
.TS
l l.
exit code error message
@@ -242,12 +292,31 @@ T}
\fB2\fR usage error
\fB3\fR unknown terminal \fItype\fR or no \fBterminfo\fR database
\fB4\fR unknown \fBterminfo\fR capability \fIcapname\fR
+\fB>4\fR error occurred in -S
=
.TE
.SH PORTABILITY
+.PP
The \fBlongname\fR and \fB-S\fR options, and the parameter-substitution
features used in the \fBcup\fR example, are not supported in BSD curses or in
AT&T/USL curses before SVr4.
+.PP
+X/Open documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP.
+In this implementation, \fBclear\fP is part of the \fIcapname\fR support.
+Other implementations of \fBtput\fP on
+SVr4-based systems such as Solaris, IRIX64 and HPUX
+as well as others such as AIX and Tru64
+provide support for \fIcapname\fR operands.
+A few platforms such as FreeBSD and NetBSD recognize termcap names rather
+than terminfo capability names in their respective \fBtput\fP commands.
+.SH SEE ALSO
+\fB@CLEAR@\fR(1),
+\fBstty\fR(1),
+\fBtabs\fR(\*n),
+\fBterminfo\fR(5).
+.PP
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
diff --git a/contrib/ncurses/man/tset.1 b/contrib/ncurses/man/tset.1
index 897d9edb5446..93e7c38580c7 100644
--- a/contrib/ncurses/man/tset.1
+++ b/contrib/ncurses/man/tset.1
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2005,2006 Free 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,14 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tset.1,v 1.12 2000/09/09 20:33:07 tom Exp $
+.\" $Id: tset.1,v 1.18 2006/07/29 11:34:07 tom Exp $
.TH tset 1 ""
.SH NAME
\fBtset\fR, \fBreset\fR - terminal initialization
.SH SYNOPSIS
-tset [-IQVqrs] [-] [-e \fIch\fR] [-i \fIch\fR] [-k \fIch\fR] [-m \fImapping\fR] [\fIterminal\fR]
+\fBtset\fR [\fB-IQVcqrsw\fR] [\fB-\fR] [\fB-e\fR \fIch\fR] [\fB-i\fR \fIch\fR] [\fB-k\fR \fIch\fR] [\fB-m\fR \fImapping\fR] [\fIterminal\fR]
.br
-reset [-IQVqrs] [-] [-e \fIch\fR] [-i \fIch\fR] [-k \fIch\fR] [-m \fImapping\fR] [\fIterminal\fR]
+\fBreset\fR [\fB-IQVcqrsw\fR] [\fB-\fR] [\fB-e\fR \fIch\fR] [\fB-i\fR \fIch\fR] [\fB-k\fR \fIch\fR] [\fB-m\fR \fImapping\fR] [\fIterminal\fR]
.SH DESCRIPTION
\&\fBTset\fR initializes terminals.
\fBTset\fR first determines the type of terminal that you are using.
@@ -50,8 +50,10 @@ System-V-like UNIXes, \fIgetty\fR does this job by setting
.PP
4. The default terminal type, ``unknown''.
.PP
-If the terminal type was not specified on the command-line, the -m
-option mappings are then applied (see below for more information).
+If the terminal type was not specified on the command-line, the \fB-m\fR
+option mappings are then applied (see the section
+.B TERMINAL TYPE MAPPING
+for more information).
Then, if the terminal type begins with a question mark (``?''), the
user is prompted for confirmation of the terminal type. An empty
response confirms the type, or, another type can be entered to specify
@@ -65,6 +67,9 @@ and tab initialization strings are sent to the standard error output.
Finally, if the erase, interrupt and line kill characters have changed,
or are not set to their default values, their values are displayed to the
standard error output.
+Use the \fB-c\fP or \fB-w\fP option to select only the window sizing
+versus the other initialization.
+If neither option is given, both are assumed.
.PP
When invoked as \fBreset\fR, \fBtset\fR sets cooked and echo modes,
turns off cbreak and raw modes, turns on newline translation and
@@ -72,68 +77,82 @@ resets any unset special characters to their default values before
doing the terminal initialization described above. This is useful
after a program dies leaving a terminal in an abnormal state. Note,
you may have to type
-
+.sp
\fB<LF>reset<LF>\fR
-
+.sp
(the line-feed character is normally control-J) to get the terminal
to work, as carriage-return may no longer work in the abnormal state.
Also, the terminal will often not echo the command.
.PP
The options are as follows:
.TP 5
--q
-The terminal type is displayed to the standard output, and the terminal is
-not initialized in any way. The option `-' by itself is equivalent but
-archaic.
-.TP 5
--e
+.B -c
+Set control characters and modes.
+.B -e
Set the erase character to \fIch\fR.
-.TP 5
--I
+.TP
+.B -I
Do not send the terminal or tab initialization strings to the terminal.
-.TP 5
--Q
-Don't display any values for the erase, interrupt and line kill characters.
.TP
-\fB-V\fR
-reports the version of ncurses which was used in this program, and exits.
-.TP 5
--i
+.B -i
Set the interrupt character to \fIch\fR.
-.TP 5
--k
+.TP
+.B -k
Set the line kill character to \fIch\fR.
-.TP 5
--m
+.TP
+.B -m
Specify a mapping from a port type to a terminal.
-See below for more information.
-.TP 5
--r
+See the section
+.B TERMINAL TYPE MAPPING
+for more information.
+.TP
+.B -Q
+Do not display any values for the erase, interrupt and line kill characters.
+Normally \fBtset\fR displays the values for control characters which
+differ from the system's default values.
+.TP
+.B -q
+The terminal type is displayed to the standard output, and the terminal is
+not initialized in any way. The option `-' by itself is equivalent but
+archaic.
+.TP
+.B -r
Print the terminal type to the standard error output.
-.TP 5
--s
+.TP
+.B -s
Print the sequence of shell commands to initialize the environment variable
\fBTERM\fR to the standard output.
-See the section below on setting the environment for details.
+See the section
+.B SETTING THE ENVIRONMENT
+for details.
+.TP
+.B -V
+reports the version of ncurses which was used in this program, and exits.
+.TP
+.B -w
+Resize the window to match the size deduced via \fBsetupterm\fP.
+Normally this has no effect,
+unless \fBsetupterm\fP is not able to detect the window size.
.PP
-The arguments for the -e, -i, and -k
+The arguments for the \fB-e\fR, \fB-i\fR, and \fB-k\fR
options may either be entered as actual characters or by using the `hat'
notation, i.e. control-h may be specified as ``^H'' or ``^h''.
+.
.SH SETTING THE ENVIRONMENT
It is often desirable to enter the terminal type and information about
the terminal's capabilities into the shell's environment.
-This is done using the -s option.
+This is done using the \fB-s\fR option.
.PP
-When the -s option is specified, the commands to enter the information
+When the \fB-s\fR option is specified, the commands to enter the information
into the shell's environment are written to the standard output. If
the \fBSHELL\fR environmental variable ends in ``csh'', the commands
are for \fBcsh\fR, otherwise, they are for \fBsh\fR.
Note, the \fBcsh\fR commands set and unset the shell variable
\fBnoglob\fR, leaving it unset. The following line in the \fB.login\fR
or \fB.profile\fR files will initialize the environment correctly:
-
+.sp
eval \`tset -s options ... \`
-
+.
.SH TERMINAL TYPE MAPPING
When the terminal is not hardwired into the system (or the current
system information is incorrect) the terminal type derived from the
@@ -142,13 +161,13 @@ something generic like \fBnetwork\fR, \fBdialup\fR, or \fBunknown\fR.
When \fBtset\fR is used in a startup script it is often desirable to
provide information about the type of terminal used on such ports.
.PP
-The purpose of the -m option is to map
+The purpose of the \fB-m\fR option is to map
from some set of conditions to a terminal type, that is, to
tell \fBtset\fR
``If I'm on this port at a particular speed, guess that I'm on that
kind of terminal''.
.PP
-The argument to the -m option consists of an optional port type, an
+The argument to the \fB-m\fR option consists of an optional port type, an
optional operator, an optional baud rate specification, an optional
colon (``:'') character and a terminal type. The port type is a
string (delimited by either the operator or the colon character). The
@@ -159,7 +178,7 @@ The baud rate is specified as a number and is compared with the speed
of the standard error output (which should be the control terminal).
The terminal type is a string.
.PP
-If the terminal type is not specified on the command line, the -m
+If the terminal type is not specified on the command line, the \fB-m\fR
mappings are applied to the terminal type. If the port type and baud
rate match the mapping, the terminal type specified in the mapping
replaces the current type. If more than one mapping is specified, the
@@ -181,9 +200,9 @@ Note, because of the leading question mark, the user will be
queried on a default port as to whether they are actually using an xterm
terminal.
.PP
-No whitespace characters are permitted in the -m option argument.
+No whitespace characters are permitted in the \fB-m\fR option argument.
Also, to avoid problems with meta-characters, it is suggested that the
-entire -m option argument be placed within single quote characters,
+entire \fB-m\fR option argument be placed within single quote characters,
and that \fBcsh\fR users insert a backslash character (``\e'') before
any exclamation marks (``!'').
.SH HISTORY
@@ -197,8 +216,8 @@ can set \fBTERM\fR appropriately for each dial-up line; this obviates what was
\fBtset\fR's most important use). This implementation behaves like 4.4BSD
tset, with a few exceptions specified here.
.PP
-The -S option of BSD tset no longer works; it prints an error message to stderr
-and dies. The -s option only sets \fBTERM\fR, not \fBTERMCAP\fP. Both these
+The \fB-S\fR option of BSD tset no longer works; it prints an error message to stderr
+and dies. The \fB-s\fR option only sets \fBTERM\fR, not \fBTERMCAP\fP. Both these
changes are because the \fBTERMCAP\fR variable is no longer supported under
terminfo-based \fBncurses\fR, which makes \fBtset -S\fR useless (we made it die
noisily rather than silently induce lossage).
@@ -207,44 +226,63 @@ There was an undocumented 4.4BSD feature that invoking tset via a link named
`TSET` (or via any other name beginning with an upper-case letter) set the
terminal to use upper-case only. This feature has been omitted.
.PP
-The -A, -E, -h, -u and -v options were deleted from the \fBtset\fR
-utility in 4.4BSD. None of them were documented in 4.3BSD and all are
-of limited utility at best. The -a, -d, and -p options are similarly
+The \fB-A\fR, \fB-E\fR, \fB-h\fR, \fB-u\fR and \fB-v\fR
+options were deleted from the \fBtset\fR
+utility in 4.4BSD.
+None of them were documented in 4.3BSD and all are
+of limited utility at best.
+The \fB-a\fR, \fB-d\fR, and \fB-p\fR options are similarly
not documented or useful, but were retained as they appear to be in
widespread use. It is strongly recommended that any usage of these
-three options be changed to use the -m option instead. The
--n option remains, but has no effect. The -adnp options are therefore
+three options be changed to use the \fB-m\fR option instead. The
+-n option remains, but has no effect. The \fB-adnp\fR options are therefore
omitted from the usage summary above.
.PP
-It is still permissible to specify the -e, -i, and -k options without
+It is still permissible to specify the \fB-e\fR, \fB-i\fR, and \fB-k\fR options without
arguments, although it is strongly recommended that such usage be fixed to
explicitly specify the character.
.PP
-As of 4.4BSD, executing \fBtset\fR as \fBreset\fR no longer implies the -Q
+As of 4.4BSD, executing \fBtset\fR as \fBreset\fR no longer implies the \fB-Q\fR
option. Also, the interaction between the - option and the \fIterminal\fR
argument in some historic implementations of \fBtset\fR has been removed.
.SH ENVIRONMENT
-The \fBtset\fR command uses the \fBSHELL\fR and \fBTERM\fR
-environment variables.
+The \fBtset\fR command uses these environment variables:
+.TP 5
+SHELL
+tells \fBtset\fP whether to initialize \fBTERM\fP using \fBsh\fP or
+\fBcsh\fP syntax.
+.TP 5
+TERM
+Denotes your terminal type.
+Each terminal type is distinct, though many are similar.
+.TP 5
+TERMCAP
+may denote the location of a termcap database.
+If it is not an absolute pathname, e.g., begins with a `/',
+\fBtset\fP removes the variable from the environment before looking
+for the terminal description.
.SH FILES
.TP 5
/etc/ttys
system port name to terminal type mapping database (BSD versions only).
-.TP 5
+.TP
@TERMINFO@
terminal capability database
.SH SEE ALSO
csh(1),
sh(1),
stty(1),
+setupterm(3X),
tty(4),
-termcap(5),
+terminfo(5),
ttys(5),
environ(7)
+.PP
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.\"#
.\"# The following sets edit modes for GNU EMACS
.\"# Local Variables:
.\"# mode:nroff
.\"# fill-column:79
.\"# End:
-
diff --git a/contrib/ncurses/man/wresize.3x b/contrib/ncurses/man/wresize.3x
index 62933f1a153d..4d05d3ee7069 100644
--- a/contrib/ncurses/man/wresize.3x
+++ b/contrib/ncurses/man/wresize.3x
@@ -1,5 +1,5 @@
.\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2003,2006 Free 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,15 +26,15 @@
.\" authorization. *
.\"***************************************************************************
.\"
-.\" Author: Thomas E. Dickey <dickey@clark.net> 1996
+.\" Author: Thomas E. Dickey 1996
.\"
-.\" $Id: wresize.3x,v 1.7 2002/02/16 22:40:59 tom Exp $
+.\" $Id: wresize.3x,v 1.9 2006/02/25 21:47:06 tom Exp $
.TH wresize 3X ""
.SH NAME
\fBwresize\fR - resize a curses window
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
+.sp
\fBint wresize(WINDOW *win, int lines, int columns);\fR
.SH DESCRIPTION
The \fBwresize\fR function reallocates storage for an \fBncurses\fR