diff options
Diffstat (limited to 'contrib/ncurses/man')
126 files changed, 3459 insertions, 1779 deletions
diff --git a/contrib/ncurses/man/Makefile.in b/contrib/ncurses/man/Makefile.in index 56dbe09..8a24d84 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 40c09f5..1bb6dec 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 4c4991f..41c4cad 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 fae59ae..91228d4 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 17d3446..f84c2cb 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 63e0526..d8b645d 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 0d9ea29..ac1b040 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 a845acb..488b9dd 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 4ce7c23..63d2746 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 022613d..31c5397 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 b9caaa8..49e5761 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 035e975..b2d768a 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 3be0dce..8c6f6af 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 c087fad..3071d2a 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 ba7a197..dbf8653 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 d08e852..fa7723a 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 18926d9..99e63ef 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 34bd9ac..7026667 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 8b39402..2599139 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 dc05b39..c053864 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 26ff2d4..6ecff79 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 f8fa51d..4286c78 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 2dfa10b..91b9961 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 73e1a29..71fed5f 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 1a32a0b..f131765 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 820bf99..8fe53dc 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 668595c..8709d13 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 0012789..b04a1f5 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 bcc8d6f..3091b9c 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 60f9d56..18c21dc 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 daa5e1e..1a865f9 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 1fc6a82..7b5a17b 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 23cf099..bb8a9a3 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 197f30f..0c153c4 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 8546cf5..78ab5a5 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 ed1e13e..6a5d312 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 9a09ab2..a93de27 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 b345ce6..990789c 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 caeb5bb..9403973 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 8211ef8..865fab1 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 2fff160..8046377 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 f9db6f2..5b986bb 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 f17b375..066c3a4 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 0813a0a..c722207 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 dd4b6e3..92b9ca2 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 8ba9d17..7c1a41b 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 210b326..5ce0690 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 b7f3795..9f25b57 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 581d10d..d432c0d 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 f957ac9..754b714 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 8f1ae8a..b946ff2 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 d285b86..48ff21c 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 828bb9a..e8072dc 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 c61b695..435ac35 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 58ffa9f..a7d07bc 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 4af258d..560302c 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 09d490d..e78f999 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 4d3ca4c..552862e 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 4ebb901..ce313e2 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 1019c42..216a3cb 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 811b9ff..264662e 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 ab37c99..bf9f28d 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 3767e95..2ba004c 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 2354089..c88e3be 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 f452036..f3a26c5 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 ac7a3b5..90dc0f3 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 814c5d9..cac6a08 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 56b81ac..bde3128 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 9468d8b..15d6cb2 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 9691520..168349e 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 8f5e2de..87449f2 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 2aba208..47b9ed4 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 cc3d508..175268b 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 69a8e20..0d42fae 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 19c1b9f..82b62c3 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 0f4c501..cac4f50 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 432f624..5b7f58d 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 7921b37..4bf5b1e 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 4b5d15a..50ed54d 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 56e86ab..6bf1607 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 df1f701..a172f85 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 00e3d71..7be0bf8 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 e565970..c8f64f2 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 8ee2840..a7feb44 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 ef8735b..1d20ef0 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 0000000..d7413da --- /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 79c480c..93e1794 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 e3f2287..08c2a27 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 0000000..b8b0561 --- /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 c6c37c2..f2afac9 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 7aaf1de..8e968ac 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 e175148..4da7790 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 e81913c..17d6fc1 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 99a2ac2..d96ea23 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 2cc5850..4ade0bf 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 0e6f9e0..a256141 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 7dde28f..f4d456f 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 531528a..8405523 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 7ec7db5..0915343 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 72ea000..1db2b3e 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 c53bd9b..c2b98e4 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 30cad58..890b2c2 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 990a9dc..50dee87 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 a4182d6..e47facc 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 f4b646a..1345aa7 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 1831621..dfe03a8 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 1fe3541..b7be2ad 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 336da44..aa356e1 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 179a23b..979f401 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 007752e..12009ed 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 0653840..c0fa6ed 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 99e4e5e..2a4a876 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 2dd564f..5895193 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 5817d8d..748fd52 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 84ead5c..19678da 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 7ebecc0..2896f01 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 562c353..888eaaf 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 a8cf6e5..cd7e79a 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 5d51e92..0a77cf6 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 36945ff..28006d3 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 bd585b1..fa9a90d 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 e3a0954..f13e0fd 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 399cf61..1419674 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 898df1e..4de0b73 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 897d9ed..93e7c38 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 62933f1..4d05d3e 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 |
