diff options
Diffstat (limited to 'man')
131 files changed, 2283 insertions, 1272 deletions
diff --git a/man/MKada_config.in b/man/MKada_config.in index 5f34cff..275b9fb 100644 --- a/man/MKada_config.in +++ b/man/MKada_config.in @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2019,2020 Thomas E. Dickey * +.\" Copyright 2019-2020,2021 Thomas E. Dickey * .\" Copyright 2010-2014,2016 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: MKada_config.in,v 1.12 2020/02/02 23:34:34 tom Exp $ +.\" $Id: MKada_config.in,v 1.13 2021/06/17 21:26:02 tom Exp $ .ds C adacurses@USE_CFG_SUFFIX@\-config .TH ADACURSES "1" "" "" "User Commands" .SH NAME @@ -54,7 +54,7 @@ to configure and build @ADA_LIBNAME@. prints a list of the \fB\*C\fP script's options. .PP If no options are given, \fB\*C\fP prints the combination -of +of \fB\-\-cflags\fR and \fB\-\-libs\fR that \fBgnatmake\fP expects (see example). diff --git a/man/MKncu_config.in b/man/MKncu_config.in index 15d5190..ca68efd 100644 --- a/man/MKncu_config.in +++ b/man/MKncu_config.in @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2020 Thomas E. Dickey * +.\" Copyright 2020,2021 Thomas E. Dickey * .\" Copyright 2010 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,12 +27,12 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: MKncu_config.in,v 1.4 2020/02/02 23:34:34 tom Exp $ +.\" $Id: MKncu_config.in,v 1.5 2021/06/17 21:20:30 tom Exp $ .TH @LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config 1 "" .SH NAME @LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config \- helper script for ncurses libraries .SH SYNOPSIS -.B @LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config +.B @LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config [\fIoptions\fR] .SH DESCRIPTION This is a shell script which simplifies configuring applications against diff --git a/man/Makefile.in b/man/Makefile.in index f379db1..2fd18f2 100644 --- a/man/Makefile.in +++ b/man/Makefile.in @@ -1,6 +1,6 @@ -# $Id: Makefile.in,v 1.50 2020/02/02 23:34:34 tom Exp $ +# $Id: Makefile.in,v 1.52 2021/07/03 18:57:29 tom Exp $ ############################################################################## -# Copyright 2019,2020 Thomas E. Dickey # +# Copyright 2019-2020,2021 Thomas E. Dickey # # Copyright 1998-2013,2015 Free Software Foundation, Inc. # # # # Permission is hereby granted, free of charge, to any person obtaining a # @@ -52,6 +52,21 @@ INCLUDEDIR = $(DESTDIR)$(includedir)$(includesubdir) INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ +################################################################################ + +@MAKE_PHONY@.PHONY : all +@MAKE_PHONY@.PHONY : clean +@MAKE_PHONY@.PHONY : depend +@MAKE_PHONY@.PHONY : distclean +@MAKE_PHONY@.PHONY : install +@MAKE_PHONY@.PHONY : install.man +@MAKE_PHONY@.PHONY : libs +@MAKE_PHONY@.PHONY : mostlyclean +@MAKE_PHONY@.PHONY : realclean +@MAKE_PHONY@.PHONY : sources +@MAKE_PHONY@.PHONY : uninstall +@MAKE_PHONY@.PHONY : uninstall.man + all \ sources : terminfo.5 depend : diff --git a/man/curs_add_wch.3x b/man/curs_add_wch.3x index a208c1a..4460208 100644 --- a/man/curs_add_wch.3x +++ b/man/curs_add_wch.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_add_wch.3x,v 1.26 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_add_wch.3x,v 1.28 2020/10/17 23:10:38 tom Exp $ .TH curs_add_wch 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -55,7 +55,7 @@ .B "int mvadd_wch( int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fB );" .br .B "int mvwadd_wch( WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fB );" -.br +.sp .B "int echo_wchar( const cchar_t *\fIwch\fB );" .br .B "int wecho_wchar( WINDOW *\fIwin\fP, const cchar_t *\fIwch\fB );" @@ -212,6 +212,25 @@ U+2550 BOX DRAWINGS DOUBLE HORIZONTAL .PP All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success. .PP +X/Open does not define any error conditions. +This implementation returns an error +.bP +if the window pointer is null or +.bP +if it is not possible to add a complete character in the window. +.PP +The latter may be due to different causes: +.bP +If \fBscrollok\fR is not enabled, +writing a character at the lower right margin succeeds. +However, an error is returned because +it is not possible to wrap to a new line +.bP +If an error is detected when converting a multibyte character to a sequence +of bytes, +or if it is not possible to add all of the resulting bytes in the window, +an error is returned. +.PP Functions with a \*(``mv\*('' prefix first perform a cursor movement using \fBwmove\fP, and return an error if the position is outside the window, or if the window pointer is null. diff --git a/man/curs_add_wchstr.3x b/man/curs_add_wchstr.3x index 5ce6d04..c037be6 100644 --- a/man/curs_add_wchstr.3x +++ b/man/curs_add_wchstr.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_add_wchstr.3x,v 1.13 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_add_wchstr.3x,v 1.15 2020/12/19 21:39:06 tom Exp $ .TH curs_add_wchstr 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -61,7 +61,7 @@ \fBint wadd_wchstr(WINDOW *\fR \fIwin\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB);\fR .br \fBint wadd_wchnstr(WINDOW *\fR \fIwin\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR -.br +.sp \fBint mvadd_wchstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB);\fR .br \fBint mvadd_wchnstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR @@ -115,8 +115,8 @@ All functions except \fBwadd_wchnstr\fR may be macros. .SH PORTABILITY These entry points are described in the XSI Curses standard, Issue 4. .SH SEE ALSO -\fBcurs_addwstr\fR(3X), -\fBcurses\fR(3X). +\fBcurses\fR(3X), +\fBcurs_addwstr\fR(3X). .PP Comparable functions in the narrow-character (ncurses) library are described in diff --git a/man/curs_addch.3x b/man/curs_addch.3x index c92d12b..43f426a 100644 --- a/man/curs_addch.3x +++ b/man/curs_addch.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_addch.3x,v 1.51 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_addch.3x,v 1.56 2021/06/17 21:30:22 tom Exp $ .TH curs_addch 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -48,17 +48,17 @@ .SH SYNOPSIS \fB#include <curses.h>\fR .PP -\fBint addch(const chtype ch);\fR +\fBint addch(const chtype \fP\fIch\fP\fB);\fR .br -\fBint waddch(WINDOW *win, const chtype ch);\fR +\fBint waddch(WINDOW *\fP\fIwin\fP\fB, const chtype \fP\fIch\fP\fB);\fR .br -\fBint mvaddch(int y, int x, const chtype ch);\fR +\fBint mvaddch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const chtype \fP\fIch\fP\fB);\fR .br -\fBint mvwaddch(WINDOW *win, int y, int x, const chtype ch);\fR +\fBint mvwaddch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const chtype \fP\fIch\fP\fB);\fR +.sp +\fBint echochar(const chtype \fP\fIch\fP\fB);\fR .br -\fBint echochar(const chtype ch);\fR -.br -\fBint wechochar(WINDOW *win, const chtype ch);\fR +\fBint wechochar(WINDOW *\fP\fIwin\fP\fB, const chtype \fP\fIch\fP\fB);\fR .br .SH DESCRIPTION .SS Adding characters @@ -94,11 +94,12 @@ 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 other control character, it -is drawn in \fB^\fR\fIX\fR notation. +If \fIch\fR is any other nonprintable character, +it is drawn in printable form, +i.e., the \fB^\fR\fIX\fR notation used by \fBunctrl\fR(3X). Calling \fBwinch\fR after adding a -control character does not return the character itself, but instead returns -the ^-representation of the control character. +nonprintable character does not return the character itself, +but instead returns the printable representation of the 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. @@ -175,6 +176,19 @@ unless otherwise noted in the preceding routine descriptions. Functions with a \*(``mv\*('' prefix first perform a cursor movement using \fBwmove\fP, and return an error if the position is outside the window, or if the window pointer is null. +.PP +If it is not possible to add a complete character, +an error is returned: +.bP +If \fBscrollok\fR is not enabled, +writing a character at the lower right margin succeeds. +However, an error is returned because +it is not possible to wrap to a new line +.bP +If an error is detected when converting a multibyte character to a sequence +of bytes, +or if it is not possible to add all of the resulting bytes in the window, +an error is returned. .SH NOTES Note that \fBaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR, and \fBechochar\fR may be macros. @@ -229,7 +243,7 @@ to light. The ACS-prefixed names for them were invented for \fBncurses\fR(3X). .LP The \fIdisplayed\fP values for the \fIACS_\fP and \fIWACS_\fP constants -depend on +depend on .bP the library configuration, i.e., \fBncurses\fP versus \fBncursesw\fP, where the latter is capable of displaying Unicode while the former is not, and diff --git a/man/curs_addchstr.3x b/man/curs_addchstr.3x index 37e6aee..09d70d6 100644 --- a/man/curs_addchstr.3x +++ b/man/curs_addchstr.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_addchstr.3x,v 1.19 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_addchstr.3x,v 1.22 2020/12/19 21:39:20 tom Exp $ .TH curs_addchstr 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -54,21 +54,21 @@ .nf \fB#include <curses.h>\fR .PP -\fBint addchstr(const chtype *chstr);\fR +\fBint addchstr(const chtype *\fP\fIchstr\fP\fB);\fR .br -\fBint addchnstr(const chtype *chstr, int n);\fR +\fBint addchnstr(const chtype *\fP\fIchstr\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint waddchstr(WINDOW *win, const chtype *chstr);\fR +\fBint waddchstr(WINDOW *\fP\fIwin\fP\fB, const chtype *\fP\fIchstr\fP\fB);\fR .br -\fBint waddchnstr(WINDOW *win, const chtype *chstr, int n);\fR +\fBint waddchnstr(WINDOW *\fP\fIwin\fP\fB, const chtype *\fP\fIchstr\fP\fB, int \fP\fIn\fP\fB);\fR +.sp +\fBint mvaddchstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const chtype *\fP\fIchstr\fP\fB);\fR .br -\fBint mvaddchstr(int y, int x, const chtype *chstr);\fR +\fBint mvaddchnstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const chtype *\fP\fIchstr\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint mvaddchnstr(int y, int x, const chtype *chstr, int n);\fR +\fBint mvwaddchstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const chtype *\fP\fIchstr\fP\fB);\fR .br -\fBint mvwaddchstr(WINDOW *win, int y, int x, const chtype *chstr);\fR -.br -\fBint mvwaddchnstr(WINDOW *win, int y, int x, const chtype *chstr, int n);\fR +\fBint mvwaddchnstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const chtype *\fP\fIchstr\fP\fB, int \fP\fIn\fP\fB);\fR .fi .SH DESCRIPTION These functions copy the (null-terminated) @@ -109,8 +109,8 @@ All functions except \fBwaddchnstr\fR may be macros. .SH PORTABILITY These entry points are described in the XSI Curses standard, Issue 4. .SH SEE ALSO -\fBcurs_addstr\fR(3X), -\fBcurses\fR(3X). +\fBcurses\fR(3X), +\fBcurs_addstr\fR(3X). .PP Comparable functions in the wide-character (ncursesw) library are described in diff --git a/man/curs_addstr.3x b/man/curs_addstr.3x index 6d54ebb..6f280e6 100644 --- a/man/curs_addstr.3x +++ b/man/curs_addstr.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_addstr.3x,v 1.20 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_addstr.3x,v 1.23 2020/10/17 23:11:02 tom Exp $ .TH curs_addstr 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -61,7 +61,7 @@ \fBint waddstr(WINDOW *\fR\fIwin\fR\fB, const char *\fR\fIstr\fR\fB);\fR .br \fBint waddnstr(WINDOW *\fR\fIwin\fR\fB, const char *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR -.br +.sp \fBint mvaddstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const char *\fR\fIstr\fR\fB);\fR .br \fBint mvaddnstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const char *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR @@ -73,14 +73,14 @@ .SH DESCRIPTION These functions write the (null-terminated) character string \fIstr\fR on the given window. -It is similar to calling \fBwaddch\fR once for each character in the string. +It is similar to calling \fBwaddch\fR once for each byte in the string. .PP The \fImv\fR functions perform cursor movement once, before writing any characters. Thereafter, the cursor is advanced as a side-effect of writing to the window. .PP The four functions with \fIn\fR as the last argument -write at most \fIn\fR characters, +write at most \fIn\fR bytes, or until a terminating null is reached. If \fIn\fR is \-1, then the entire string will be added. .SH RETURN VALUE @@ -98,6 +98,18 @@ if the corresponding calls to \fBwaddch\fP return an error. Functions with a \*(``mv\*('' prefix first perform a cursor movement using \fBwmove\fP, and return an error if the position is outside the window, or if the window pointer is null. +If an error is returned by the \fBwmove\fP, +no characters are added to the window. +.PP +If an error is returned by \fBwaddch\fP +(e.g., +because the window is not large enough, +or an illegal byte sequence was detected) +only part of the string may be added. +Aside from that, +there is a special case in \fBwaddch\fP where an error may be +returned after successfully writing a character to the lower-right corner +of a window when \fBscrollok\fP is disabled. .SH NOTES All of these functions except \fBwaddnstr\fR may be macros. .SH PORTABILITY diff --git a/man/curs_addwstr.3x b/man/curs_addwstr.3x index f1d738f..6f7c3db 100644 --- a/man/curs_addwstr.3x +++ b/man/curs_addwstr.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_addwstr.3x,v 1.14 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_addwstr.3x,v 1.15 2020/10/17 23:12:22 tom Exp $ .TH curs_addwstr 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -61,7 +61,7 @@ \fBint waddwstr(WINDOW *\fR\fIwin\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR .br \fBint waddnwstr(WINDOW *\fR\fIwin\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR -.br +.sp \fBint mvaddwstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR .br \fBint mvaddnwstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR diff --git a/man/curs_bkgd.3x b/man/curs_bkgd.3x index 6b66388..356eff4 100644 --- a/man/curs_bkgd.3x +++ b/man/curs_bkgd.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_bkgd.3x,v 1.30 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_bkgd.3x,v 1.32 2021/06/17 21:30:22 tom Exp $ .de bP .ie n .IP \(bu 4 .el .IP \(bu 2 @@ -43,11 +43,11 @@ \fBvoid bkgdset(chtype \fP\fIch\fP\fB);\fR .br \fBvoid wbkgdset(WINDOW *\fP\fIwin, chtype \fP\fIch\fP\fB);\fR -.br +.sp \fBint bkgd(chtype \fP\fIch\fP\fB);\fR .br \fBint wbkgd(WINDOW *\fP\fIwin\fP\fB, chtype \fP\fIch\fP\fB);\fR -.br +.sp \fBchtype getbkgd(WINDOW *\fP\fIwin\fP\fB);\fR .br .SH DESCRIPTION @@ -103,7 +103,7 @@ cell with those from the new background character. If the cell uses color, and that matches the color in the current background, the library removes attributes -which may have come from the current background +which may have come from the current background and adds attributes from the new background. It finishes by setting the cell to use the color from the new background. diff --git a/man/curs_bkgrnd.3x b/man/curs_bkgrnd.3x index 8e3e836..84a2984 100644 --- a/man/curs_bkgrnd.3x +++ b/man/curs_bkgrnd.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_bkgrnd.3x,v 1.11 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_bkgrnd.3x,v 1.12 2020/10/17 23:13:15 tom Exp $ .de bP .ie n .IP \(bu 4 .el .IP \(bu 2 @@ -47,11 +47,11 @@ \fBint bkgrnd(\fR\fB const cchar_t *\fR\fIwch\fR\fB);\fR .br \fBint wbkgrnd(\fR\fB WINDOW *\fR\fIwin\fR\fB, const cchar_t *\fR\fIwch\fR\fB);\fR -.br +.sp \fBvoid bkgrndset(const cchar_t *\fR\fIwch\fR \fB);\fR .br \fBvoid wbkgrndset(WINDOW *\fR\fIwin\fR\fB, const cchar_t *\fR\fIwch\fR\fB);\fR -.br +.sp \fBint getbkgrnd(cchar_t *\fR\fIwch\fR\fB);\fR .br \fBint wgetbkgrnd(WINDOW *\fR\fIwin\fR\fB, cchar_t *\fR\fIwch\fR\fB);\fR diff --git a/man/curs_border.3x b/man/curs_border.3x index eaf6954..7b41da5 100644 --- a/man/curs_border.3x +++ b/man/curs_border.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_border.3x,v 1.25 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_border.3x,v 1.27 2020/10/18 00:33:06 tom Exp $ .TH curs_border 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -51,31 +51,31 @@ .hy .SH SYNOPSIS \fB#include <curses.h>\fR +.sp +\fBint border(chtype \fP\fIls\fP\fB, chtype \fP\fIrs\fP\fB, chtype \fP\fIts\fP\fB, chtype \fP\fIbs\fP\fB,\fR + \fBchtype \fP\fItl\fP\fB, chtype \fP\fItr\fP\fB, chtype \fP\fIbl\fP\fB, chtype \fP\fIbr\fP\fB);\fR .br -\fBint border(chtype ls, chtype rs, chtype ts, chtype bs,\fR - \fBchtype tl, chtype tr, chtype bl, chtype br);\fR -.br -\fBint wborder(WINDOW *win, chtype ls, chtype rs,\fR - \fBchtype ts, chtype bs, chtype tl, chtype tr,\fR - \fBchtype bl, chtype br);\fR -.br -\fBint box(WINDOW *win, chtype verch, chtype horch);\fR -.br -\fBint hline(chtype ch, int n);\fR -.br -\fBint whline(WINDOW *win, chtype ch, int n);\fR +\fBint wborder(WINDOW *\fP\fIwin\fP\fB, chtype \fP\fIls\fP\fB, chtype \fP\fIrs\fP\fB,\fR + \fBchtype \fP\fIts\fP\fB, chtype \fP\fIbs\fP\fB, chtype \fP\fItl\fP\fB, chtype \fP\fItr\fP\fB,\fR + \fBchtype \fP\fIbl\fP\fB, chtype \fP\fIbr\fP\fB);\fR +.sp +\fBint box(WINDOW *\fP\fIwin\fP\fB, chtype \fP\fIverch\fP\fB, chtype \fP\fIhorch\fP\fB);\fR +.sp +\fBint hline(chtype \fP\fIch\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint vline(chtype ch, int n);\fR +\fBint whline(WINDOW *\fP\fIwin\fP\fB, chtype \fP\fIch\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint wvline(WINDOW *win, chtype ch, int n);\fR +\fBint vline(chtype \fP\fIch\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint mvhline(int y, int x, chtype ch, int n);\fR +\fBint wvline(WINDOW *\fP\fIwin\fP\fB, chtype \fP\fIch\fP\fB, int \fP\fIn\fP\fB);\fR +.sp +\fBint mvhline(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, chtype \fP\fIch\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint mvwhline(WINDOW *, int y, int x, chtype ch, int n);\fR +\fBint mvwhline(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, chtype \fP\fIch\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint mvvline(int y, int x, chtype ch, int n);\fR +\fBint mvvline(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, chtype \fP\fIch\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint mvwvline(WINDOW *, int y, int x, chtype ch, int n);\fR +\fBint mvwvline(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, chtype \fP\fIch\fP\fB, int \fP\fIn\fP\fB);\fR .br .SH DESCRIPTION The \fBborder\fR, \fBwborder\fR and \fBbox\fR routines diff --git a/man/curs_clear.3x b/man/curs_clear.3x index 2cce06e..d86acbd 100644 --- a/man/curs_clear.3x +++ b/man/curs_clear.3x @@ -27,10 +27,14 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_clear.3x,v 1.17 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_clear.3x,v 1.20 2020/10/24 09:19:37 tom Exp $ .TH curs_clear 3X "" .na .hy 0 +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. .SH NAME \fBerase\fR, \fBwerase\fR, @@ -43,23 +47,23 @@ .ad .hy .SH SYNOPSIS -\fB# include <curses.h>\fR +\fB#include <curses.h>\fR .sp \fBint erase(void);\fR .br -\fBint werase(WINDOW *win);\fR -.br +\fBint werase(WINDOW *\fP\fIwin\fP\fB);\fR +.sp \fBint clear(void);\fR .br -\fBint wclear(WINDOW *win);\fR -.br +\fBint wclear(WINDOW *\fP\fIwin\fP\fB);\fR +.sp \fBint clrtobot(void);\fR .br -\fBint wclrtobot(WINDOW *win);\fR -.br +\fBint wclrtobot(WINDOW *\fP\fIwin\fP\fB);\fR +.sp \fBint clrtoeol(void);\fR .br -\fBint wclrtoeol(WINDOW *win);\fR +\fBint wclrtoeol(WINDOW *\fP\fIwin\fP\fB);\fR .br .SH DESCRIPTION The \fBerase\fR and \fBwerase\fR routines copy blanks to every @@ -82,12 +86,14 @@ 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 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. +.bP +functions using a window pointer parameter return an error if it is null +.bP +\fBwclrtoeol\fP returns an error +if the cursor position is about to wrap. .SH NOTES Note that \fBerase\fR, \fBwerase\fR, \fBclear\fR, \fBwclear\fR, \fBclrtobot\fR, and \fBclrtoeol\fR may be macros. @@ -97,6 +103,12 @@ The standard specifies that they return \fBERR\fR on failure, but specifies no error conditions. .PP +The SVr4.0 manual says that these functions could +return "a non-negative integer if \fBimmedok\fR is set", +referring to the return-value of \fBwrefresh\fP. +In that implementation, \fBwrefresh\fP would return a count of +the number of characters written to the terminal. +.PP Some historic curses implementations had, as an undocumented feature, the ability to do the equivalent of \fBclearok(..., 1)\fR by saying \fBtouchwin(stdscr)\fR or \fBclear(stdscr)\fR. diff --git a/man/curs_color.3x b/man/curs_color.3x index b3521cb..2b8b607 100644 --- a/man/curs_color.3x +++ b/man/curs_color.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_color.3x,v 1.62 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_color.3x,v 1.66 2021/09/04 19:42:20 tom Exp $ .TH curs_color 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -66,31 +66,31 @@ .br \fBbool can_change_color(void);\fR .sp -\fBint init_pair(short pair, short f, short b);\fR +\fBint init_pair(short \fP\fIpair\fP\fB, short \fP\fIf\fP\fB, short \fP\fIb\fP\fB);\fR .br -\fBint init_color(short color, short r, short g, short b);\fR +\fBint init_color(short \fP\fIcolor\fP\fB, short \fP\fIr\fP\fB, short \fP\fIg\fP\fB, short \fP\fIb\fP\fB);\fR .br /* extensions */ .br -\fBint init_extended_pair(int pair, int f, int b);\fR +\fBint init_extended_pair(int \fP\fIpair\fP\fB, int \fP\fIf\fP\fB, int \fP\fIb\fP\fB);\fR .br -\fBint init_extended_color(int color, int r, int g, int b);\fR +\fBint init_extended_color(int \fP\fIcolor\fP\fB, int \fP\fIr\fP\fB, int \fP\fIg\fP\fB, int \fP\fIb\fP\fB);\fR .sp -\fBint color_content(short color, short *r, short *g, short *b);\fR +\fBint color_content(short \fP\fIcolor\fP\fB, short *\fP\fIr\fP\fB, short *\fP\fIg\fP\fB, short *\fP\fIb\fP\fB);\fR .br -\fBint pair_content(short pair, short *f, short *b);\fR +\fBint pair_content(short \fP\fIpair\fP\fB, short *\fP\fIf\fP\fB, short *\fP\fIb\fP\fB);\fR .br /* extensions */ .br -\fBint extended_color_content(int color, int *r, int *g, int *b);\fR +\fBint extended_color_content(int \fP\fIcolor\fP\fB, int *\fP\fIr\fP\fB, int *\fP\fIg\fP\fB, int *\fP\fIb\fP\fB);\fR .br -\fBint extended_pair_content(int pair, int *f, int *b);\fR +\fBint extended_pair_content(int \fP\fIpair\fP\fB, int *\fP\fIf\fP\fB, int *\fP\fIb\fP\fB);\fR .sp /* extensions */ .br \fBvoid reset_color_pairs(void);\fR .sp -\fBint COLOR_PAIR(int n);\fR +\fBint COLOR_PAIR(int \fP\fIn\fP\fB);\fR .br \fBPAIR_NUMBER(\fR\fIattrs\fR\fB);\fP .br @@ -422,7 +422,7 @@ if \fBstart_color\fP was not called. SVr4 does much the same, except that it returns \fBERR\fP from \fBpair_content\fP if the pair was not initialized using \fBinit_pairs\fP -and +and it returns \fBERR\fP from \fBcolor_content\fP if the terminal does not support changing colors. .IP @@ -467,6 +467,54 @@ Paradise and compatibles) do the wrong thing when you try to set a bright \*(``yellow\*('' background (you get a blinking yellow foreground instead). .bP Color RGB values are not settable. +.SH HISTORY +.PP +SVr3.2 introduced color support to curses in 1987. +.PP +SVr4 made internal changes, +e.g., moving the storage for the color state +from \fBSP\fP (the \fBSCREEN\fP structure) +to \fBcur_term\fP (the \fBTERMINAL\fP structure), +but provided the same set of library functions. +.PP +SVr4 curses limits the number of color pairs to 64, +reserving color pair zero (0) as the terminal's initial uncolored state. +This limit arises because the color pair information is a bitfield +in the \fBchtype\fP data type (denoted by \fBA_COLOR\fP). +.PP +Other implementations of curses had different limits: +.bP +PCCurses (1987-1990) provided for only eight (8) colors. +.bP +PDCurses (1992-present) inherited the 8-color limitation from PCCurses, +but changed this to 256 in version 2.5 (2001), +along with changing \fBchtype\fP from 16-bits to 32-bits. +.bP +X/Open Curses (1992-present) +added a new structure \fBcchar_t\fP to store the character, +attributes and color-pair values, allowing increased range of color-pairs. +Both color-pairs and color-values used a signed \fBshort\fP, +limiting values to 15 bits. +.bP +ncurses (1992-present) uses eight bits for \fBA_COLOR\fP in \fBchtype\fP values. +.IP +Version 5.3 provided a wide-character interface (2002), +but left color-pairs as part of the attributes-field. +.IP +Since version 6 (2015), +ncurses uses a separate \fBint\fP for color-pairs in the \fBcchar_t\fP values. +When those color-pair values fit in 8 bits, +ncurses allows color-pairs to be manipulated +via the functions using \fBchtype\fP values. +.bP +NetBSD curses used 6 bits from +2000 (when colors were first supported) until 2004. +At that point, NetBSD changed to use 10 bits. +As of 2021, that size is unchanged. +Like ncurses before version 6, +the NetBSD color-pair information is stored in +the attributes field of \fBcchar_t\fP, limiting the number of color-pairs +by the size of the bitfield. .SH PORTABILITY This implementation satisfies XSI Curses's minimum maximums for \fBCOLORS\fR and \fBCOLOR_PAIRS\fR. diff --git a/man/curs_delch.3x b/man/curs_delch.3x index ecfde60..86f0984 100644 --- a/man/curs_delch.3x +++ b/man/curs_delch.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_delch.3x,v 1.14 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_delch.3x,v 1.15 2020/10/24 09:36:43 tom Exp $ .TH curs_delch 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -43,11 +43,11 @@ .sp \fBint delch(void);\fR .br -\fBint wdelch(WINDOW *win);\fR +\fBint wdelch(WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBint mvdelch(int y, int x);\fR +\fBint mvdelch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR .br -\fBint mvwdelch(WINDOW *win, int y, int x);\fR +\fBint mvwdelch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR .br .SH DESCRIPTION These routines delete the character under the cursor; all characters to the diff --git a/man/curs_deleteln.3x b/man/curs_deleteln.3x index 2e667c8..391c800 100644 --- a/man/curs_deleteln.3x +++ b/man/curs_deleteln.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_deleteln.3x,v 1.15 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_deleteln.3x,v 1.17 2020/10/18 00:28:51 tom Exp $ .TH curs_deleteln 3X "" .SH NAME \fBdeleteln\fR, @@ -41,15 +41,15 @@ .sp \fBint deleteln(void);\fR .br -\fBint wdeleteln(WINDOW *win);\fR -.br -\fBint insdelln(int n);\fR -.br -\fBint winsdelln(WINDOW *win, int n);\fR +\fBint wdeleteln(WINDOW *\fP\fIwin\fP\fB);\fR +.sp +\fBint insdelln(int \fP\fIn\fP\fB);\fR .br +\fBint winsdelln(WINDOW *\fP\fIwin\fP\fB, int \fP\fIn\fP\fB);\fR +.sp \fBint insertln(void);\fR .br -\fBint winsertln(WINDOW *win);\fR +\fBint winsertln(WINDOW *\fP\fIwin\fP\fB);\fR .br .SH DESCRIPTION The \fBdeleteln\fR and \fBwdeleteln\fR routines delete the line under the diff --git a/man/curs_extend.3x b/man/curs_extend.3x index 307c8a1..a316a6b 100644 --- a/man/curs_extend.3x +++ b/man/curs_extend.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1999-2010,2016 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -29,8 +29,12 @@ .\" .\" Author: Thomas E. Dickey 1999-on .\" -.\" $Id: curs_extend.3x,v 1.23 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_extend.3x,v 1.26 2021/03/13 13:43:05 tom Exp $ .TH curs_extend 3X "" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' .SH NAME \fBcurses_version\fP, \fBuse_extended_names\fP \- miscellaneous curses extensions @@ -40,15 +44,19 @@ .sp \fBconst char * curses_version(void);\fP .br -\fBint use_extended_names(bool enable);\fP +\fBint use_extended_names(bool \fP\fIenable\fP\fB);\fP .SH DESCRIPTION These functions are extensions to the curses library which do not fit easily into other categories. .SS curses_version .PP Use \fBcurses_version\fP -to get the version number, including patch level of the library, e.g., -.B 5.0.19991023 +to get the version number, including patch level of the library, +prefixed by \*(``ncurses\*('', e.g., +.RS +.sp +.B ncurses 5.0.19991023 +.RE .SS use_extended_names .PP The \fBuse_extended_names\fP diff --git a/man/curs_get_wch.3x b/man/curs_get_wch.3x index 4a30cf1..115f068 100644 --- a/man/curs_get_wch.3x +++ b/man/curs_get_wch.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 2002-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_get_wch.3x,v 1.13 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_get_wch.3x,v 1.15 2021/05/22 22:33:19 tom Exp $ .TH curs_get_wch 3X "" .na .hy 0 @@ -57,9 +57,10 @@ \fBint mvget_wch(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwch\fR\fB);\fR .br \fBint mvwget_wch(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwch\fR\fB);\fR -.br +.sp \fBint unget_wch(const wchar_t \fR\fIwch\fR\fB);\fR .SH DESCRIPTION +.SS wget_wch The \fBget_wch\fR, \fBwget_wch\fR, @@ -111,7 +112,7 @@ Their names begin with \fBKEY_\fR. Other (user-defined) function keys which may be defined using \fBdefine_key\fP(3X) have no names, but also are expected to have values outside the range of 8-bit characters. -.PP +.SS unget_wch The \fBunget_wch\fR function pushes the wide character @@ -126,6 +127,14 @@ If the program calls too many times without an intervening call to \fBget_wch\fR, the operation may fail. +.PP +Unlike \fBungetch\fP and \fBwgetch\fP, +\fBunget_wch\fP cannot distinguish special characters +returned by \fBwget_wch\fP from ordinary characters. +An application can push special keys +which it may read via \fBwget_wch\fP +by checking for the \fBKEY_CODE_YES\fR result, +and using \fBungetch\fP for those special keys. .SH NOTES The header file \fB<curses.h>\fR diff --git a/man/curs_get_wstr.3x b/man/curs_get_wstr.3x index ce8572e..112208a 100644 --- a/man/curs_get_wstr.3x +++ b/man/curs_get_wstr.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_get_wstr.3x,v 1.20 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_get_wstr.3x,v 1.21 2020/10/17 23:17:24 tom Exp $ .TH curs_get_wstr 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -61,7 +61,7 @@ \fBint wget_wstr(WINDOW *\fR\fIwin\fR\fB, wint_t *\fR\fIwstr\fR\fB);\fR .br \fBint wgetn_wstr(WINDOW *\fR\fIwin\fR\fB, wint_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR -.br +.sp \fBint mvget_wstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwstr\fR\fB);\fR .br \fBint mvgetn_wstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR diff --git a/man/curs_getcchar.3x b/man/curs_getcchar.3x index fafe782..cc127e2 100644 --- a/man/curs_getcchar.3x +++ b/man/curs_getcchar.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2019,2020 Thomas E. Dickey * +.\" Copyright 2019-2020,2021 Thomas E. Dickey * .\" Copyright 2001-2015,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getcchar.3x,v 1.24 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_getcchar.3x,v 1.25 2021/06/17 21:26:02 tom Exp $ .TH curs_getcchar 3X "" .de bP .ie n .IP \(bu 4 @@ -116,7 +116,7 @@ In that case, no nonspacing characters are allowed. .PP X/Open Curses documents the \fIopts\fP argument as reserved for future use, saying that it must be null. -This implementation +This implementation uses that parameter in ABI 6 for the functions which have a color-pair parameter to support extended color pairs: .bP diff --git a/man/curs_getch.3x b/man/curs_getch.3x index c171f1d..a8c4bc1 100644 --- a/man/curs_getch.3x +++ b/man/curs_getch.3x @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getch.3x,v 1.55 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_getch.3x,v 1.57 2020/12/19 21:38:20 tom Exp $ .TH curs_getch 3X "" .na .hy 0 @@ -55,12 +55,14 @@ \fBint getch(void);\fR .br \fBint wgetch(WINDOW *\fP\fIwin);\fR -.br +.sp \fBint mvgetch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR .br \fBint mvwgetch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR -.br +.sp \fBint ungetch(int \fP\fIch\fP\fB);\fR +.sp +/* extension */ .br \fBint has_key(int \fP\fIch\fP\fB);\fR .br @@ -404,9 +406,9 @@ any code using it be conditionalized on the \fBNCURSES_VERSION\fR feature macro. .SH SEE ALSO \fBcurses\fR(3X), \fBcurs_inopts\fR(3X), -\fBcurs_outopts\fR(3X), \fBcurs_mouse\fR(3X), \fBcurs_move\fR(3X), +\fBcurs_outopts\fR(3X), \fBcurs_refresh\fR(3X), \fBcurs_variables\fR(3X), \fBresizeterm\fR(3X). diff --git a/man/curs_getstr.3x b/man/curs_getstr.3x index d9bed59..4a1cc89 100644 --- a/man/curs_getstr.3x +++ b/man/curs_getstr.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getstr.3x,v 1.29 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_getstr.3x,v 1.33 2021/05/22 21:36:35 tom Exp $ .TH curs_getstr 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -53,21 +53,21 @@ .SH SYNOPSIS \fB#include <curses.h>\fR .sp -\fBint getstr(char *str);\fR +\fBint getstr(char *\fP\fIstr\fP\fB);\fR .br -\fBint getnstr(char *str, int n);\fR +\fBint getnstr(char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint wgetstr(WINDOW *win, char *str);\fR +\fBint wgetstr(WINDOW *\fP\fIwin\fP\fB, char *\fP\fIstr\fP\fB);\fR .br -\fBint wgetnstr(WINDOW *win, char *str, int n);\fR -.br -\fBint mvgetstr(int y, int x, char *str);\fR +\fBint wgetnstr(WINDOW *\fP\fIwin\fP\fB, char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR +.sp +\fBint mvgetstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB);\fR .br -\fBint mvwgetstr(WINDOW *win, int y, int x, char *str);\fR +\fBint mvwgetstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB);\fR .br -\fBint mvgetnstr(int y, int x, char *str, int n);\fR +\fBint mvgetnstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint mvwgetnstr(WINDOW *, int y, int x, char *str, int n);\fR +\fBint mvwgetnstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR .br .SH DESCRIPTION The function \fBgetstr\fR is equivalent to a series of calls to \fBgetch\fR, @@ -80,19 +80,29 @@ The resulting value is placed in the area pointed to by the character pointer \fIstr\fR, followed by a NUL. .PP -\fBwgetnstr\fR reads at most \fIn\fR characters, thus preventing a possible +The \fBgetnstr\fR function reads +from the \fIstdscr\fR default window. +The other functions, such as \fBwgetnstr\fP, +read from the window given as a parameter. +.PP +\fBgetnstr\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. +The user's \fIerase\fP and \fIkill\fP characters are interpreted: +.bP +The \fIerase\fP character (e.g., \fB^H\fP) erases the character +at the end of the buffer, moving the cursor to the left. +.IP +If \fIkeypad\fP mode is on for the window, +\fBKEY_LEFT\fR and \fBKEY_BACKSPACE\fR +are both considered equivalent to the user's erase character. +.bP +The \fIkill\fP character (e.g., \fB^U\fP) erases the entire buffer, +leaving the cursor at the beginning of the buffer. .PP Characters input are echoed only if \fBecho\fR is currently on. In that case, @@ -187,7 +197,50 @@ which the \fBsysconf\fP function may provide. If neither \fBLINE_MAX\fP or \fBsysconf\fP is available, ncurses uses the POSIX value for \fBLINE_MAX\fP (a 2048 byte limit). In either case, it reserves a byte for the terminating NUL. +.PP +Although \fBgetnstr\fP is equivalent to a series of calls to \fBgetch\fP, +it also makes changes to the curses modes to allow simple editing of +the input buffer: +.bP +\fBgetnstr\fP saves the current value of the \fBnl\fP, \fBecho\fP, +\fBraw\fP and \fBcbreak\fP modes, and sets +\fBnl\fP, +\fBnoecho\fP, +\fBnoraw\fP, and +\fBcbreak\fP. +.IP +\fBgetnstr\fP handles the echoing of characters, +rather than relying on the caller to set an appropriate mode. +.bP +It also obtains the \fIerase\fP and \fIkill\fP characters +from \fBerasechar\fP and \fBkillchar\fP, respectively. +.bP +On return, \fBgetnstr\fP restores the modes to their previous values. +.PP +Other implementations differ in their treatment of special characters: +.bP +While they may set the \fIecho\fP mode, +other implementations do not modify the \fIraw\fP mode, +They may take the \fIcbreak\fP +mode set by the caller into account when deciding whether to handle +echoing within \fBgetnstr\fP or as a side-effect of the \fBgetch\fP calls. +.bP +The original ncurses (as pcurses in 1986) set \fBnoraw\fP and \fBcbreak\fP +when accepting input for \fBgetnstr\fP. +That may have been done to make function- and cursor-keys work; +it is not necessary with ncurses. +.IP +Since 1995, ncurses has provided signal handlers for INTR and QUIT +(e.g., \fB^C\fP or \fB^\\\fP). +With the \fBnoraw\fP and \fBcbreak\fP settings, +those may catch a signal and stop the program, +where other implementations allow one to enter those characters in the buffer. +.bP +Starting in 2021 (ncurses 6.3), \fBgetnstr\fP sets \fBraw\fP, +rather than \fBnoraw\fP and \fBcbreak\fP for better compatibility with +SVr4-curses, e.g., allowing one to enter a \fB^C\fP into the buffer. .SH SEE ALSO \fBcurses\fR(3X), \fBcurs_getch\fR(3X), +\fBcurs_termattrs\fR(3X), \fBcurs_variables\fR(3X). diff --git a/man/curs_getyx.3x b/man/curs_getyx.3x index d12c064..e6ff670 100644 --- a/man/curs_getyx.3x +++ b/man/curs_getyx.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getyx.3x,v 1.19 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_getyx.3x,v 1.20 2020/10/24 09:38:43 tom Exp $ .TH curs_getyx 3X "" .SH NAME \fBgetyx\fR, @@ -37,13 +37,13 @@ .SH SYNOPSIS \fB#include <curses.h>\fR .sp -\fBvoid getyx(WINDOW *win, int y, int x);\fR +\fBvoid getyx(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR .br -\fBvoid getparyx(WINDOW *win, int y, int x);\fR +\fBvoid getparyx(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR .br -\fBvoid getbegyx(WINDOW *win, int y, int x);\fR +\fBvoid getbegyx(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR .br -\fBvoid getmaxyx(WINDOW *win, int y, int x);\fR +\fBvoid getmaxyx(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR .br .SH DESCRIPTION The \fBgetyx\fR macro places the current cursor position of the given window in diff --git a/man/curs_in_wch.3x b/man/curs_in_wch.3x index a17135e..e267899 100644 --- a/man/curs_in_wch.3x +++ b/man/curs_in_wch.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_in_wch.3x,v 1.9 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_in_wch.3x,v 1.10 2020/10/17 23:19:29 tom Exp $ .TH curs_in_wch 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -43,11 +43,11 @@ .sp \fBint in_wch(cchar_t *\fR\fIwcval\fR\fB);\fR .br +\fBint win_wch(WINDOW *\fR\fIwin\fR\fB, cchar_t *\fR\fIwcval\fR\fB);\fR +.sp \fBint mvin_wch(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwcval\fR\fB);\fR .br \fBint mvwin_wch(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwcval\fR\fB);\fR -.br -\fBint win_wch(WINDOW *\fR\fIwin\fR\fB, cchar_t *\fR\fIwcval\fR\fB);\fR .SH DESCRIPTION These functions extract the complex character and rendition from the current position in the named window into the \fBcchar_t\fR object diff --git a/man/curs_in_wchstr.3x b/man/curs_in_wchstr.3x index 53491a8..4feae48 100644 --- a/man/curs_in_wchstr.3x +++ b/man/curs_in_wchstr.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_in_wchstr.3x,v 1.13 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_in_wchstr.3x,v 1.14 2020/10/17 23:19:44 tom Exp $ .TH curs_in_wchstr 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -57,7 +57,7 @@ \fBint win_wchstr(WINDOW *\fR\fIwin\fR\fB, cchar_t *\fR\fIwchstr\fR\fB);\fR .br \fBint win_wchnstr(WINDOW *\fR\fIwin\fR\fB, cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR -.br +.sp \fBint mvin_wchstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwchstr\fR\fB);\fR .br \fBint mvin_wchnstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR diff --git a/man/curs_inch.3x b/man/curs_inch.3x index a91d963..1f271e3 100644 --- a/man/curs_inch.3x +++ b/man/curs_inch.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_inch.3x,v 1.23 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_inch.3x,v 1.26 2021/06/17 21:30:22 tom Exp $ .TH curs_inch 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -48,11 +48,11 @@ .sp \fBchtype inch(void);\fR .br -\fBchtype winch(WINDOW *win);\fR -.br -\fBchtype mvinch(int y, int x);\fR +\fBchtype winch(WINDOW *\fP\fIwin\fP\fB);\fR +.sp +\fBchtype mvinch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR .br -\fBchtype mvwinch(WINDOW *win, int y, int x);\fR +\fBchtype mvwinch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR .br .SH DESCRIPTION These routines return the character, of type \fBchtype\fR, at the current @@ -100,7 +100,7 @@ could be combined with characters in the window. Reflecting this improvement, the function was altered to return the character combined with all video attributes in a \fBchtype\fP value. .PP -X/Open Curses does not specify +X/Open Curses does not specify the size and layout of attributes, color and character values in \fBchtype\fP; it is implementation-dependent. This implementation uses 8 bits for character values. diff --git a/man/curs_inchstr.3x b/man/curs_inchstr.3x index d352c38..332604e 100644 --- a/man/curs_inchstr.3x +++ b/man/curs_inchstr.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_inchstr.3x,v 1.19 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_inchstr.3x,v 1.21 2020/10/18 00:24:36 tom Exp $ .TH curs_inchstr 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -53,21 +53,21 @@ .SH SYNOPSIS \fB#include <curses.h>\fR .sp -\fBint inchstr(chtype *chstr);\fR +\fBint inchstr(chtype *\fP\fIchstr\fP\fB);\fR .br -\fBint inchnstr(chtype *chstr, int n);\fR +\fBint inchnstr(chtype *\fP\fIchstr\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint winchstr(WINDOW *win, chtype *chstr);\fR +\fBint winchstr(WINDOW *\fP\fIwin\fP\fB, chtype *\fP\fIchstr\fP\fB);\fR .br -\fBint winchnstr(WINDOW *win, chtype *chstr, int n);\fR -.br -\fBint mvinchstr(int y, int x, chtype *chstr);\fR +\fBint winchnstr(WINDOW *\fP\fIwin\fP\fB, chtype *\fP\fIchstr\fP\fB, int \fP\fIn\fP\fB);\fR +.sp +\fBint mvinchstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, chtype *\fP\fIchstr\fP\fB);\fR .br -\fBint mvinchnstr(int y, int x, chtype *chstr, int n);\fR +\fBint mvinchnstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, chtype *\fP\fIchstr\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint mvwinchstr(WINDOW *win, int y, int x, chtype *chstr);\fR +\fBint mvwinchstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, chtype *\fP\fIchstr\fP\fB);\fR .br -\fBint mvwinchnstr(WINDOW *win, int y, int x, chtype *chstr, int n);\fR +\fBint mvwinchnstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, chtype *\fP\fIchstr\fP\fB, int \fP\fIn\fP\fB);\fR .br .SH DESCRIPTION These routines return a NULL-terminated array of \fBchtype\fR quantities, diff --git a/man/curs_initscr.3x b/man/curs_initscr.3x index e0e8ba2..235a5aa 100644 --- a/man/curs_initscr.3x +++ b/man/curs_initscr.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_initscr.3x,v 1.32 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_initscr.3x,v 1.33 2020/10/17 23:20:48 tom Exp $ .TH curs_initscr 3X "" .de bP .ie n .IP \(bu 4 @@ -54,9 +54,9 @@ \fBWINDOW *initscr(void);\fR .br \fBint endwin(void);\fR -.br +.sp \fBbool isendwin(void);\fR -.br +.sp \fBSCREEN *newterm(const char *\fP\fItype\fP\fB, FILE *\fP\fIoutfd\fP\fB, FILE *\fP\fIinfd\fP\fB);\fR .br \fBSCREEN *set_term(SCREEN *\fP\fInew\fP\fB);\fR diff --git a/man/curs_inopts.3x b/man/curs_inopts.3x index 3422c6b..d346017 100644 --- a/man/curs_inopts.3x +++ b/man/curs_inopts.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_inopts.3x,v 1.29 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_inopts.3x,v 1.33 2020/12/05 19:38:18 Benno.Schulenberg Exp $ .TH curs_inopts 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -44,12 +44,14 @@ \fBintrflush\fR, \fBkeypad\fR, \fBmeta\fR, +\fBnl\fR, +\fBnonl\fR, \fBnodelay\fR, \fBnotimeout\fR, \fBraw\fR, \fBnoraw\fR, -\fBnoqiflush\fR, \fBqiflush\fR, +\fBnoqiflush\fR, \fBtimeout\fR, \fBwtimeout\fR, \fBtypeahead\fR \- \fBcurses\fR input options @@ -61,36 +63,40 @@ \fBint cbreak(void);\fR .br \fBint nocbreak(void);\fR -.br +.sp \fBint echo(void);\fR .br \fBint noecho(void);\fR +.sp +\fBint intrflush(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR .br -\fBint halfdelay(int tenths);\fR +\fBint keypad(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR .br -\fBint intrflush(WINDOW *win, bool bf);\fR +\fBint meta(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR .br -\fBint keypad(WINDOW *win, bool bf);\fR +\fBint nodelay(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR .br -\fBint meta(WINDOW *win, bool bf);\fR -.br -\fBint nodelay(WINDOW *win, bool bf);\fR +\fBint notimeout(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR +.sp +\fBint nl(void);\fR .br +\fBint nonl(void);\fR +.sp \fBint raw(void);\fR .br \fBint noraw(void);\fR -.br -\fBvoid noqiflush(void);\fR -.br +.sp \fBvoid qiflush(void);\fR .br -\fBint notimeout(WINDOW *win, bool bf);\fR -.br -\fBvoid timeout(int delay);\fR +\fBvoid noqiflush(void);\fR +.sp +\fBint halfdelay(int \fP\fItenths\fP\fB);\fR .br -\fBvoid wtimeout(WINDOW *win, int delay);\fR +\fBvoid timeout(int \fP\fIdelay\fP\fB);\fR .br -\fBint typeahead(int fd);\fR +\fBvoid wtimeout(WINDOW *\fP\fIwin\fP\fB, int \fP\fIdelay\fP\fB);\fR +.sp +\fBint typeahead(int \fP\fIfd\fP\fB);\fR .br .SH DESCRIPTION The \fBncurses\fP library provides several functions which let an application @@ -102,7 +108,7 @@ windows. An application must apply these to each window, if the same behavior is needed. .\" -.SS cbreak +.SS cbreak/nocbreak Normally, the tty driver buffers typed characters until a newline or carriage return is typed. The \fBcbreak\fR routine disables line buffering and @@ -194,14 +200,20 @@ If the terminfo capabilities \fBsmm\fR \fBTRUE\fR) is called and \fBrmm\fR is sent when \fBmeta\fR(\fIwin\fR, \fBFALSE\fR) is called. .\" +.SS nl/nonl +.PP +The \fBnl\fR and \fBnonl\fR routines control whether the underlying display +device translates the return key into newline on input. +.\" .SS nodelay .PP The \fBnodelay\fR option causes \fBgetch\fR to be a non-blocking call. If no input is ready, \fBgetch\fR returns \fBERR\fR. If disabled (\fIbf\fR is \fBFALSE\fR), \fBgetch\fR waits until a key is pressed. +.SS notimeout .PP -While interpreting an input escape sequence, \fBwgetch\fR(3X) sets a timer +When interpreting an escape sequence, \fBwgetch\fR(3X) sets a timer while waiting for the next character. If \fBnotimeout(\fR\fIwin\fR, \fBTRUE\fR) is called, then \fBwgetch\fR does not set a timer. @@ -222,7 +234,7 @@ The behavior of the BREAK key depends on other bits in the tty driver that are not set by \fBcurses\fR. .\" -.SS noqiflush +.SS qiflush/noqiflush .PP When the \fBnoqiflush\fR routine is used, normal flush of input and output queues associated with the \fBINTR\fR, \fBQUIT\fR and @@ -292,9 +304,17 @@ 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 +For best portability, set \fBecho \fPor \fBnoecho\fP explicitly just after initialization, even if your program remains in cooked mode. .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 chose to do so, on the theory that a programmer requesting +raw input wants a clean (ideally 8-bit clean) connection that the operating +system will not alter. +.PP When \fBkeypad\fP is first enabled, ncurses loads the key-definitions for the current terminal description. If the terminal description includes extended string capabilities, @@ -331,9 +351,20 @@ and if a capability's value is the same as a previously-loaded key definition, the later definition is the one used. .SH NOTES -Note that \fBecho\fR, \fBnoecho\fR, \fBhalfdelay\fR, \fBintrflush\fR, -\fBmeta\fR, \fBnodelay\fR, \fBnotimeout\fR, \fBnoqiflush\fR, -\fBqiflush\fR, \fBtimeout\fR, and \fBwtimeout\fR may be macros. +Note that +\fBecho\fR, +\fBnoecho\fR, +\fBhalfdelay\fR, +\fBintrflush\fR, +\fBmeta\fR, +\fBnl\fR, +\fBnonl\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 diff --git a/man/curs_ins_wch.3x b/man/curs_ins_wch.3x index 69731f6..9b19a28 100644 --- a/man/curs_ins_wch.3x +++ b/man/curs_ins_wch.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_ins_wch.3x,v 1.8 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_ins_wch.3x,v 1.10 2020/10/18 00:22:21 tom Exp $ .TH curs_ins_wch 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -43,11 +43,11 @@ .sp \fBint ins_wch(const cchar_t *\fR\fIwch\fR\fB);\fR .br -\fBint wins_wch(WINDOW *\fR\fIwin, const cchar_t *\fR\fIwch\fR\fB);\fR -.br -\fBint mvins_wch(int \fR\fIy, int \fR\fIx, const cchar_t *\fR\fIwch\fR\fB);\fR +\fBint wins_wch(WINDOW *\fR\fIwin\fP\fB, const cchar_t *\fR\fIwch\fR\fB);\fR +.sp +\fBint mvins_wch(int \fR\fIy\fP\fB, int \fR\fIx\fP\fB, const cchar_t *\fR\fIwch\fR\fB);\fR .br -\fBint mvwins_wch(WINDOW *\fR\fIwin, int \fR\fIy, int \fR\fIx, const cchar_t *\fR\fIwch\fR\fB);\fR +\fBint mvwins_wch(WINDOW *\fR\fIwin\fP\fB, int \fR\fIy\fP\fB, int \fR\fIx\fP\fB, const cchar_t *\fR\fIwch\fR\fB);\fR .SH DESCRIPTION These routines, insert the complex character \fIwch\fR with rendition before the character under the cursor. diff --git a/man/curs_ins_wstr.3x b/man/curs_ins_wstr.3x index 2a89ff1..76c44fb 100644 --- a/man/curs_ins_wstr.3x +++ b/man/curs_ins_wstr.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_ins_wstr.3x,v 1.10 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_ins_wstr.3x,v 1.11 2020/10/17 23:21:25 tom Exp $ .TH curs_ins_wstr 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -57,7 +57,7 @@ \fBint wins_wstr(WINDOW *\fR\fIwin\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR .br \fBint wins_nwstr(WINDOW *\fR\fIwin\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR -.br +.sp \fBint mvins_wstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR .br \fBint mvins_nwstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR diff --git a/man/curs_insch.3x b/man/curs_insch.3x index 4642caa..1b4e3ee 100644 --- a/man/curs_insch.3x +++ b/man/curs_insch.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_insch.3x,v 1.17 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_insch.3x,v 1.19 2020/10/18 00:21:39 tom Exp $ .TH curs_insch 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -41,13 +41,13 @@ .SH SYNOPSIS \fB#include <curses.h>\fR .sp -\fBint insch(chtype ch);\fR +\fBint insch(chtype \fP\fIch\fP\fB);\fR .br -\fBint winsch(WINDOW *win, chtype ch);\fR -.br -\fBint mvinsch(int y, int x, chtype ch);\fR +\fBint winsch(WINDOW *\fP\fIwin\fP\fB, chtype \fP\fIch\fP\fB);\fR +.sp +\fBint mvinsch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, chtype \fP\fIch\fP\fB);\fR .br -\fBint mvwinsch(WINDOW *win, int y, int x, chtype ch);\fR +\fBint mvwinsch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, chtype \fP\fIch\fP\fB);\fR .br .SH DESCRIPTION These routines insert the character \fIch\fR before the character under the diff --git a/man/curs_insstr.3x b/man/curs_insstr.3x index b3147ed..a4c8c62 100644 --- a/man/curs_insstr.3x +++ b/man/curs_insstr.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2019,2020 Thomas E. Dickey * +.\" Copyright 2019-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_insstr.3x,v 1.24 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_insstr.3x,v 1.27 2021/06/17 21:26:02 tom Exp $ .TH curs_insstr 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -45,21 +45,21 @@ .SH SYNOPSIS \fB#include <curses.h>\fR .br -\fBint insstr(const char *str);\fR +\fBint insstr(const char *\fP\fIstr\fP\fB);\fR .br -\fBint insnstr(const char *str, int n);\fR +\fBint insnstr(const char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint winsstr(WINDOW *win, const char *str);\fR +\fBint winsstr(WINDOW *\fP\fIwin\fP\fB, const char *\fP\fIstr\fP\fB);\fR .br -\fBint winsnstr(WINDOW *win, const char *str, int n);\fR +\fBint winsnstr(WINDOW *\fP\fIwin\fP\fB, const char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR +.sp +\fBint mvinsstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const char *\fP\fIstr\fP\fB);\fR .br -\fBint mvinsstr(int y, int x, const char *str);\fR +\fBint mvinsnstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint mvinsnstr(int y, int x, const char *str, int n);\fR +\fBint mvwinsstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const char *\fP\fIstr\fP\fB);\fR .br -\fBint mvwinsstr(WINDOW *win, int y, int x, const char *str);\fR -.br -\fBint mvwinsnstr(WINDOW *win, int y, int x, const char *str, int n);\fR +\fBint mvwinsnstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR .br .SH DESCRIPTION These routines insert a character string @@ -94,7 +94,7 @@ Note that all but \fBwinsnstr\fR may be macros. These functions are described in the XSI Curses standard, Issue 4, which adds const qualifiers to the arguments. .LP -The Single Unix Specification, Version 2 states that +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. diff --git a/man/curs_instr.3x b/man/curs_instr.3x index 4423106..7cc4b4b 100644 --- a/man/curs_instr.3x +++ b/man/curs_instr.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_instr.3x,v 1.20 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_instr.3x,v 1.22 2020/10/18 00:18:27 tom Exp $ .TH curs_instr 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -49,21 +49,21 @@ .SH SYNOPSIS \fB#include <curses.h>\fR .sp -\fBint instr(char *str);\fR +\fBint instr(char *\fP\fIstr\fP\fB);\fR .br -\fBint innstr(char *str, int n);\fR +\fBint innstr(char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint winstr(WINDOW *win, char *str);\fR +\fBint winstr(WINDOW *\fP\fIwin\fP\fB, char *\fP\fIstr\fP\fB);\fR .br -\fBint winnstr(WINDOW *win, char *str, int n);\fR -.br -\fBint mvinstr(int y, int x, char *str);\fR +\fBint winnstr(WINDOW *\fP\fIwin\fP\fB, char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR +.sp +\fBint mvinstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB);\fR .br -\fBint mvinnstr(int y, int x, char *str, int n);\fR +\fBint mvinnstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR .br -\fBint mvwinstr(WINDOW *win, int y, int x, char *str);\fR +\fBint mvwinstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB);\fR .br -\fBint mvwinnstr(WINDOW *win, int y, int x, char *str, int n);\fR +\fBint mvwinnstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR .br .SH DESCRIPTION These routines return a string of characters in \fIstr\fR, extracted starting diff --git a/man/curs_inwstr.3x b/man/curs_inwstr.3x index 1b44a64..b3899c4 100644 --- a/man/curs_inwstr.3x +++ b/man/curs_inwstr.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_inwstr.3x,v 1.13 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_inwstr.3x,v 1.14 2020/10/17 23:22:11 tom Exp $ .TH curs_inwstr 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -53,7 +53,7 @@ \fBint winwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, wchar_t *\fR\fIwstr\fR\fB);\fR .br \fBint winnwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR -.br +.sp \fBint mvinwstr(\fR\fBint \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIwstr\fR\fB);\fR .br \fBint mvinnwstr(\fR\fBint \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR diff --git a/man/curs_kernel.3x b/man/curs_kernel.3x index 2d89d1a..a4e6c80 100644 --- a/man/curs_kernel.3x +++ b/man/curs_kernel.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_kernel.3x,v 1.28 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_kernel.3x,v 1.29 2020/10/17 23:22:35 tom Exp $ .ie \n(.g .ds `` \(lq .el .ds `` `` .ie \n(.g .ds '' \(rq @@ -59,19 +59,19 @@ \fBint def_prog_mode(void);\fR .br \fBint def_shell_mode(void);\fR -.br +.sp \fBint reset_prog_mode(void);\fR .br \fBint reset_shell_mode(void);\fR -.br +.sp \fBint resetty(void);\fR .br \fBint savetty(void);\fR -.br +.sp \fBvoid getsyx(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR .br \fBvoid setsyx(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR -.br +.sp \fBint ripoffline(int \fP\fIline\fP\fB, int (*\fP\fIinit\fP\fB)(WINDOW *, int));\fR .br \fBint curs_set(int \fP\fIvisibility\fP\fB);\fR diff --git a/man/curs_legacy.3x b/man/curs_legacy.3x index b73a6be..c2eb86b 100644 --- a/man/curs_legacy.3x +++ b/man/curs_legacy.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_legacy.3x,v 1.10 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_legacy.3x,v 1.12 2020/10/18 00:16:04 tom Exp $ .de bP .ie n .IP \(bu 4 .el .IP \(bu 2 @@ -38,23 +38,23 @@ curs_legacy \- get \fBcurses\fP cursor and window coordinates, attributes .SH SYNOPSIS \fB#include <curses.h>\fP .sp -\fBint getattrs(const WINDOW *win);\fP -.br -\fBint getbegx(const WINDOW *win);\fP -.br -\fBint getbegy(const WINDOW *win);\fP -.br -\fBint getcurx(const WINDOW *win);\fP -.br -\fBint getcury(const WINDOW *win);\fP +\fBint getattrs(const WINDOW *\fP\fIwin\fP\fB);\fP +.sp +\fBint getbegx(const WINDOW *\fP\fIwin\fP\fB);\fP .br -\fBint getmaxx(const WINDOW *win);\fP +\fBint getbegy(const WINDOW *\fP\fIwin\fP\fB);\fP +.sp +\fBint getcurx(const WINDOW *\fP\fIwin\fP\fB);\fP .br -\fBint getmaxy(const WINDOW *win);\fP +\fBint getcury(const WINDOW *\fP\fIwin\fP\fB);\fP +.sp +\fBint getmaxx(const WINDOW *\fP\fIwin\fP\fB);\fP .br -\fBint getparx(const WINDOW *win);\fP +\fBint getmaxy(const WINDOW *\fP\fIwin\fP\fB);\fP +.sp +\fBint getparx(const WINDOW *\fP\fIwin\fP\fB);\fP .br -\fBint getpary(const WINDOW *win);\fP +\fBint getpary(const WINDOW *\fP\fIwin\fP\fB);\fP .br .SH DESCRIPTION These legacy functions are simpler to use than the X/Open Curses functions: diff --git a/man/curs_memleaks.3x b/man/curs_memleaks.3x index 06a95ed..59bd3e8 100644 --- a/man/curs_memleaks.3x +++ b/man/curs_memleaks.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2019,2020 Thomas E. Dickey * +.\" Copyright 2019-2020,2021 Thomas E. Dickey * .\" Copyright 2008-2010,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_memleaks.3x,v 1.8 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_memleaks.3x,v 1.11 2021/01/02 23:47:51 tom Exp $ .TH curs_memleaks 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -36,31 +36,32 @@ .na .hy 0 .SH NAME -\fB_nc_freeall\fP, -\fB_nc_free_and_exit\fP, -\fB_nc_free_tinfo\fP \- \fBcurses\fR memory-leak checking +\fBexit_curses\fP, +\fBexit_terminfo\fP \- \fBcurses\fR memory-leak checking .ad .hy .SH SYNOPSIS \fB#include <curses.h>\fR +.br +\fBvoid exit_curses(int \fP\fIcode\fP\fB);\fR .sp -\fBvoid exit_curses(int);\fR +\fB#include <term.h>\fR .br -\fBvoid exit_terminfo(int);\fR +\fBvoid exit_terminfo(int \fP\fIcode\fP\fB);\fR .sp -/* deprecated */ +/* deprecated (intentionally not declared in curses.h or term.h) */ .br \fBvoid _nc_freeall(void);\fR .br -\fBvoid _nc_free_and_exit(int);\fR +\fBvoid _nc_free_and_exit(int \fP\fIcode\fP\fB);\fR .br -\fBvoid _nc_free_tinfo(int);\fR +\fBvoid _nc_free_tinfo(int \fP\fIcode\fP\fB);\fR .SH DESCRIPTION These functions are used to simplify analysis of memory leaks in the ncurses library. .PP Any implementation of curses must not free the memory associated with -a screen, since (even after calling \fBendwin\fP), it must be available +a screen, since (even after calling \fBendwin\fP(3X)), it must be available for use in the next call to \fBrefresh\fP(3X). There are also chunks of memory held for performance reasons. That makes it hard to analyze curses applications for memory leaks. diff --git a/man/curs_mouse.3x b/man/curs_mouse.3x index 775bc33..c18be3f 100644 --- a/man/curs_mouse.3x +++ b/man/curs_mouse.3x @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_mouse.3x,v 1.52 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_mouse.3x,v 1.53 2020/10/17 23:25:08 tom Exp $ .ie \n(.g .ds `` \(lq .el .ds `` `` .ie \n(.g .ds '' \(rq @@ -76,21 +76,20 @@ .fi .PP \fBbool has_mouse(void);\fR -.br +.sp \fBint getmouse(MEVENT *\fP\fIevent\fP\fB);\fR .br \fBint ungetmouse(MEVENT *\fP\fIevent\fP\fB);\fR -.br +.sp \fBmmask_t mousemask(mmask_t \fP\fInewmask\fP\fB, mmask_t *\fP\fIoldmask\fP\fB);\fR -.br +.sp \fBbool wenclose(const WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR -.br +.sp \fBbool mouse_trafo(int* \fP\fIpY\fP\fB, int* \fP\fIpX\fP\fB, bool \fP\fIto_screen\fP\fB);\fR .br -\fBbool wmouse_trafo(const WINDOW* \fP\fIwin\fP\fB, int* \fP\fIpY\fP\fB, int* \fP\fIpX\fP\fB,\fR -.br - \fBbool \fP\fIto_screen\fP\fB);\fR -.br +\fBbool wmouse_trafo(const WINDOW* \fP\fIwin\fP\fB,\fR + \fBint* \fP\fIpY\fP\fB, int* \fP\fIpX\fP\fB, bool \fP\fIto_screen\fP\fB);\fR +.sp \fBint mouseinterval(int \fP\fIerval\fP\fB);\fR .br .SH DESCRIPTION diff --git a/man/curs_move.3x b/man/curs_move.3x index e710452..e0c1bf5 100644 --- a/man/curs_move.3x +++ b/man/curs_move.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_move.3x,v 1.18 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_move.3x,v 1.19 2020/10/24 09:39:41 tom Exp $ .TH curs_move 3X "" .na .hy 0 @@ -39,9 +39,9 @@ .SH SYNOPSIS \fB#include <curses.h>\fR .sp -\fBint move(int y, int x);\fR +\fBint move(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR .br -\fBint wmove(WINDOW *win, int y, int x);\fR +\fBint wmove(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR .br .SH DESCRIPTION These routines move the cursor associated with the window to line \fIy\fR and diff --git a/man/curs_opaque.3x b/man/curs_opaque.3x index 855d31e..1d0cb55 100644 --- a/man/curs_opaque.3x +++ b/man/curs_opaque.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_opaque.3x,v 1.14 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_opaque.3x,v 1.15 2020/10/24 09:41:22 tom Exp $ .TH curs_opaque 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -56,35 +56,35 @@ .SH SYNOPSIS \fB#include <curses.h>\fR .sp -\fBbool is_cleared(const WINDOW *win);\fR +\fBbool is_cleared(const WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBbool is_idcok(const WINDOW *win);\fR +\fBbool is_idcok(const WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBbool is_idlok(const WINDOW *win);\fR +\fBbool is_idlok(const WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBbool is_immedok(const WINDOW *win);\fR +\fBbool is_immedok(const WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBbool is_keypad(const WINDOW *win);\fR +\fBbool is_keypad(const WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBbool is_leaveok(const WINDOW *win);\fR +\fBbool is_leaveok(const WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBbool is_nodelay(const WINDOW *win);\fR +\fBbool is_nodelay(const WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBbool is_notimeout(const WINDOW *win);\fR +\fBbool is_notimeout(const WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBbool is_pad(const WINDOW *win);\fR +\fBbool is_pad(const WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBbool is_scrollok(const WINDOW *win);\fR +\fBbool is_scrollok(const WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBbool is_subwin(const WINDOW *win);\fR +\fBbool is_subwin(const WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBbool is_syncok(const WINDOW *win);\fR +\fBbool is_syncok(const WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBWINDOW * wgetparent(const WINDOW *win);\fR +\fBWINDOW * wgetparent(const WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBint wgetdelay(const WINDOW *win);\fR +\fBint wgetdelay(const WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBint wgetscrreg(const WINDOW *win, int *top, int *bottom);\fR +\fBint wgetscrreg(const WINDOW *\fP\fIwin\fP\fB, int *\fP\fItop\fP\fB, int *\fP\fIbottom\fP\fB);\fR .br .SH DESCRIPTION This implementation provides functions which return properties diff --git a/man/curs_outopts.3x b/man/curs_outopts.3x index b3e4608..e4e7421 100644 --- a/man/curs_outopts.3x +++ b/man/curs_outopts.3x @@ -27,10 +27,14 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_outopts.3x,v 1.30 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_outopts.3x,v 1.33 2020/10/03 22:04:09 tom Exp $ .TH curs_outopts 3X "" .na .hy 0 +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. .SH NAME \fBclearok\fR, \fBidlok\fR, @@ -39,9 +43,7 @@ \fBleaveok\fR, \fBsetscrreg\fR, \fBwsetscrreg\fR, -\fBscrollok\fR, -\fBnl\fR, -\fBnonl\fR \- \fBcurses\fR output options +\fBscrollok\fR \- \fBcurses\fR output options .ad .hy .SH SYNOPSIS @@ -57,17 +59,14 @@ .br \fBint leaveok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR .br +\fBint scrollok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR +.sp \fBint setscrreg(int \fP\fItop\fP\fB, int \fP\fIbot\fP\fB);\fR .br \fBint wsetscrreg(WINDOW *\fP\fIwin\fP\fB, int \fP\fItop\fP\fB, int \fP\fIbot\fP\fB);\fR .br -\fBint scrollok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR -.br -\fBint nl(void);\fR -.br -\fBint nonl(void);\fR -.br .SH DESCRIPTION +.PP These routines set options that change the style of output within \fBcurses\fR. All options are initially \fBFALSE\fR, unless otherwise stated. @@ -121,7 +120,18 @@ The \fBleaveok\fR option allows the cursor to be left wherever the update happens to leave it. It is useful for applications where the cursor is not used, since it reduces the need for cursor motions. -.SS setscrreg +.SS scrollok +.PP +The \fBscrollok\fR option controls what happens when the cursor of a window is +moved off the edge of the window or scrolling region, either as a result of a +newline action on the bottom line, or typing the last character of the last +line. +If disabled, (\fIbf\fR is \fBFALSE\fR), the cursor is left on the bottom +line. +If enabled, (\fIbf\fR is \fBTRUE\fR), the window is scrolled up one line +(Note that to get the physical scrolling effect on the terminal, it is +also necessary to call \fBidlok\fR). +.SS setscrreg/wsetscrreg .PP The \fBsetscrreg\fR and \fBwsetscrreg\fR routines allow the application programmer to set a software scrolling region in a window. @@ -140,30 +150,6 @@ terminal, like that in the VT100. If \fBidlok\fR is enabled and the terminal has either a scrolling region or insert/delete line capability, they will probably be used by the output routines.) -.SS scrollok -.PP -The \fBscrollok\fR option controls what happens when the cursor of a window is -moved off the edge of the window or scrolling region, either as a result of a -newline action on the bottom line, or typing the last character of the last -line. -If disabled, (\fIbf\fR is \fBFALSE\fR), the cursor is left on the bottom -line. -If enabled, (\fIbf\fR is \fBTRUE\fR), the window is scrolled up one line -(Note that to get the physical scrolling effect on the terminal, it is -also necessary to call \fBidlok\fR). -.SS nl, nonl -.PP -The \fBnl\fR and \fBnonl\fR routines control whether the underlying display -device translates the return key into newline on input, and whether it -translates newline into return and line-feed on output (in either case, the -call \fBaddch('\\n')\fR does the equivalent of return and line feed on the -\fIvirtual screen\fP). -Initially, these translations do occur. -If you disable them -using \fBnonl\fR, \fBcurses\fR will be able to make better use of the line-feed -capability, resulting in faster cursor motion. -Also, \fBcurses\fR will then be -able to detect the return key. .SH RETURN VALUE The functions \fBsetscrreg\fR and \fBwsetscrreg\fR return \fBOK\fR upon success and \fBERR\fR upon failure. @@ -172,15 +158,12 @@ return \fBOK\fR. .PP X/Open Curses does not define any error conditions. .PP -In this implementation, those functions that have a window pointer -will return an error if the window pointer is null. -.RS -.TP 5 -.B wclrtoeol -returns an error -if the cursor position is about to wrap. -.TP 5 -.B wsetscrreg +In this implementation, +.bP +those functions that have a window pointer +will return an error if the window pointer is null +.bP +\fBwsetscrreg\fP returns an error if the scrolling region limits extend outside the window. .RE .PP @@ -190,19 +173,23 @@ 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 will not alter. +From the outset, ncurses used \fBnl\fP/\fBnonl\fP to control the conversion +of newlines to carriage return/line-feed on output as well as input. +XSI Curses documents only the use of these functions for input. +This difference arose from converting the \fIpcurses\fP source +(which used \fBioctl\fP calls with the \fBsgttyb\fP structure) +to termios (i.e., the POSIX terminal interface). +In the former, both input and output were controlled via a single +option \fBCRMOD\fP, +while the latter separates these features. +Because that conversion interferes with output optimization, +\fBnl\fP/\fBnonl\fP were amended after ncurses 6.2 +to eliminate their effect on output. .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. +This will not work under ncurses. .PP Earlier System V curses implementations specified that with \fBscrollok\fR enabled, any window modification triggering a scroll also forced a physical @@ -216,8 +203,12 @@ made invisible as a side-effect of \fBleaveok\fR. SVr4 curses documentation does this, but the code does not. Use \fBcurs_set\fR to make the cursor invisible. .SH NOTES -Note that \fBclearok\fR, \fBleaveok\fR, \fBscrollok\fR, \fBidcok\fR, \fBnl\fR, -\fBnonl\fR and \fBsetscrreg\fR may be macros. +Note that +\fBclearok\fR, +\fBleaveok\fR, +\fBscrollok\fR, +\fBidcok\fR, and +\fBsetscrreg\fR may be macros. .PP The \fBimmedok\fR routine is useful for windows that are used as terminal emulators. diff --git a/man/curs_print.3x b/man/curs_print.3x index edb5008..8bde817 100644 --- a/man/curs_print.3x +++ b/man/curs_print.3x @@ -27,14 +27,14 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_print.3x,v 1.14 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_print.3x,v 1.16 2020/10/24 09:25:14 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 +\fBint mcprint(char *\fP\fIdata\fP\fB, int \fP\fIlen\fP\fB);\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. @@ -51,7 +51,7 @@ rule of thumb is to sleep for a second after shipping each 80-character line. .SH RETURN VALUE The \fBmcprint\fR function returns \fBERR\fR if the write operation aborted for some reason. -In this case, errno will contain either an error associated +In this case, \fBerrno\fP will contain either an error associated with \fBwrite\fP(2) or one of the following: .TP 5 ENODEV diff --git a/man/curs_printw.3x b/man/curs_printw.3x index 4d060d7..4980517 100644 --- a/man/curs_printw.3x +++ b/man/curs_printw.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_printw.3x,v 1.25 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_printw.3x,v 1.28 2020/10/24 09:22:45 tom Exp $ .TH curs_printw 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -50,19 +50,19 @@ .SH SYNOPSIS \fB#include <curses.h>\fR .sp -\fBint printw(const char *fmt, ...);\fR +\fBint printw(const char *\fP\fIfmt\fP\fB, ...);\fR .br -\fBint wprintw(WINDOW *win, const char *fmt, ...);\fR +\fBint wprintw(WINDOW *\fP\fIwin\fP\fB, const char *\fP\fIfmt\fP\fB, ...);\fR .br -\fBint mvprintw(int y, int x, const char *fmt, ...);\fR +\fBint mvprintw(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const char *\fP\fIfmt\fP\fB, ...);\fR .br -\fBint mvwprintw(WINDOW *win, int y, int x, const char *fmt, ...);\fR +\fBint mvwprintw(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const char *\fP\fIfmt\fP\fB, ...);\fR .br -\fBint vw_printw(WINDOW *win, const char *fmt, va_list varglist);\fR +\fBint vw_printw(WINDOW *\fP\fIwin\fP\fB, const char *\fP\fIfmt\fP\fB, va_list \fP\fIvarglist\fP\fB);\fR .sp /* obsolete */ .br -\fBint vwprintw(WINDOW *win, const char *fmt, va_list varglist);\fR +\fBint vwprintw(WINDOW *\fP\fIwin\fP\fB, const char *\fP\fIfmt\fP\fB, va_list \fP\fIvarglist\fP\fB);\fR .SH DESCRIPTION The \fBprintw\fR, \fBwprintw\fR, \fBmvprintw\fR and \fBmvwprintw\fR routines are analogous to \fBprintf\fR [see \fBprintf\fR(3)]. @@ -70,7 +70,7 @@ In effect, the string that would be output by \fBprintf\fR is output instead as though \fBwaddstr\fR were used on the given window. .PP -The \fBvwprintw\fR and \fBwv_printw\fR routines are analogous +The \fBvwprintw\fR and \fBvw_printw\fR routines are analogous to \fBvprintf\fR [see \fBprintf\fR(3)] and perform a \fBwprintw\fR using a variable argument list. The third argument is a \fBva_list\fR, a pointer to a @@ -89,6 +89,42 @@ It will return an error if the window pointer is null. Functions with a \*(``mv\*('' prefix first perform a cursor movement using \fBwmove\fP, and return an error if the position is outside the window, or if the window pointer is null. +.SH HISTORY +While \fBprintw\fP was implemented in 4BSD, +it was unused until 4.2BSD (which used it in games). +That early version of curses was before the ANSI C standard. +It did not use <varargs.h>, though that was available. +In 1991 (a couple of years after SVr4 was generally available, +and after the C standard was published), +other developers updated the library, +using <stdarg.h> internally in 4.4BSD curses. +Even with this improvement, +BSD curses did not use function prototypes (or even declare +functions) in the <curses.h> header until 1992. +.PP +SVr2 documented +\fBprintw\fP, +\fBwprintw\fP +tersely as \*(``printf on \fIstdscr\fP\*('' and +tersely as \*(``printf on \fIwin\fP\*('', respectively. +.PP +SVr3 added +\fBmvprintw\fP, and +\fBmvwprintw\fP, with a three-line summary saying that they were analogous +to \fBprintf\fP(3), +explaining that the string which would be output from \fBprintf\fP(3) would +instead be output using \fBwaddstr\fP on the given window. +SVr3 also added \fBvwprintw\fP, saying that the third parameter +is a \fBva_list\fP, defined in <varargs.h>, +and referring the reader to the manual pages for \fIvarargs\fP and +\fIvprintf\fP for detailed descriptions. +.PP +SVr4 added no new variations of \fBprintw\fP, +but provided for using <varargs.h> or <stdarg.h> to define the \fBva_list\fP +type. +.PP +X/Open Curses added \fBvw_printw\fP to replace \fBvwprintw\fP, +stating that its \fBva_list\fP definition requires <stdarg.h>. .SH PORTABILITY In this implementation, \fBvw_printw\fP and \fBvwprintw\fP are equivalent, to support legacy applications. diff --git a/man/curs_refresh.3x b/man/curs_refresh.3x index 765020d..4c4b8e7 100644 --- a/man/curs_refresh.3x +++ b/man/curs_refresh.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_refresh.3x,v 1.21 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_refresh.3x,v 1.22 2020/10/24 09:43:49 tom Exp $ .TH curs_refresh 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -53,15 +53,15 @@ .sp \fBint refresh(void);\fR .br -\fBint wrefresh(WINDOW *win);\fR +\fBint wrefresh(WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBint wnoutrefresh(WINDOW *win);\fR +\fBint wnoutrefresh(WINDOW *\fP\fIwin\fP\fB);\fR .br \fBint doupdate(void);\fR +.sp +\fBint redrawwin(WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBint redrawwin(WINDOW *win);\fR -.br -\fBint wredrawln(WINDOW *win, int beg_line, int num_lines);\fR +\fBint wredrawln(WINDOW *\fP\fIwin\fP\fB, int \fP\fIbeg_line\fP\fB, int \fP\fInum_lines\fP\fB);\fR .br .SH DESCRIPTION .SS refresh/wrefresh diff --git a/man/curs_scanw.3x b/man/curs_scanw.3x index 9407ae6..1de9ad8 100644 --- a/man/curs_scanw.3x +++ b/man/curs_scanw.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_scanw.3x,v 1.26 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_scanw.3x,v 1.28 2020/10/24 09:29:26 tom Exp $ .TH curs_scanw 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -46,19 +46,19 @@ .SH SYNOPSIS \fB#include <curses.h>\fR .sp -\fBint scanw(const char *fmt, ...);\fR +\fBint scanw(const char *\fP\fIfmt\fP\fB, ...);\fR .br -\fBint wscanw(WINDOW *win, const char *fmt, ...);\fR +\fBint wscanw(WINDOW *\fP\fIwin\fP\fB, const char *\fP\fIfmt\fP\fB, ...);\fR .br -\fBint mvscanw(int y, int x, const char *fmt, ...);\fR +\fBint mvscanw(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const char *\fP\fIfmt\fP\fB, ...);\fR .br -\fBint mvwscanw(WINDOW *win, int y, int x, const char *fmt, ...);\fR -.br -\fBint vw_scanw(WINDOW *win, const char *fmt, va_list varglist);\fR +\fBint mvwscanw(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const char *\fP\fIfmt\fP\fB, ...);\fR +.sp +\fBint vw_scanw(WINDOW *\fP\fIwin\fP\fB, const char *\fP\fIfmt\fP\fB, va_list \fP\fIvarglist\fP\fB);\fR .sp /* obsolete */ .br -\fBint vwscanw(WINDOW *win, const char *fmt, va_list varglist);\fR +\fBint vwscanw(WINDOW *\fP\fIwin\fP\fB, const char *\fP\fIfmt\fP\fB, va_list \fP\fIvarglist\fP\fB);\fR .SH DESCRIPTION The \fBscanw\fR, \fBwscanw\fR and \fBmvscanw\fR routines are analogous to \fBscanf\fR [see \fBscanf\fR(3)]. @@ -83,6 +83,44 @@ which were mapped in the call. Functions with a \*(``mv\*('' prefix first perform a cursor movement using \fBwmove\fP, and return an error if the position is outside the window, or if the window pointer is null. +.SH HISTORY +While \fBscanw\fP was implemented in 4BSD, +none of the BSD releases used it until 4.4BSD (in a game). +That early version of curses was before the ANSI C standard. +It did not use <varargs.h>, though that was available. +In 1991 (a couple of years after SVr4 was generally available, +and after the C standard was published), +other developers updated the library, +using <stdarg.h> internally in 4.4BSD curses. +Even with this improvement, +BSD curses did not use function prototypes (or even declare +functions) in the <curses.h> header until 1992. +.PP +SVr2 documented +\fBscanw\fP, +\fBwscanw\fP +tersely as \*(``scanf through \fIstdscr\fP\*('' and +tersely as \*(``scanf through \fIwin\fP\*('', respectively. +.PP +SVr3 added +\fBmvscanw\fP, and +\fBmvwscanw\fP, with a three-line summary saying that they were analogous +to \fBscanf\fP(3), +explaining that the string which would be output from \fBscanf\fP(3) would +instead be output using \fBwaddstr\fP on the given window. +SVr3 also added \fBvwscanw\fP, saying that the third parameter +is a \fBva_list\fP, defined in <varargs.h>, +and referring the reader to the manual pages for \fIvarargs\fP and +\fIvprintf\fP for detailed descriptions. +(Because the SVr3 documentation does not mention \fIvscanf\fP, +that reference to \fIvprintf\fP may not be an error). +.PP +SVr4 added no new variations of \fBscanw\fP, +but provided for using <varargs.h> or <stdarg.h> to define the \fBva_list\fP +type. +.PP +X/Open Curses added \fBvw_scanw\fP to replace \fBvwscanw\fP, +stating that its \fBva_list\fP definition requires <stdarg.h>. .SH PORTABILITY In this implementation, \fBvw_scanw\fP and \fBvwscanw\fP are equivalent, to support legacy applications. diff --git a/man/curs_scr_dump.3x b/man/curs_scr_dump.3x index 01c61b2..faa6144 100644 --- a/man/curs_scr_dump.3x +++ b/man/curs_scr_dump.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_scr_dump.3x,v 1.15 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_scr_dump.3x,v 1.17 2021/10/20 22:37:48 tom Exp $ .TH curs_scr_dump 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -49,23 +49,27 @@ .SH SYNOPSIS \fB#include <curses.h>\fR .sp -\fBint scr_dump(const char *filename);\fR +\fBint scr_dump(const char *\fP\fIfilename\fP\fB);\fR .br -\fBint scr_restore(const char *filename);\fR +\fBint scr_restore(const char *\fP\fIfilename\fP\fB);\fR .br -\fBint scr_init(const char *filename);\fR +\fBint scr_init(const char *\fP\fIfilename\fP\fB);\fR .br -\fBint scr_set(const char *filename);\fR +\fBint scr_set(const char *\fP\fIfilename\fP\fB);\fR .br .SH DESCRIPTION +.SS scr_dump +.PP The \fBscr_dump\fR routine dumps the current contents of the \fIvirtual screen\fP to the file \fIfilename\fR. +.SS scr_restore .PP The \fBscr_restore\fR routine sets the \fIvirtual screen\fP to the contents of \fIfilename\fR, which must have been written using \fBscr_dump\fR. The next call to \fBdoupdate\fR restores the \fIphysical screen\fP to the way it looked in the dump file. +.SS scr_init .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 @@ -82,6 +86,7 @@ The data is declared invalid if the terminfo capabilities \fBrmcup\fR and \fBnrrmc\fR exist, also .bP if the terminal has been written to since the preceding \fBscr_dump\fR call. +.SS scr_set .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 diff --git a/man/curs_scroll.3x b/man/curs_scroll.3x index 50d2a99..d9e45f2 100644 --- a/man/curs_scroll.3x +++ b/man/curs_scroll.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_scroll.3x,v 1.18 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_scroll.3x,v 1.19 2020/10/24 09:45:48 tom Exp $ .TH curs_scroll 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -44,11 +44,11 @@ .SH SYNOPSIS \fB#include <curses.h>\fR .sp -\fBint scroll(WINDOW *win);\fR -.br -\fBint scrl(int n);\fR +\fBint scroll(WINDOW *\fP\fIwin\fP\fB);\fR +.sp +\fBint scrl(int \fP\fIn\fP\fB);\fR .br -\fBint wscrl(WINDOW *win, int n);\fR +\fBint wscrl(WINDOW *\fP\fIwin\fP\fB, int \fP\fIn\fP\fB);\fR .br .SH DESCRIPTION The \fBscroll\fR routine scrolls the window up one line. diff --git a/man/curs_slk.3x b/man/curs_slk.3x index 9eb2dfb..d09d6c7 100644 --- a/man/curs_slk.3x +++ b/man/curs_slk.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_slk.3x,v 1.36 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_slk.3x,v 1.38 2021/06/17 21:26:02 tom Exp $ .TH curs_slk 3X "" .de bP .ie n .IP \(bu 4 @@ -63,6 +63,8 @@ .sp \fBint slk_set(int \fP\fIlabnum\fP\fB, const char *\fP\fIlabel\fP\fB, int \fP\fIfmt\fP\fB);\fR .br +/* extension */ +.br \fBint slk_wset(int \fP\fIlabnum\fP\fB, const wchar_t *\fP\fIlabel\fP\fB, int \fP\fIfmt\fP\fB);\fR .sp \fBchar *slk_label(int \fP\fIlabnum\fP\fB);\fR @@ -192,7 +194,7 @@ It has an effect only if soft labels are simulated on the bottom line of the screen. .PP Because \fBslk_color\fR accepts only \fBshort\fP (signed 16-bit integer) values, -this implementation provides +this implementation provides \fBextended_slk_color\fR which accepts an integer value, e.g., 32-bits. . .SH RETURN VALUE @@ -270,7 +272,7 @@ X/Open Curses added these: .PP X/Open Curses documents the \fIopts\fP argument as reserved for future use, saying that it must be null. -This implementation +This implementation uses that parameter in ABI 6 for the functions which have a color-pair parameter to support extended color pairs. .PP diff --git a/man/curs_sp_funcs.3x b/man/curs_sp_funcs.3x index d524c0e..c192e02 100644 --- a/man/curs_sp_funcs.3x +++ b/man/curs_sp_funcs.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 2010-2015,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_sp_funcs.3x,v 1.18 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_sp_funcs.3x,v 1.25 2021/05/22 22:12:46 tom Exp $ .TH curs_sp_funcs 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -41,268 +41,281 @@ curs_sp_funcs \- \fBcurses\fR screen-pointer extension .hy .SH SYNOPSIS \fB#include <curses.h>\fR -\fB#include <term.h>\fR .nf .sp -\fBint alloc_pair_sp(SCREEN*, int, int);\fR -.br -\fBint assume_default_colors_sp(SCREEN*, int, int);\fR -.br -\fBint baudrate_sp(SCREEN*);\fR -.br -\fBint beep_sp(SCREEN*);\fR +\fBint alloc_pair_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIfg\fP\fB, int \fP\fIbg\fP\fB);\fR .br -\fBbool can_change_color_sp(SCREEN*);\fR +\fBint assume_default_colors_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIfg\fP\fB, int \fP\fIbg\fP\fB);\fR .br -\fBint cbreak_sp(SCREEN*);\fR +\fBint baudrate_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint color_content_sp(SCREEN*, short, short*, short*, short*);\fR +\fBint beep_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint curs_set_sp(SCREEN*, int);\fR +\fBbool can_change_color_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint define_key_sp(SCREEN*, const char *, int);\fR +\fBint cbreak_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint def_prog_mode_sp(SCREEN*);\fR +\fBint color_content_sp(SCREEN* \fP\fIsp\fP\fB, short \fP\fIcolor\fP\fB, short* \fP\fIr\fP\fB, short* \fP\fIg\fP\fB, short* \fP\fIb\fP\fB);\fR .br -\fBint def_shell_mode_sp(SCREEN*);\fR +\fBint curs_set_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIvisibility\fP);\fR .br -\fBint delay_output_sp(SCREEN*, int);\fR +\fBint def_prog_mode_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint doupdate_sp(SCREEN*);\fR +\fBint def_shell_mode_sp(SCREEN* \fP\fIsp\fP\fB);\fR +.sp +\fBint define_key_sp(SCREEN* \fP\fIsp\fP\fB, const char * \fP\fIdefinition\fP\fB, int \fP\fIkeycode\fP\fB);\fR .br -\fBint echo_sp(SCREEN*);\fR +\fBint delay_output_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIms\fP\fB);\fR .br -\fBint endwin_sp(SCREEN*);\fR +\fBint doupdate_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBchar erasechar_sp(SCREEN*);\fR +\fBint echo_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint extended_color_content_sp(SCREEN *, int, int *, int *, int *);\fR +\fBint endwin_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint extended_pair_content_sp(SCREEN*, int, int *, int *);\fR +\fBchar erasechar_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint extended_slk_color_sp(SCREEN*, int);\fR +\fBint erasewchar_sp(SCREEN* \fP\fIsp\fP\fB, wchar_t *\fP\fIch\fP\fB);\fR .br -\fBvoid filter_sp(SCREEN*);\fR +\fBint extended_color_content_sp(SCREEN * \fP\fIsp\fP\fB, int \fP\fIcolor\fP\fB, int * \fP\fIr\fP\fB, int * \fP\fIg\fP\fB, int * \fP\fIb\fP\fB);\fR .br -\fBint find_pair_sp(SCREEN*, int, int);\fR +\fBint extended_pair_content_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIpair\fP\fB, int * \fP\fIfg\fP\fB, int * \fP\fIbg\fP\fB);\fR .br -\fBint free_pair_sp(SCREEN*, int);\fR +\fBint extended_slk_color_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIpair\fP\fB);\fR +.sp +\fBvoid filter_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint flash_sp(SCREEN*);\fR +\fBint find_pair_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIfg\fP\fB, int \fP\fIbg\fP\fB);\fR .br -\fBint flushinp_sp(SCREEN*);\fR +\fBint flash_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint get_escdelay_sp(SCREEN*);\fR +\fBint flushinp_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint getmouse_sp(SCREEN*, MEVENT*);\fR +\fBint free_pair_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIpair\fP\fB);\fR .br -\fBWINDOW* getwin_sp(SCREEN*, FILE*);\fR +\fBint get_escdelay_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint halfdelay_sp(SCREEN*, int);\fR +\fBint getmouse_sp(SCREEN* \fP\fIsp\fP\fB, MEVENT* \fP\fBevent\fP\fB);\fR .br -\fBbool has_colors_sp(SCREEN*);\fR +\fBWINDOW* getwin_sp(SCREEN* \fP\fIsp\fP\fB, FILE* \fP\fIfilep\fP\fB);\fR .br -\fBbool has_ic_sp(SCREEN*);\fR +\fBint halfdelay_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fItenths\fP\fB);\fR .br -\fBbool has_il_sp(SCREEN*);\fR +\fBbool has_colors_sp(SCREEN* \fP\fIsp\fP\fB);\fR +.sp +\fBbool has_ic_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint has_key_sp(SCREEN*, int);\fR +\fBbool has_il_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBbool has_mouse_sp(SCREEN*);\fR +\fBint has_key_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIch\fP\fB);\fR .br -\fBint init_color_sp(SCREEN*, short, short, short, short);\fR +\fBbool has_mouse_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint init_extended_color_sp(SCREEN*, int, int, int, int);\fR +\fBint init_color_sp(SCREEN* \fP\fIsp\fP\fB, short \fP\fIcolor\fP\fB, short \fP\fIr\fP\fB, short \fP\fIg\fP\fB, short \fP\fIb\fP\fB);\fR .br -\fBint init_extended_pair_sp(SCREEN*, int, int, int);\fR +\fBint init_extended_color_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIcolor\fP\fB, int \fP\fIr\fP\fB, int \fP\fIg\fP\fB, int \fP\fIb\fP\fB);\fR .br -\fBint init_pair_sp(SCREEN*, short, short, short);\fR +\fBint init_extended_pair_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIpair\fP\fB, int \fP\fIfg\fP\fB, int \fP\fIbg\fP\fB);\fR .br -\fBint intrflush_sp(SCREEN*, WINDOW*, bool);\fR +\fBint init_pair_sp(SCREEN* \fP\fIsp\fP\fB, short \fP\fIpair\fP\fB, short \fP\fIfg\fP\fB, short \fP\fIbg\fP\fB);\fR .br -\fBbool isendwin_sp(SCREEN*);\fR +\fBint intrflush_sp(SCREEN* \fP\fIsp\fP\fB, WINDOW* \fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR .br -\fBbool is_term_resized_sp(SCREEN*, int, int);\fR +\fBbool is_term_resized_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIlines\fP\fB, int \fP\fIcolumns\fP\fB);\fR +.sp +\fBbool isendwin_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBchar* keybound_sp(SCREEN*, int, int);\fR +\fBint key_defined_sp(SCREEN* \fP\fIsp\fP\fB, const char *\fP\fIdefinition\fP\fB);\fR .br -\fBint key_defined_sp(SCREEN*, const char *);\fR +\fBchar* keybound_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIkeycode\fP\fB, int \fP\fIcount\fP\fB);\fR .br -\fBNCURSES_CONST char * keyname_sp(SCREEN*, int);\fR +\fBNCURSES_CONST char * keyname_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIc\fP\fB);\fR .br -\fBint keyok_sp(SCREEN*, int, bool);\fR +\fBint keyok_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIkeycode\fP\fB, bool \fP\fIenable\fP\fB);\fR .br -\fBchar killchar_sp(SCREEN*);\fR +\fBchar killchar_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBchar* longname_sp(SCREEN*);\fR +\fBint killwchar_sp(SCREEN* \fP\fIsp\fP\fB, wchar_t *\fP\fIch\fP\fB);\fR .br -\fBint mcprint_sp(SCREEN*, char *, int);\fR +\fBchar* longname_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint mouseinterval_sp(SCREEN*, int);\fR +\fBint mcprint_sp(SCREEN* \fP\fIsp\fP\fB, char *\fP\fIdata\fP\fB, int \fP\fIlen\fP\fB);\fR .br -\fBmmask_t mousemask_sp(SCREEN*, mmask_t, mmask_t *);\fR +\fBint mouseinterval_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIerval\fP\fB);\fR +.sp +\fBmmask_t mousemask_sp(SCREEN* \fP\fIsp\fP\fB, mmask_t \fP\fInewmask\fP\fB, mmask_t *\fP\fIoldmask\fP\fB);\fR .br -\fBint mvcur_sp(SCREEN*, int, int, int, int);\fR +\fBint mvcur_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIoldrow\fP\fB, int \fP\fIoldcol\fP\fB, int \fP\fInewrow\fP\fB, int \fP\fInewcol\fP\fB);\fR .br -\fBint napms_sp(SCREEN*, int);\fR +\fBint napms_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIms\fP\fB);\fR .br -\fBWINDOW* newpad_sp(SCREEN*, int, int);\fR +\fBWINDOW* newpad_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fInrows\fP\fB, int \fP\fIncols\fP\fB);\fR .br \fBSCREEN* new_prescr(void);\fR .br -\fBSCREEN* newterm_sp(SCREEN*, const char *, FILE *, FILE *);\fR -.br -\fBWINDOW* newwin_sp(SCREEN*, int, int, int, int);\fR -.br -\fBint nl_sp(SCREEN*);\fR -.br -\fBint nocbreak_sp(SCREEN*);\fR -.br -\fBint noecho_sp(SCREEN*);\fR -.br -\fBvoid nofilter_sp(SCREEN*);\fR +\fBSCREEN* newterm_sp(SCREEN* \fP\fIsp\fP\fB, const char *\fP\fItype\fP\fB, FILE *\fP\fIoutfd\fP\fB, FILE *\fP\fIinfd\fP\fB);\fR .br -\fBint nonl_sp(SCREEN*);\fR +\fBWINDOW* newwin_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fInlines\fP\fB, int \fP\fIncols\fP\fB, int \fP\fIbegin_y\fP\fB, int \fP\fIbegin_x\fP\fB);\fR .br -\fBvoid noqiflush_sp(SCREEN*);\fR +\fBint nl_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint noraw_sp(SCREEN*);\fR +\fBint nocbreak_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint pair_content_sp(SCREEN*, short, short*, short*);\fR -.br -\fBvoid qiflush_sp(SCREEN*);\fR -.br -\fBint raw_sp(SCREEN*);\fR +\fBint noecho_sp(SCREEN* \fP\fIsp\fP\fB);\fR +.sp +\fBvoid nofilter_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint reset_prog_mode_sp(SCREEN*);\fR +\fBint nonl_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint reset_shell_mode_sp(SCREEN*);\fR +\fBvoid noqiflush_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint resetty_sp(SCREEN*);\fR +\fBint noraw_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint resize_term_sp(SCREEN*, int, int);\fR +\fBint pair_content_sp(SCREEN* \fP\fIsp\fP\fB, short \fP\fIpair\fP\fB, short* \fP\fIfg\fP\fB, short* \fP\fIbg\fP\fB);\fR .br -\fBint resizeterm_sp(SCREEN*, int, int);\fR +\fBvoid qiflush_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint restartterm_sp(SCREEN*, NCURSES_CONST char*, int, int *);\fR +\fBint raw_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint ripoffline_sp(SCREEN*, int, int (*)(WINDOW*, int));\fR +\fBint reset_prog_mode_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint savetty_sp(SCREEN*);\fR +\fBvoid reset_color_pairs_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint scr_init_sp(SCREEN*, const char *);\fR +\fBint reset_shell_mode_sp(SCREEN* \fP\fIsp\fP\fB);\fR +.sp +\fBint resetty_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint scr_restore_sp(SCREEN*, const char *);\fR +\fBint resize_term_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIlines\fP\fB, int \fP\fIcolumns\fP\fB);\fR .br -\fBint scr_set_sp(SCREEN*, const char *);\fR +\fBint resizeterm_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIlines\fP\fB, int \fP\fIcolumns\fP\fB);\fR .br -\fBTERMINAL* set_curterm_sp(SCREEN*, TERMINAL*);\fR +\fBint ripoffline_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIline\fP\fB, int (*\fP\fIinit\fP\fB)(WINDOW* \fP\fIwin\fP\fB, int \fP\fIfmt\fP\fB));\fR .br -\fBint set_escdelay_sp(SCREEN*, int);\fR +\fBint savetty_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint set_tabsize_sp(SCREEN*, int);\fR +\fBint scr_init_sp(SCREEN* \fP\fIsp\fP\fB, const char *\fP\fIfilename\fP\fB);\fR .br -\fBint slk_attroff_sp(SCREEN*, const chtype);\fR +\fBint scr_restore_sp(SCREEN* \fP\fIsp\fP\fB, const char *\fP\fIfilename\fP\fB);\fR .br -\fBint slk_attron_sp(SCREEN*, const chtype);\fR +\fBint scr_set_sp(SCREEN* \fP\fIsp\fP\fB, const char *\fP\fIfilename\fP\fB);\fR .br -\fBint slk_attr_set_sp(SCREEN*, const attr_t, short, void*);\fR +\fBint set_escdelay_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIms\fP\fB);\fR .br -\fBint slk_attrset_sp(SCREEN*, const chtype);\fR +\fBint set_tabsize_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIcols\fP\fB);\fR +.sp +\fBint slk_attr_set_sp(SCREEN* \fP\fIsp\fP\fB, const attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void*\fP\fIopts\fP\fB);\fR .br -\fBattr_t slk_attr_sp(SCREEN*);\fR +\fBint slk_attrset_sp(SCREEN* \fP\fIsp\fP\fB, const chtype \fP\fIa\fP\fB);\fR .br -\fBint slk_clear_sp(SCREEN*);\fR +\fBint slk_attroff_sp(SCREEN* \fP\fIsp\fP\fB, const chtype \fP\fIa\fP\fB);\fR .br -\fBint slk_color_sp(SCREEN*, short);\fR +\fBint slk_attron_sp(SCREEN* \fP\fIsp\fP\fB, const chtype \fP\fIa\fP\fB);\fR .br -\fBint slk_init_sp(SCREEN*, int);\fR +\fBattr_t slk_attr_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBchar* slk_label_sp(SCREEN*, int);\fR +\fBint slk_clear_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint slk_noutrefresh_sp(SCREEN*);\fR +\fBint slk_color_sp(SCREEN* \fP\fIsp\fP\fB, short \fP\fIpair\fP\fB);\fR .br -\fBint slk_refresh_sp(SCREEN*);\fR +\fBint slk_init_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIfmt\fP\fB);\fR .br -\fBint slk_restore_sp(SCREEN*);\fR +\fBchar* slk_label_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIlabnum\fP\fB);\fR .br -\fBint slk_set_sp(SCREEN*, int, const char *, int);\fR +\fBint slk_noutrefresh_sp(SCREEN* \fP\fIsp\fP\fB);\fR +.sp +\fBint slk_refresh_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint slk_touch_sp(SCREEN*);\fR +\fBint slk_restore_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint start_color_sp(SCREEN*);\fR +\fBint slk_set_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIlabnum\fP\fB, const char * \fP\fIlabel\fP\fB, int \fP\fIfmt\fP\fB);\fR .br -\fBattr_t term_attrs_sp(SCREEN*);\fR +\fBint slk_touch_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBchtype termattrs_sp(SCREEN*);\fR +\fBint start_color_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBchar* termname_sp(SCREEN*);\fR +\fBattr_t term_attrs_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint typeahead_sp(SCREEN*, int);\fR +\fBchtype termattrs_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBNCURSES_CONST char* unctrl_sp(SCREEN*, chtype);\fR +\fBchar* termname_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBint ungetch_sp(SCREEN*, int);\fR +\fBint typeahead_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIfd\fP\fB);\fR .br -\fBint ungetmouse_sp(SCREEN*,MEVENT *);\fR +\fBint unget_wch_sp(SCREEN* \fP\fIsp\fP\fB, const wchar_t \fP\fIwch\fP\fB);\fR +.sp +\fBint ungetch_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIch\fP\fB);\fR .br -\fBint unget_wch_sp(SCREEN*, const wchar_t);\fR +\fBint ungetmouse_sp(SCREEN* \fP\fIsp\fP\fB,MEVENT * \fP\fBevent\fP\fB);\fR .br -\fBint use_default_colors_sp(SCREEN*);\fR +\fBint use_default_colors_sp(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBvoid use_env_sp(SCREEN*, bool);\fR +\fBvoid use_env_sp(SCREEN* \fP\fIsp\fP\fB, bool \fP\fIbf\fP\fB);\fR .br -\fBvoid use_tioctl_sp(SCREEN *, bool);\fR +\fBint use_legacy_coding_sp(SCREEN* \fP\fIsp\fP\fB, int \fP\fIlevel\fP\fB);\fR .br -\fBint use_legacy_coding_sp(SCREEN*, int);\fR +\fBvoid use_tioctl_sp(SCREEN *\fP\fIsp\fP\fB, bool \fP\fIbf\fP\fB);\fR .br -\fBint vid_attr_sp(SCREEN*, attr_t, short, void *);\fR +\fBint vid_attr_sp(SCREEN* \fP\fIsp\fP\fB, attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void * \fP\fIopts\fP\fB);\fR .br -\fBint vidattr_sp(SCREEN*, chtype);\fR +\fBint vid_puts_sp(SCREEN* \fP\fIsp\fP\fB, attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void * \fP\fIopts\fP\fB, NCURSES_SP_OUTC \fP\fIputc\fP\fB);\fR .br -\fBint vid_puts_sp(SCREEN*, attr_t, short, void *, NCURSES_SP_OUTC);\fR +\fBint vidattr_sp(SCREEN* \fP\fIsp\fP\fB, chtype \fP\fIattrs\fP\fB);\fR .br -\fBint vidputs_sp(SCREEN*, chtype, NCURSES_SP_OUTC);\fR +\fBint vidputs_sp(SCREEN* \fP\fIsp\fP\fB, chtype \fP\fIattrs\fP\fB, NCURSES_SP_OUTC \fP\fIputc\fP\fB);\fR .br -\fBwchar_t* wunctrl_sp(SCREEN*, cchar_t *);\fR +\fBwchar_t* wunctrl_sp(SCREEN* \fP\fIsp\fP\fB, cchar_t *\fP\fIch\fP\fB);\fR .sp \fB#include <form.h>\fR .sp -\fBFORM* new_form_sp(SCREEN*, FIELD **);\fR +\fBFORM* new_form_sp(SCREEN* \fP\fIsp\fP\fB, FIELD **\fP\fIfields\fP\fB);\fR .sp \fB#include <menu.h>\fR .sp -\fBMENU* new_menu_sp(SCREEN*, ITEM **);\fR +\fBMENU* new_menu_sp(SCREEN* \fP\fIsp\fP\fB, ITEM **\fP\fIitems\fP\fB);\fR .sp \fB#include <panel.h>\fR .sp -\fBPANEL* ceiling_panel(SCREEN*);\fR +\fBPANEL* ceiling_panel(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBPANEL* ground_panel(SCREEN*);\fR +\fBPANEL* ground_panel(SCREEN* \fP\fIsp\fP\fB);\fR .br -\fBvoid update_panels_sp(SCREEN*);\fR +\fBvoid update_panels_sp(SCREEN* \fP\fIsp\fP\fB);\fR .sp \fB#include <term.h>\fR .sp -\fBint del_curterm_sp(SCREEN*, TERMINAL *);\fR +\fBint del_curterm_sp(SCREEN* \fP\fIsp\fP\fB, TERMINAL *\fP\fIoterm\fP\fB);\fR .br -\fBint putp_sp(SCREEN*, const char *);\fR +\fBint putp_sp(SCREEN* \fP\fIsp\fP\fB, const char *\fP\fIstr\fP\fB);\fR .br -\fBint tgetflag_sp(SCREEN*, const char *);\fR +\fBint restartterm_sp(SCREEN* \fP\fIsp\fP\fB, NCURSES_CONST char*\fP\fIterm\fP\fB, int \fP\fIfiledes\fP\fB, int *\fP\fIerrret\fP\fB);\fR .br -\fBint tgetent_sp(SCREEN*, char *, const char *);\fR +\fBTERMINAL* set_curterm_sp(SCREEN* \fP\fIsp\fP\fB, TERMINAL*\fP\fInterm\fP\fB);\fR .br -\fBint tgetnum_sp(SCREEN*, const char *);\fR +\fBint tgetent_sp(SCREEN* \fP\fIsp\fP\fB, char *\fP\fIbp\fP\fB, const char *\fP\fIname\fP\fB);\fR .br -\fBchar* tgetstr_sp(SCREEN*, const char *, char **);\fR +\fBint tgetflag_sp(SCREEN* \fP\fIsp\fP\fB, const char *\fP\fIcapname\fP\fB);\fR .br -\fBint tigetflag_sp(SCREEN*, const char *);\fR +\fBint tgetnum_sp(SCREEN* \fP\fIsp\fP\fB, const char *\fP\fIcapname\fP\fB);\fR .br -\fBint tigetnum_sp(SCREEN*, const char *);\fR +\fBchar* tgetstr_sp(SCREEN* \fP\fIsp\fP\fB, const char *\fP\fIcapname\fP\fB, char **\fP\fIarea\fP\fB);\fR .br -\fBchar* tigetstr_sp(SCREEN*, const char *);\fR +\fBchar* tgoto_sp(SCREEN* \fP\fIsp\fP\fB, const char *\fP\fIcapname\fP\fB, int \fP\fIcol\fP\fB, int \fP\fIrow\fP\fB);\fR .br -\fBint tputs_sp(SCREEN*, const char *, int, NCURSES_SP_OUTC);\fR +\fBint tigetflag_sp(SCREEN* \fP\fIsp\fP\fB, const char *\fP\fIcapname\fP\fB);\fR +.br +\fBint tigetnum_sp(SCREEN* \fP\fIsp\fP\fB, const char *\fP\fIcapname\fP\fB);\fR +.br +\fBchar* tigetstr_sp(SCREEN* \fP\fIsp\fP\fB, const char *\fP\fIcapname\fP\fB);\fR +.br +/* may instead use 9 long parameters */ +.br +\fBchar* tparm_sp(SCREEN* \fP\fIsp\fP\fB, const char *\fP\fIstr\fP\fB, ...);\fR +.br +\fBint tputs_sp(SCREEN* \fP\fIsp\fP\fB, const char *\fP\fIstr\fP\fB, int \fP\fIaffcnt\fP\fB, NCURSES_SP_OUTC \fP\fIputc\fP\fB);\fR +.sp +\fB#include <unctrl.h>\fR +.sp +\fBNCURSES_CONST char* unctrl_sp(SCREEN* \fP\fIsp\fP\fB, chtype \fP\fIc\fP\fB);\fR .ad .br .SH DESCRIPTION diff --git a/man/curs_termcap.3x b/man/curs_termcap.3x index e7422b4..94bed5b 100644 --- a/man/curs_termcap.3x +++ b/man/curs_termcap.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2017,2018 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_termcap.3x,v 1.43 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_termcap.3x,v 1.49 2021/04/03 21:17:09 tom Exp $ .TH curs_termcap 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -50,7 +50,7 @@ \fBtgetnum\fR, \fBtgetstr\fR, \fBtgoto\fR, -\fBtputs\fR \- direct \fBcurses\fR interface to the terminfo capability database +\fBtputs\fR \- \fBcurses\fR emulation of termcap .ad .hy .SH SYNOPSIS @@ -66,22 +66,22 @@ .br \fBextern @NCURSES_OSPEED@ ospeed;\fR .sp -\fBint tgetent(char *bp, const char *name);\fR +\fBint tgetent(char *\fP\fIbp\fP\fB, const char *\fP\fIname\fP\fB);\fR .br -\fBint tgetflag(const char *id);\fR +\fBint tgetflag(const char *\fP\fIid\fP\fB);\fR .br -\fBint tgetnum(const char *id);\fR +\fBint tgetnum(const char *\fP\fIid\fP\fB);\fR .br -\fBchar *tgetstr(const char *id, char **area);\fR +\fBchar *tgetstr(const char *\fP\fIid\fP\fB, char **\fP\fIarea\fP\fB);\fR .br -\fBchar *tgoto(const char *cap, int col, int row);\fR +\fBchar *tgoto(const char *\fP\fIcap\fP\fB, int \fP\fIcol\fP\fB, int \fP\fIrow\fP\fB);\fR .br -\fBint tputs(const char *str, int affcnt, int (*putc)(int));\fR +\fBint tputs(const char *\fP\fIstr\fP\fB, int \fP\fIaffcnt\fP\fB, int (*\fP\fIputc\fP\fB)(int));\fR .br .SH DESCRIPTION These routines are included as a conversion aid for programs that use the \fItermcap\fR library. -Their parameters are the same and the +Their parameters are the same, but the routines are emulated using the \fIterminfo\fR database. Thus, they can only be used to query the capabilities of entries for which a @@ -218,16 +218,28 @@ if the string is indeed terminfo-style by looking for "%p" parameters or appear to be terminfo). .PP Because terminfo conventions for representing padding in string capabilities -differ from termcap's, \fBtputs("50");\fR will put out a literal \*(``50\*('' rather -than busy-waiting for 50 milliseconds. -Cope with it. +differ from termcap's, +users can be surprised: +.bP +\fBtputs("50")\fR in a terminfo system will put out a literal \*(``50\*('' +rather than busy-waiting for 50 milliseconds. +.bP +However, if ncurses is configured to support termcap, +it may also have been configured to support the BSD-style padding. +.IP +In that case, \fBtputs\fP inspects strings passed to it, +looking for digits at the beginning of the string. +.IP +\fBtputs("50")\fR in a termcap system may wait for 50 milliseconds +rather than put out a literal \*(``50\*('' .PP Note that termcap has nothing analogous to terminfo's \fBsgr\fR string. -One consequence of this is that termcap applications assume \fRme\fR +One consequence of this is that termcap applications assume \fBme\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 +.SS Standards These functions are provided for supporting legacy applications, and should not be used in new programs: .bP @@ -246,6 +258,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. +.SS Compatibility with BSD Termcap .PP External variables are provided for support of certain termcap applications. However, termcap applications' use of those variables is poorly documented, @@ -270,10 +283,67 @@ This implementation disallows matches against single-character capability names. .bP This implementation disallows matches by the termcap interface against extended capability names which are longer than two characters. +.PP +The BSD termcap function \fBtgetent\fP returns the text of a termcap +entry in the buffer passed as an argument. +This library (like other terminfo implementations) does not store +terminal descriptions as text. +It sets the buffer contents to a null-terminated string. +.SS Other Compatibility +This library includes a termcap.h header, +for compatibility with other implementations. +But the header is rarely used because the other implementations +are not strictly compatible. +.PP +The original BSD termcap (through 4.3BSD) had no header file which +gave function prototypes, because that was a feature of ANSI C. +BSD termcap was written several years before C was standardized. +However, there were two different termcap.h header files in the BSD +sources: +.bP +One was used internally by the \fIjove\fP editor in 2BSD through 4.4BSD. +It defined global symbols for the termcap variables which it used. +.bP +The other appeared in 4.4BSD Lite Release 2 (mid-1993) +as part of \fIlibedit\fP (also known as the \fIeditline\fP library). +The CSRG source history shows that this was added in mid-1992. +The \fIlibedit\fP header file was used internally, +as a convenience for compiling the \fIeditline\fP library. +It declared function prototypes, but no global variables. +.PP +The header file from \fIlibedit\fP was added to NetBSD's termcap +library in mid-1994. +.PP +Meanwhile, GNU termcap was under development, starting in 1990. +The first release (termcap 1.0) in 1991 included a termcap.h header. +The second release (termcap 1.1) in September 1992 modified the +header to use \fBconst\fP for the function prototypes in the header +where one would expect the parameters to be read-only. +This was a difference versus the original BSD termcap. +The prototype for \fBtputs\fP also differed, +but in that instance, it was \fIlibedit\fP which differed from BSD termcap. +.PP +A copy of GNU termcap 1.3 was bundled with \fIbash\fP in mid-1993, +to support the \fIreadline\fP library. +.PP +A termcap.h file was provided in ncurses 1.8.1 (November 1993). +That reflected influence by \fIemacs\fP (rather than \fIjove\fP) +and GNU termcap: +.bP +it provided declarations for a few global symbols used by \fIemacs\fP +.bP +it provided function prototypes (using \fBconst\fP). +.bP +a prototype for \fBtparam\fP (a GNU termcap feature) was provided. +.PP +Later (in mid-1996) the \fBtparam\fP function was removed from ncurses. +As a result, there are differences between any of the four implementations, +which must be taken into account by programs which can work with all +termcap library interfaces. .SH SEE ALSO \fBcurses\fR(3X), -\fBterminfo\fR(\*n), +\fBputc\fR(3), \fBterm_variables\fR(3X), -\fBputc\fR(3). +\fBterminfo\fR(\*n). .sp https://invisible-island.net/ncurses/tctest.html diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x index 041c58f..6bb5dc2 100644 --- a/man/curs_terminfo.3x +++ b/man/curs_terminfo.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_terminfo.3x,v 1.64 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_terminfo.3x,v 1.76 2021/09/04 19:58:03 tom Exp $ .TH curs_terminfo 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -46,7 +46,6 @@ \fBputp\fR, \fBrestartterm\fR, \fBset_curterm\fR, -\fBsetterm\fR, \fBsetupterm\fR, \fBtigetflag\fR, \fBtigetnum\fR, @@ -63,7 +62,6 @@ .SH SYNOPSIS .nf \fB#include <curses.h>\fR -.br \fB#include <term.h>\fR .sp \fBTERMINAL *cur_term;\fR @@ -80,8 +78,6 @@ .sp \fBint setupterm(const char *\fR\fIterm\fR\fB, int \fR\fIfiledes\fR\fB, int *\fR\fIerrret\fR\fB);\fR .br -\fBint setterm(const char *\fR\fIterm\fR\fB);\fR -.br \fBTERMINAL *set_curterm(TERMINAL *\fR\fInterm\fR\fB);\fR .br \fBint del_curterm(TERMINAL *\fR\fIoterm\fR\fB);\fR @@ -120,6 +116,14 @@ capabilities, such as programming function keys. For all other functionality, \fBcurses\fR routines are more suitable and their use is recommended. +.PP +None of these functions use (or are aware of) multibyte character strings +such as UTF-8: +.bP +capability names use the POSIX portable character set +.bP +capability string values have no associated encoding; +they are strings of 8-bit characters. .SS Initialization .PP Initially, \fBsetupterm\fR should be called. @@ -227,14 +231,6 @@ Thus, the simplest call is: .sp which uses all the defaults and sends the output to \fBstdout\fR. .RE -.PP -The \fBsetterm\fR routine was replaced by \fBsetupterm\fR. The call: -.sp - \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR -.sp -provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR. -The \fBsetterm\fR routine is provided for BSD compatibility, and -is not recommended for new programs. .\" *************************************************************************** .SS The Terminal State .PP @@ -284,6 +280,12 @@ the prototype expects \fBlong\fP (integer) values. .bP Aside from the \fBset_attributes\fP (\fBsgr\fP) capability, most terminal capabilities require no more than one or two parameters. +.bP +Padding information is ignored by \fBtparm\fP; +it is interpreted by \fBtputs\fP. +.bP +The capability string is null-terminated. +Use \*(``\\200\*('' where an ASCII NUL is needed in the output. .PP \fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI<stdarg.h>\fP rather than a fixed-parameter list. @@ -291,7 +293,10 @@ Its numeric parameters are integers (int) rather than longs. .\" *************************************************************************** .SS Output Functions .PP -The \fBtputs\fR routine applies padding information to the string +The \fBtputs\fR routine applies padding information +(i.e., by interpreting marker embedded in the terminfo capability +such as \*(``$<5>\*('' as 5 milliseconds) +to the string \fIstr\fR and outputs it: .bP The \fIstr\fR parameter must be a terminfo string @@ -340,8 +345,12 @@ this implementation allows \fIopts\fP to be used as a pointer to \fBint\fP, which overrides the \fIpair\fP (\fBshort\fP) argument. .PP The \fBmvcur\fR routine provides low-level cursor motion. -It takes -effect immediately (rather than at the next refresh). +It takes effect immediately (rather than at the next refresh). +.PP +While \fBputp\fR and \fBmvcur\fP are low-level functions which +do not use the high-level curses state, +they are declared in \fB<curses.h>\fP because SystemV did this +(see \fBHISTORY\fP). .\" *************************************************************************** .SS Terminal Capability Functions .PP @@ -385,7 +394,7 @@ These null-terminated arrays contain .bP the short terminfo names (\*(``codes\*(''), .bP -the \fBtermcap\fR names (\*(``names\*('', and +the \fBtermcap\fR names (\*(``names\*(''), and .bP the long terminfo names (\*(``fnames\*('') .PP @@ -433,6 +442,32 @@ It does not detect I/O errors: X/Open states that \fBtputs\fP ignores the return value of the output function \fIputc\fP. .RE +.\" *************************************************************************** +.SS Compatibility macros +This implementation provides a few macros for compatibility with systems +before SVr4 (see \fBHISTORY\fP). +Those include +\fBcrmode\fP, +\fBfixterm\fP, +\fBgettmode\fP, +\fBnocrmode\fP, +\fBresetterm\fP, +\fBsaveterm\fP, and +\fBsetterm\fP. +.PP +In SVr4, those are found in \fB<curses.h>\fP, +but except for \fBsetterm\fR, are likewise macros. +The one function, \fBsetterm\fR, is mentioned in the manual page. +The manual page notes that the \fBsetterm\fR routine +was replaced by \fBsetupterm\fR, stating that the call: +.sp + \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR +.sp +provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR, +and is not recommended for new programs. +This implementation provides each of those symbols +as macros for BSD compatibility, +.\" *************************************************************************** .SH HISTORY .PP SVr2 introduced the terminfo feature. @@ -504,13 +539,13 @@ l l _ _ l l. \fBFunction\fR \fBReplaced by\fP -crmode cbreak -fixterm reset_prog_mode -gettmode N/A -nocrmode nocbreak -resetterm reset_shell_mode -saveterm def_prog_mode -setterm setupterm +crmode cbreak +fixterm reset_prog_mode +gettmode N/A +nocrmode nocbreak +resetterm reset_shell_mode +saveterm def_prog_mode +setterm setupterm .TE .PP SVr3 kept the \fBmvcur\fP, \fBvidattr\fP and \fBvidputs\fP functions, @@ -521,8 +556,14 @@ and handling functions such as \fBvidattr\fP .PP SVr3 introduced the functions for switching between terminal descriptions, e.g., \fBset_curterm\fP. +Some of that was incremental improvements to the SVr2 library: +.bP +The \fBTERMINAL\fP type definition was introduced in SVr3.01, +for the \fBterm\fP structure provided in SVr2. +.bP The various global variables such as \fBboolnames\fP were mentioned -in the programming manual at this point. +in the programming manual at this point, +though the variables were provided in SVr2. .PP SVr4 added the \fBvid_attr\fP and \fBvid_puts\fP functions. .PP diff --git a/man/curs_threads.3x b/man/curs_threads.3x index 95afb87..cb2da61 100644 --- a/man/curs_threads.3x +++ b/man/curs_threads.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_threads.3x,v 1.25 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_threads.3x,v 1.27 2020/12/30 18:28:51 tom Exp $ .TH curs_threads 3X "" .de bP .ie n .IP \(bu 4 @@ -45,16 +45,16 @@ \fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);\fR .br \fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);\fR -.br +.sp \fBint get_escdelay(void);\fR .br -\fBint set_escdelay(int size);\fR +\fBint set_escdelay(int \fP\fIms\fP\fB);\fR .br -\fBint set_tabsize(int size);\fR -.br -\fBint use_screen(SCREEN *scr, NCURSES_SCREEN_CB func, void *data);\fR +\fBint set_tabsize(int \fP\fIcols\fP\fB);\fR +.sp +\fBint use_screen(SCREEN *\fP\fIscr\fP\fB, NCURSES_SCREEN_CB \fP\fIfunc\fP\fB, void *\fP\fIdata\fP\fB);\fR .br -\fBint use_window(WINDOW *win, NCURSES_WINDOW_CB func, void *data);\fR +\fBint use_window(WINDOW *\fP\fIwin\fP\fB, NCURSES_WINDOW_CB \fP\fIfunc\fP\fB, void *\fP\fIdata\fP\fB);\fR .br .SH DESCRIPTION This implementation can be configured to provide rudimentary support diff --git a/man/curs_touch.3x b/man/curs_touch.3x index e532078..8b0ca87 100644 --- a/man/curs_touch.3x +++ b/man/curs_touch.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_touch.3x,v 1.22 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_touch.3x,v 1.24 2021/06/17 21:26:02 tom Exp $ .TH curs_touch 3X "" .na .hy 0 @@ -42,18 +42,18 @@ .hy .SH SYNOPSIS \fB#include <curses.h>\fR +.sp +\fBint touchline(WINDOW *\fP\fIwin\fP\fB, int \fP\fIstart\fP\fB, int \fP\fIcount\fP\fB);\fR +.sp +\fBint touchwin(WINDOW *\fP\fIwin\fP\fB);\fR .br -\fBint touchwin(WINDOW *win);\fR +\fBint wtouchln(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIn\fP\fB, int \fP\fIchanged\fP\fB);\fR +.sp +\fBint untouchwin(WINDOW *\fP\fIwin\fP\fB);\fR +.sp +\fBbool is_linetouched(WINDOW *\fP\fIwin\fP\fB, int \fP\fIline\fP\fB);\fR .br -\fBint touchline(WINDOW *win, int start, int count);\fR -.br -\fBint untouchwin(WINDOW *win);\fR -.br -\fBint wtouchln(WINDOW *win, int y, int n, int changed);\fR -.br -\fBbool is_linetouched(WINDOW *win, int line);\fR -.br -\fBbool is_wintouched(WINDOW *win);\fR +\fBbool is_wintouched(WINDOW *\fP\fIwin\fP\fB);\fR .br .SH DESCRIPTION The \fBtouchwin\fR and \fBtouchline\fR routines throw away all @@ -90,7 +90,7 @@ In this implementation .RS 3 .TP 5 \fBis_linetouched\fP -returns an error +returns an error if the window pointer is null, or if the line number is outside the window. .IP @@ -105,7 +105,7 @@ the \fBERR\fP is provided by a macro named \fBis_linetouched\fP. The actual function returns \fBFALSE\fP when it detects an error. .TP 5 \fBwtouchln\fP -returns an error +returns an error if the window pointer is null, or if the line number is outside the window. .RE diff --git a/man/curs_util.3x b/man/curs_util.3x index 7cee63f..f833803 100644 --- a/man/curs_util.3x +++ b/man/curs_util.3x @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_util.3x,v 1.57 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_util.3x,v 1.60 2020/12/19 22:44:46 tom Exp $ .TH curs_util 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -58,27 +58,27 @@ .SH SYNOPSIS \fB#include <curses.h>\fR .sp -\fBconst char *unctrl(chtype c);\fR +\fBconst char *unctrl(chtype \fP\fIc\fP\fB);\fR .br -\fBwchar_t *wunctrl(cchar_t *c);\fR -.br -\fBconst char *keyname(int c);\fR -.br -\fBconst char *key_name(wchar_t w);\fR +\fBwchar_t *wunctrl(cchar_t *\fP\fIc\fP\fB);\fR +.sp +\fBconst char *keyname(int \fP\fIc\fP\fB);\fR .br +\fBconst char *key_name(wchar_t \fP\fIw\fP\fB);\fR +.sp \fBvoid filter(void);\fR .br \fBvoid nofilter(void);\fR +.sp +\fBvoid use_env(bool \fP\fIf\fP\fB);\fR .br -\fBvoid use_env(bool f);\fR -.br -\fBvoid use_tioctl(bool f);\fR -.br -\fBint putwin(WINDOW *win, FILE *filep);\fR -.br -\fBWINDOW *getwin(FILE *filep);\fR +\fBvoid use_tioctl(bool \fP\fIf\fP\fB);\fR +.sp +\fBint putwin(WINDOW *\fP\fIwin\fP\fB, FILE *\fP\fIfilep\fP\fB);\fR .br -\fBint delay_output(int ms);\fR +\fBWINDOW *getwin(FILE *\fP\fIfilep\fP\fB);\fR +.sp +\fBint delay_output(int \fP\fIms\fP\fB);\fR .br \fBint flushinp(void);\fR .br @@ -344,7 +344,7 @@ the parameter is a 7-bit US\-ASCII code. This is the case that X/Open Curses documented. .bP the parameter is in the range 128\-159, i.e., a C1 control code. -If \fBuse_legacy_coding\fP has been called with a \fB2\fP parameter, +If \fBuse_legacy_coding\fP(3X) has been called with a \fB2\fP parameter, \fBunctrl\fP returns the parameter, i.e., a one-character string with the parameter as the first character. Otherwise, it returns \*(``~@\*('', \*(``~A\*('', etc., @@ -369,14 +369,14 @@ Or they may ignore C1 controls and treat all of the upper-128 codes as printable. This implementation uses 8 bits but does not modify the string to reflect locale. -The \fBuse_legacy_coding\fP function allows the caller to +The \fBuse_legacy_coding\fP(3X) function allows the caller to change the output of \fBunctrl\fP. .PP Likewise, the \fBmeta\fP(3X) function allows the caller to change the output of \fBkeyname\fP, i.e., it determines whether to use the \*(``M\-\*('' prefix for \*(``meta\*('' keys (codes in the range 128 to 255). -Both \fBuse_legacy_coding\fP and \fBmeta\fP succeed only after +Both \fBuse_legacy_coding\fP(3X) and \fBmeta\fP(3X) succeed only after curses is initialized. X/Open Curses does not document the treatment of codes 128 to 159. When treating them as \*(``meta\*('' keys @@ -397,7 +397,6 @@ creating each \fIscreen\fP rather than once only This feature of \fBuse_env\fP is not provided by other implementation of curses. .SH SEE ALSO -\fBlegacy_coding\fR(3X), \fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_inopts\fR(3X), diff --git a/man/curs_variables.3x b/man/curs_variables.3x index cd0c866..25294df 100644 --- a/man/curs_variables.3x +++ b/man/curs_variables.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_variables.3x,v 1.14 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_variables.3x,v 1.15 2020/04/18 14:29:07 tom Exp $ .TH curs_variables 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -112,7 +112,7 @@ i.e., the number of lines. .SS TABSIZE This variable holds the number of columns used by the \fIcurses\fP library when converting a tab character to spaces as it adds the tab to a window -(see curs_addch(3X). +(see \fBcurs_addch\fP(3X). .SS The Current Screen This implementation of curses uses a special window \fBcurscr\fP to record its updates to the terminal screen. diff --git a/man/curs_window.3x b/man/curs_window.3x index 77cbffa..e5ea2aa 100644 --- a/man/curs_window.3x +++ b/man/curs_window.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2020 Thomas E. Dickey * +.\" Copyright 2020,2021 Thomas E. Dickey * .\" Copyright 1998-2015,2016 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,8 +27,12 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_window.3x,v 1.21 2020/02/02 23:34:34 tom Exp $ +.\" $Id: curs_window.3x,v 1.23 2021/06/17 21:11:08 tom Exp $ .TH curs_window 3X "" +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. .na .hy 0 .SH NAME @@ -97,6 +101,29 @@ If either .RE .PP A new full-screen window is created by calling \fBnewwin(0,0,0,0)\fR. +.PP +Regardless of the function used for creating a new window +(e.g., \fBnewwin\fP, \fBsubwin\fP, \fBderwin\fP, \fBnewpad\fP), +rather than a duplicate (with \fBdupwin\fP), +all of the window modes are initialized to the default values. +These functions set window modes after a window is created: +.RS +.na +.PP +idcok, +idlok, +immedok, +keypad, +leaveok, +nodelay, +scrollok, +setscrreg, +syncok, +wbkgdset, +wbkgrndset, and +wtimeout +.RE +.ad .SS delwin .PP Calling \fBdelwin\fR deletes the named window, freeing all memory diff --git a/man/default_colors.3x b/man/default_colors.3x index 2ad7dcd..c1d1bf7 100644 --- a/man/default_colors.3x +++ b/man/default_colors.3x @@ -29,7 +29,7 @@ .\" .\" Author: Thomas E. Dickey 1997,1999,2000,2005 .\" -.\" $Id: default_colors.3x,v 1.29 2020/02/02 23:34:34 tom Exp $ +.\" $Id: default_colors.3x,v 1.31 2020/12/19 21:38:37 tom Exp $ .TH default_colors 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -43,7 +43,7 @@ .sp \fBint use_default_colors(void);\fP .br -\fBint assume_default_colors(int fg, int bg);\fP +\fBint assume_default_colors(int \fP\fIfg\fP\fB, int \fP\fIbg\fP\fB);\fP .SH DESCRIPTION The \fBuse_default_colors\fP and \fBassume_default_colors\fP functions are extensions to the curses library. @@ -137,8 +137,8 @@ Version 7, BSD or System V implementations. It is recommended that any code depending on them be conditioned using NCURSES_VERSION. .SH SEE ALSO -\fBcurs_color\fR(3X), -\fBded\fP(1). +\fBded\fP(1), +\fBcurs_color\fR(3X). .SH AUTHOR Thomas Dickey (from an analysis of the requirements for color xterm for XFree86 3.1.2C, February 1996). diff --git a/man/define_key.3x b/man/define_key.3x index a8d7b47..d0dbe7f 100644 --- a/man/define_key.3x +++ b/man/define_key.3x @@ -29,14 +29,14 @@ .\" .\" Author: Thomas E. Dickey 1997 .\" -.\" $Id: define_key.3x,v 1.17 2020/02/02 23:34:34 tom Exp $ +.\" $Id: define_key.3x,v 1.18 2020/10/24 09:52:54 tom Exp $ .TH define_key 3X "" .SH NAME \fBdefine_key\fP \- define a keycode .SH SYNOPSIS \fB#include <curses.h>\fP .sp -\fBint define_key(const char *definition, int keycode);\fP +\fBint define_key(const char *\fP\fIdefinition\fP\fB, int \fP\fIkeycode\fP\fB);\fP .SH DESCRIPTION This is an extension to the curses library. It permits an application to define keycodes with their corresponding control diff --git a/man/form.3x b/man/form.3x index 2115ddc..685ad71 100644 --- a/man/form.3x +++ b/man/form.3x @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form.3x,v 1.34 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form.3x,v 1.36 2020/12/12 16:34:33 tom Exp $ .TH form 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -79,6 +79,8 @@ rendering of fields already created. . The following table lists each \fBform\fR routine and the name of the manual page on which it is described. +Routines flagged with \*(``*\*('' +are ncurses-specific, not present in SVr4. . .TS l l @@ -115,8 +117,8 @@ form_opts \fBform_opts\fR(3X) form_opts_off \fBform_opts\fR(3X) form_opts_on \fBform_opts\fR(3X) form_page \fBform_page\fR(3X) -form_request_by_name \fBform_requestname\fR(3X) -form_request_name \fBform_requestname\fR(3X) +form_request_by_name \fBform_requestname\fR(3X)* +form_request_name \fBform_requestname\fR(3X)* form_sub \fBform_win\fR(3X) form_term \fBform_hook\fR(3X) form_userptr \fBform_userptr\fR(3X) @@ -158,12 +160,12 @@ set_form_userptr \fBform_userptr\fR(3X) set_form_win \fBform_win\fR(3X) set_max_field \fBform_field_buffer\fR(3X) set_new_page \fBform_new_page\fR(3X) -unfocus_current_field \fBform_page\fR(3X) +unfocus_current_field \fBform_page\fR(3X)* unpost_form \fBform_post\fR(3X) .TE .SH RETURN VALUE Routines that return pointers return \fBNULL\fR on error, -and set errno to the corresponding error-code returned by functions +and set \fBerrno\fP to the corresponding error-code returned by functions returning an integer. Routines that return an integer return one of the following error codes: diff --git a/man/form_cursor.3x b/man/form_cursor.3x index 7fde03c..cb9d1cd 100644 --- a/man/form_cursor.3x +++ b/man/form_cursor.3x @@ -28,14 +28,14 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_cursor.3x,v 1.12 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_cursor.3x,v 1.14 2020/10/18 00:15:29 tom Exp $ .TH form_cursor 3X "" .SH NAME \fBpos_form_cursor\fR \- position a form window cursor .SH SYNOPSIS \fB#include <form.h>\fR -.br -int pos_form_cursor(FORM *form); +.sp +\fBint pos_form_cursor(FORM *\fP\fIform\fP\fB);\fP .br .SH DESCRIPTION The function \fBpos_form_cursor\fR restores the cursor to the position required diff --git a/man/form_data.3x b/man/form_data.3x index 1d14343..8a56692 100644 --- a/man/form_data.3x +++ b/man/form_data.3x @@ -28,17 +28,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_data.3x,v 1.13 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_data.3x,v 1.15 2020/10/18 00:15:00 tom Exp $ .TH form_data 3X "" .SH NAME \fBdata_ahead\fP, \fBdata_behind\fR \- test for off-screen data in given forms .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBbool data_ahead(const FORM *\fP\fIform\fP\fB);\fP .br -bool data_ahead(const FORM *form); -.br -bool data_behind(const FORM *form); +\fBbool data_behind(const FORM *\fP\fIform\fP\fB);\fP .br .SH DESCRIPTION The function \fBdata_ahead\fR tests whether there is off-screen data diff --git a/man/form_driver.3x b/man/form_driver.3x index 64a1e48..9c096f9 100644 --- a/man/form_driver.3x +++ b/man/form_driver.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_driver.3x,v 1.33 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_driver.3x,v 1.35 2020/12/19 21:34:15 tom Exp $ .TH form_driver 3X "" .de bP .ie n .IP \(bu 4 @@ -38,7 +38,7 @@ \fBform_driver_w\fR \- command-processing loop of the form system .SH SYNOPSIS \fB#include <form.h>\fR -.br +.sp \fBint form_driver(FORM *\fP\fIform\fP\fB, int \fP\fIc\fP\fB);\fP .br \fBint form_driver_w(FORM *\fP\fIform\fP\fB, int \fP\fIc\fP\fB, wchar_t \fP\fIwch\fP\fB);\fP @@ -254,9 +254,9 @@ The form driver code saw an unknown request code. .SH SEE ALSO \fBcurses\fR(3X), \fBform\fR(3X), +\fBform_fieldtype\fR(3X), \fBform_field_buffer\fR(3X), \fBform_field_validation\fR(3X), -\fBform_fieldtype\fR(3X), \fBform_variables\fR(3X), \fBgetch\fR(3X). .SH NOTES diff --git a/man/form_field.3x b/man/form_field.3x index 113604d..01ff576 100644 --- a/man/form_field.3x +++ b/man/form_field.3x @@ -28,20 +28,20 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_field.3x,v 1.14 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_field.3x,v 1.17 2020/10/24 09:10:45 tom Exp $ .TH form_field 3X "" .SH NAME \fBform_field\fR \- make and break connections between fields and forms .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBint set_form_fields(FORM *\fP\fIform\fP\fB, FIELD **\fP\fIfields\fP\fB);\fP .br -int set_form_fields(FORM *form, FIELD **fields); +\fBFIELD **form_fields(const FORM *\fP\fIform\fP\fB);\fP .br -FIELD **form_fields(const FORM *form); +\fBint field_count(const FORM *\fP\fIform\fP\fB);\fP .br -int field_count(const FORM *form); -.br -int move_field(FIELD *field, int frow, int fcol); +\fBint move_field(FIELD *\fP\fIfield\fP\fB, int \fP\fIfrow\fP\fB, int \fP\fIfcol\fP\fB);\fP .br .SH DESCRIPTION The function \fBset_form_fields\fR changes the field pointer array of @@ -55,7 +55,7 @@ The function \fBmove_field\fR moves the given field (which must be disconnected) to a specified location on the screen. .SH RETURN VALUE The function \fBform_fields\fR returns a pointer (which may be \fBNULL\fR). -It does not set errno. +It does not set \fBerrno\fP. .PP The function \fBfield_count\fR returns \fBERR\fR if the \fIform\fP parameter is \fBNULL\fP. diff --git a/man/form_field_attributes.3x b/man/form_field_attributes.3x index caeffa3..88778b1 100644 --- a/man/form_field_attributes.3x +++ b/man/form_field_attributes.3x @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_field_attributes.3x,v 1.16 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_field_attributes.3x,v 1.18 2020/10/18 00:14:20 tom Exp $ .TH form_field_attributes 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -38,18 +38,18 @@ \fBform_field_attributes\fR \- color and attribute control for form fields .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBint set_field_fore(FIELD *\fP\fIfield\fP\fB, chtype \fP\fIattr\fP\fB);\fP .br -int set_field_fore(FIELD *field, chtype attr); +\fBchtype field_fore(const FIELD *\fP\fIfield\fP\fB);\fP +.sp +\fBint set_field_back(FIELD *\fP\fIfield\fP\fB, chtype \fP\fIattr\fP\fB);\fP .br -chtype field_fore(const FIELD *field); +\fBchtype field_back(const FIELD *\fP\fIfield\fP\fB);\fP +.sp +\fBint set_field_pad(FIELD *\fP\fIfield\fP\fB, int \fP\fIpad\fP\fB);\fP .br -int set_field_back(FIELD *field, chtype attr); -.br -chtype field_back(const FIELD *field); -.br -int set_field_pad(FIELD *field, int pad); -.br -int field_pad(const FIELD *field); +\fBint field_pad(const FIELD *\fP\fIfield\fP\fB);\fP .br .SH DESCRIPTION The function \fBset_field_fore\fR sets the foreground attribute of diff --git a/man/form_field_buffer.3x b/man/form_field_buffer.3x index 95e963e..98b2e42 100644 --- a/man/form_field_buffer.3x +++ b/man/form_field_buffer.3x @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_field_buffer.3x,v 1.25 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_field_buffer.3x,v 1.27 2020/10/24 09:27:17 tom Exp $ .TH form_field_buffer 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -43,15 +43,15 @@ .SH SYNOPSIS \fB#include <form.h>\fR .sp -int set_field_buffer(FIELD *field, int buf, const char *value); +\fBint set_field_buffer(FIELD *\fP\fIfield\fP\fB, int \fP\fIbuf\fP\fB, const char *\fP\fIvalue\fP\fB);\fP .br -char *field_buffer(const FIELD *field, int buffer); -.br -int set_field_status(FIELD *field, bool status); -.br -bool field_status(const FIELD *field); +\fBchar *field_buffer(const FIELD *\fP\fIfield\fP\fB, int \fP\fIbuffer\fP\fB);\fP +.sp +\fBint set_field_status(FIELD *\fP\fIfield\fP\fB, bool \fP\fIstatus\fP\fB);\fP .br -int set_max_field(FIELD *field, int max); +\fBbool field_status(const FIELD *\fP\fIfield\fP\fB);\fP +.sp +\fBint set_max_field(FIELD *\fP\fIfield\fP\fB, int \fP\fImax\fP\fB);\fP .br .SH DESCRIPTION The function \fBset_field_buffer\fR sets the numbered buffer of the given field @@ -99,7 +99,7 @@ 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: +It sets \fBerrno\fP according to their success: .TP 5 .B E_OK The routine succeeded. diff --git a/man/form_field_info.3x b/man/form_field_info.3x index ba4c82a..556c45b 100644 --- a/man/form_field_info.3x +++ b/man/form_field_info.3x @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_field_info.3x,v 1.17 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_field_info.3x,v 1.18 2020/10/17 23:35:05 tom Exp $ .TH form_field_info 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -38,13 +38,17 @@ \fBdynamic_field_info\fP, \fBfield_info\fR \- retrieve field characteristics .SH SYNOPSIS +.nf \fB#include <form.h>\fR -.br -int field_info(const FIELD *field, int *rows, int *cols, - int *frow, int *fcol, int *nrow, int *nbuf); -.br -int dynamic_field_info(const FIELD *field, int *rows, int *cols, int *max); -.br +.sp +\fBint field_info(const FIELD *\fP\fIfield\fP\fB,\fP + \fBint *\fP\fIrows\fP\fB, int *\fP\fIcols\fP\fB,\fP + \fBint *\fP\fIfrow\fP\fB, int *\fP\fIfcol\fP\fB,\fP + \fBint *\fP\fInrow\fP\fB, int *\fP\fInbuf\fB);\fP +.sp +\fBint dynamic_field_info(const FIELD *\fP\fIfield\fP\fB,\fP + \fBint *\fP\fIrows\fP\fB, int *\fP\fIcols\fP\fB, int *\fImax\fB);\fP +.fi .SH DESCRIPTION The function \fBfield_info\fR returns the sizes and other attributes passed in to the field at its creation time. diff --git a/man/form_field_just.3x b/man/form_field_just.3x index bd3753d..d8fef76 100644 --- a/man/form_field_just.3x +++ b/man/form_field_just.3x @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_field_just.3x,v 1.16 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_field_just.3x,v 1.18 2020/10/18 00:12:55 tom Exp $ .TH form_field_just 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -39,10 +39,10 @@ \fBfield_just\fP \- retrieve field characteristics .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBint set_field_just(FIELD *\fP\fIfield\fP\fB, int \fP\fIjustification\fP\fB);\fP .br -int set_field_just(FIELD *field, int justification); -.br -int field_just(const FIELD *field); +\fBint field_just(const FIELD *\fP\fIfield\fP\fB);\fP .br .SH DESCRIPTION The function \fBset_field_just\fR sets the justification attribute of diff --git a/man/form_field_new.3x b/man/form_field_new.3x index 18ad3b9..1a240d0 100644 --- a/man/form_field_new.3x +++ b/man/form_field_new.3x @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_field_new.3x,v 1.21 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_field_new.3x,v 1.24 2020/10/24 09:09:18 tom Exp $ .TH form_field_new 3X "" .SH NAME \fBnew_field\fR, @@ -37,16 +37,16 @@ \fBfree_field\fR \- create and destroy form fields .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBFIELD *new_field(int \fP\fIheight\fP\fB, int \fP\fIwidth\fP\fB,\fP + \fBint \fP\fItoprow\fP\fB, int \fP\fIleftcol\fP\fB,\fP + \fBint \fP\fIoffscreen\fP\fB, int \fP\fInbuffers\fP\fB);\fP .br -FIELD *new_field(int height, int width, - int toprow, int leftcol, - int offscreen, int nbuffers); +\fBFIELD *dup_field(FIELD *\fP\fIfield\fP\fB, int \fP\fItoprow\fP\fB, int \fP\fIleftcol\fP\fB);\fP .br -FIELD *dup_field(FIELD *field, int toprow, int leftcol); +\fBFIELD *link_field(FIELD *\fP\fIfield\fP\fB, int \fP\fItoprow\fP\fB, int \fP\fIleftcol\fP\fB);\fP .br -FIELD *link_field(FIELD *field, int toprow, int leftcol); -.br -int free_field(FIELD *field); +\fBint free_field(FIELD *\fP\fIfield\fP\fB);\fP .br .SH DESCRIPTION The function \fBnew_field\fR allocates a new field and initializes it from the @@ -67,9 +67,9 @@ 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 +The functions \fBnew_field\fR, \fBdup_field\fR, \fBlink_field\fR return \fBNULL\fR on error. -They set errno according to their success: +They set \fBerrno\fP according to their success: .TP 5 .B E_OK The routine succeeded. diff --git a/man/form_field_opts.3x b/man/form_field_opts.3x index 14f9a20..96338e2 100644 --- a/man/form_field_opts.3x +++ b/man/form_field_opts.3x @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_field_opts.3x,v 1.25 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_field_opts.3x,v 1.27 2020/10/18 00:11:45 tom Exp $ .TH form_field_opts 3X "" .SH NAME \fBset_field_opts\fP, @@ -37,14 +37,14 @@ \fBfield_opts\fP \- set and get field options .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBint set_field_opts(FIELD *\fP\fIfield\fP\fB, Field_Options \fP\fIopts\fP\fB);\fP .br -int set_field_opts(FIELD *field, Field_Options opts); +\fBField_Options field_opts(const FIELD *\fP\fIfield\fP\fB);\fP +.sp +\fBint field_opts_on(FIELD *\fP\fIfield\fP\fB, Field_Options \fP\fIopts\fP\fB);\fP .br -int field_opts_on(FIELD *field, Field_Options opts); -.br -int field_opts_off(FIELD *field, Field_Options opts); -.br -Field_Options field_opts(const FIELD *field); +\fBint field_opts_off(FIELD *\fP\fIfield\fP\fB, Field_Options \fP\fIopts\fP\fB);\fP .br .SH DESCRIPTION The function \fBset_field_opts\fR sets all the given field's option bits (field diff --git a/man/form_field_userptr.3x b/man/form_field_userptr.3x index 4d6aa57..5d3ab14 100644 --- a/man/form_field_userptr.3x +++ b/man/form_field_userptr.3x @@ -28,18 +28,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_field_userptr.3x,v 1.13 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_field_userptr.3x,v 1.16 2020/10/24 09:06:33 tom Exp $ .TH form_field_userptr 3X "" .SH NAME \fBset_field_userptr\fR, \fBfield_userptr\fR \- associate application data with a form field .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBint set_field_userptr(FIELD *\fP\fIfield\fP\fB, void *\fP\fIuserptr\fP\fB);\fP .br -int set_field_userptr(FIELD *field, void*userptr); -.br -void *field_userptr(const FIELD *field); -.br +\fBvoid *field_userptr(const FIELD *\fP\fIfield\fP\fB);\fP .SH DESCRIPTION Every form field has a field that can be used to hold application-specific data (that is, the form-driver code leaves it alone). @@ -47,7 +46,7 @@ These functions get and set that field. .SH RETURN VALUE The function \fBfield_userptr\fR returns a pointer (which may be \fBNULL\fR). -It does not set errno. +It does not set \fBerrno\fP. .PP The function \fBset_field_userptr\fR returns \fBE_OK\fP (success). .SH SEE ALSO diff --git a/man/form_field_validation.3x b/man/form_field_validation.3x index 5835923..8ce9132 100644 --- a/man/form_field_validation.3x +++ b/man/form_field_validation.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_field_validation.3x,v 1.25 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_field_validation.3x,v 1.33 2020/12/12 19:57:55 tom Exp $ .TH form_field_validation 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -41,80 +41,117 @@ \fBform_field_validation\fR \- data type validation for fields .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBvoid *field_arg(const FIELD *\fP\fIfield\fP\fB);\fP .br -int set_field_type(FIELD *field, FIELDTYPE *type, ...); -.br -FIELDTYPE *field_type(const FIELD *field); +\fBFIELDTYPE *field_type(const FIELD *\fP\fIfield\fP\fB);\fP .br -void *field_arg(const FIELD *field); +\fBint set_field_type(FIELD *\fP\fIfield\fP\fB, FIELDTYPE *\fP\fItype\fP\fB, ...);\fP .sp -FIELDTYPE *TYPE_ALNUM; +/* predefined field types */ .br -FIELDTYPE *TYPE_ALPHA; +\fBFIELDTYPE *TYPE_ALNUM;\fP .br -FIELDTYPE *TYPE_ENUM; +\fBFIELDTYPE *TYPE_ALPHA;\fP .br -FIELDTYPE *TYPE_INTEGER; +\fBFIELDTYPE *TYPE_ENUM;\fP .br -FIELDTYPE *TYPE_NUMERIC; +\fBFIELDTYPE *TYPE_INTEGER;\fP .br -FIELDTYPE *TYPE_REGEXP; +\fBFIELDTYPE *TYPE_NUMERIC;\fP .br -FIELDTYPE *TYPE_IPV4; +\fBFIELDTYPE *TYPE_REGEXP;\fP +.br +\fBFIELDTYPE *TYPE_IPV4;\fP .br .SH DESCRIPTION -The function \fBset_field_type\fR declares a data type for a given form field. +By default, no validation is done on form fields. +You can associate a form with with a \fIfield type\fP, +making the form library validate input. +.SS field_arg +Returns a pointer to the field's argument block. +The \fIargument block\fP is an opaque structure containing +a copy of the arguments provided in a \fBset_field_type\fP call. +.SS field_type +Returns a pointer to the \fIfield type\fP associated with the form field, +i.e., by calling \fBset_field_type\fP. +.SS set_field_type +The function \fBset_field_type\fR associates +a field type with a given form field. This is the type checked by validation functions. +Most field types are configurable, +via arguments which the caller provides when calling \fBset_field_type\fP. +.PP +Several field types are predefined by the form library. +.SS Predefined types +.PP +It is possible to set up new programmer-defined field types. +Field types are implemented via the \fBFIELDTYPE\fP data +structure, which contains several pointers to functions. +.PP +See the \fBform_fieldtype\fR(3X) manual page, +which describes functions which can be used to construct +a field-type dynamically. +.PP The predefined types are as follows: .TP 5 TYPE_ALNUM Alphanumeric data. -Requires a third \fBint\fR argument, a minimum field width. +Required parameter: +.RS +.bP +a third \fBint\fR argument, a minimum field width. +.RE .TP 5 TYPE_ALPHA Character data. -Requires a third \fBint\fR argument, a minimum field width. +Required parameter: +.RS +.bP +a third \fBint\fR argument, a minimum field width. +.RE .TP 5 TYPE_ENUM Accept one of a specified set of strings. -Requires additional parameters: +Required parameters: .RS .bP a third \fB(char **)\fR argument pointing to a string list; .bP a fourth \fBint\fR flag argument to enable case-sensitivity; .bP -and a fifth \fBint\fR flag argument specifying whether a partial +a fifth \fBint\fR flag argument specifying whether a partial match must be a unique one. If this flag is off, a prefix matches the first of any set of more than one list elements with that prefix. +.RE .IP The library copies the string list, so you may use a list that lives in automatic variables on the stack. -.RE .TP 5 TYPE_INTEGER Integer data, parsable to an integer by \fBatoi\fP(3). -Requires additional parameters: +Required parameters: .RS .bP a third \fBint\fR argument controlling the precision, .bP a fourth \fBlong\fR argument constraining minimum value, .bP -and a fifth \fBlong\fR constraining maximum value. +a fifth \fBlong\fR constraining maximum value. If the maximum value is less than or equal to the minimum value, the range is simply ignored. +.RE +.IP On return, the field buffer is formatted according to the \fBprintf\fR format specification \*(``.*ld\*('', where the \*(``*\*('' is replaced by the precision argument. .IP For details of the precision handling see \fBprintf\fR(3). -.RE .TP 5 TYPE_NUMERIC Numeric data (may have a decimal-point part). -This requires additional parameters: +Required parameters: .RS .bP a third \fBint\fR argument controlling the precision, @@ -126,18 +163,22 @@ If your system supports locales, the decimal point character must be the one specified by your locale. If the maximum value is less than or equal to the minimum value, the range is simply ignored. +.RE .IP On return, the field buffer is formatted according to the \fBprintf\fR format specification \*(``.*f\*('', where the \*(``*\*('' is replaced by the precision argument. .IP For details of the precision handling see \fBprintf\fR(3). -.RE .TP 5 TYPE_REGEXP Regular expression data. -Requires a regular expression \fB(char *)\fR third argument. +Required parameter: +.RS +.bP +a third argument, a regular expression \fB(char *)\fR string. The data is valid if the regular expression matches it. +.RE .IP Regular expressions are in the format of \fBregcomp\fR and \fBregexec\fR. @@ -154,17 +195,19 @@ leading and trailing spaces around the digits. .TP 5 TYPE_IPV4 An Internet Protocol Version 4 address. -This requires no additional argument. -The library checks whether or not the buffer has the form a.b.c.d, -where a,b,c and d are numbers between 0 and 255. +Required parameter: +.RS +.bP +none +.RE +.IP +The form library checks whether or not the buffer has the form \fIa.b.c.d\fP, +where \fIa\fP, \fIb\fP, \fIc\fP, and \fId\fP are numbers in the range 0 to 255. Trailing blanks in the buffer are ignored. The address itself is not validated. .IP This is an ncurses extension; this field type may not be available in other curses implementations. -.PP -It is possible to set up new programmer-defined field types. -See the \fBform_fieldtype\fR(3X) manual page. .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: @@ -177,6 +220,7 @@ System error occurred (see \fBerrno\fR(3)). .SH SEE ALSO \fBcurses\fR(3X), \fBform\fR(3X), +\fBform_fieldtype\fR(3X), \fBform_variables\fR(3X). .SH NOTES The header file \fB<form.h>\fR automatically includes the header file diff --git a/man/form_fieldtype.3x b/man/form_fieldtype.3x index dd350c2..767c3fc 100644 --- a/man/form_fieldtype.3x +++ b/man/form_fieldtype.3x @@ -28,78 +28,105 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_fieldtype.3x,v 1.20 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_fieldtype.3x,v 1.28 2020/12/12 17:11:21 tom Exp $ +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. .TH form_fieldtype 3X "" .SH NAME \fBform_fieldtype\fR \- define validation-field types .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBFIELDTYPE *new_fieldtype(\fP + \fBbool (* const \fP\fIfield_check\fP\fB)(FIELD *, const void *),\fP + \fBbool (* const \fP\fIchar_check\fP\fB)(int, const void *));\fP .br -FIELDTYPE *new_fieldtype( - bool (* const field_check)(FIELD *, const void *), - bool (* const char_check)(int, const void *)); -.br -int free_fieldtype(FIELDTYPE *fieldtype); -.br -int set_fieldtype_arg( - FIELDTYPE *fieldtype, - void *(* const make_arg)(va_list *), - void *(* const copy_arg)(const void *), - void (* const free_arg)(void *)); -.br -int set_fieldtype_choice( - FIELDTYPE *fieldtype, - bool (* const next_choice)(FIELD *, const void *), - bool (* const prev_choice)(FIELD *, const void *)); -.br -FIELDTYPE *link_fieldtype(FIELDTYPE *type1, - FIELDTYPE *type2); +\fBint free_fieldtype(FIELDTYPE *\fP\fIfieldtype\fP\fB);\fP +.sp +\fBint set_fieldtype_arg(\fP + \fBFIELDTYPE *\fP\fIfieldtype\fP\fB,\fP + \fBvoid *(* const \fP\fImake_arg\fP\fB)(va_list *),\fP + \fBvoid *(* const \fP\fIcopy_arg\fP\fB)(const void *),\fP + \fBvoid (* const \fP\fIfree_arg\fP\fB)(void *));\fP .br +\fBint set_fieldtype_choice(\fP + \fBFIELDTYPE *\fP\fIfieldtype\fP\fB,\fP + \fBbool (* const \fP\fInext_choice\fP\fB)(FIELD *, const void *),\fP + \fBbool (* const \fP\fIprev_choice\fP\fB)(FIELD *, const void *));\fP +.sp +\fBFIELDTYPE *link_fieldtype(FIELDTYPE *\fP\fItype1\fP\fB,\fP + \fBFIELDTYPE *\fP\fItype2\fP\fB);\fP .SH DESCRIPTION +.SS new_fieldtype 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 +Its parameters are function pointers: +.TP 5 +\fIfield_check\fR +This function checks the validity of an entered data string whenever the user attempts to leave a field. +It has two arguments: +.RS +.bP The (FIELD *) argument is passed in so the validation predicate can see the -field's buffer, sizes and other attributes; the second argument is an +field's buffer, sizes and other attributes. +.bP +The second argument is an argument-block structure, about which more below. +.RE +.TP 5 +\fIchar_check\fR +This function validates input characters as they are entered. +The form library passes it the character to be checked +and a pointer to an argument-block structure. +.SS free_fieldtype .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 \fBfree_fieldtype\fR function +frees the space allocated for a given validation type by \fBnew_fieldtype\fP. +.SS set_fieldtype_arg .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 +three storage-management functions with a field type: +.TP 5 +\fImake_arg\fR +This function is automatically applied to the list of arguments you give \fBset_field_type\fR when attaching validation -to a field; its job is to bundle these into an allocated argument-block -object which can later be passed to validation predicated. -The other two hook arguments should copy and free argument-block structures. -They will be used by the forms-driver code. -You must supply the \fImake_arg\fR function, -the other two are optional, you may supply NULL for them. -In this case it is assumed +to a field. +It stores the arguments in an allocated argument-block +object which is used when validating input. +.TP 5 +\fIcopy_arg\fR +This function may be used by applications to copy argument-blocks. +.TP 5 +\fIfree_arg\fR +Frees an argument-block structure. +.PP +You must supply the \fImake_arg\fR function. +The other two are optional: you may supply NULL for them. +In this case, the form library assumes 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'. +.SS set_fieldtype_choice .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. +.PP 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 argument-block structure as arguments. +.SS link_fieldtype +.PP +The function \fBlink_fieldtype\fR creates +a new field type from the two given types. +They are connected by an logical 'OR'. .SH RETURN VALUE The pointer-valued routines return NULL on error. -They set errno according to their success: +They set \fBerrno\fP according to their success: .TP 5 .B E_OK The routine succeeded. @@ -128,14 +155,12 @@ The field is the current field. .B E_SYSTEM_ERROR System error occurred (see \fBerrno\fR(3)). .SH SEE ALSO -\fBcurses\fR(3X), \fBform\fR(3X). +\fBcurses\fR(3X), +\fBform\fR(3X), +\fBform_field_validation\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. .SH PORTABILITY These routines emulate the System V forms library. They were not supported on diff --git a/man/form_hook.3x b/man/form_hook.3x index 5ddeb9f..e84aa97 100644 --- a/man/form_hook.3x +++ b/man/form_hook.3x @@ -28,28 +28,28 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_hook.3x,v 1.14 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_hook.3x,v 1.16 2020/10/18 00:06:29 tom Exp $ .TH form_hook 3X "" .SH NAME \fBform_hook\fR \- set hooks for automatic invocation by applications .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBint set_field_init(FORM *\fP\fIform\fP\fB, Form_Hook \fP\fIfunc\fP\fB);\fP .br -int set_field_init(FORM *form, Form_Hook func); +\fBForm_Hook field_init(const FORM *\fP\fIform\fP\fB);\fP +.sp +\fBint set_field_term(FORM *\fP\fIform\fP\fB, Form_Hook \fP\fIfunc\fP\fB);\fP .br -Form_Hook field_init(const FORM *form); +\fBForm_Hook field_term(const FORM *\fP\fIform\fP\fB);\fP +.sp +\fBint set_form_init(FORM *\fP\fIform\fP\fB, Form_Hook \fP\fIfunc\fP\fB);\fP .br -int set_field_term(FORM *form, Form_Hook func); +\fBForm_Hook form_init(const FORM *\fP\fIform\fP\fB);\fP +.sp +\fBint set_form_term(FORM *\fP\fIform\fP\fB, Form_Hook \fP\fIfunc\fP\fB);\fP .br -Form_Hook field_term(const FORM *form); -.br -int set_form_init(FORM *form, Form_Hook func); -.br -Form_Hook form_init(const FORM *form); -.br -int set_form_term(FORM *form, Form_Hook func); -.br -Form_Hook form_term(const FORM *form); +\fBForm_Hook form_term(const FORM *\fP\fIform\fP\fB);\fP .br .SH DESCRIPTION These functions make it possible to set hook functions to be called at various diff --git a/man/form_new.3x b/man/form_new.3x index 25513bd..4739817 100644 --- a/man/form_new.3x +++ b/man/form_new.3x @@ -28,17 +28,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_new.3x,v 1.12 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_new.3x,v 1.15 2020/10/24 09:02:26 tom Exp $ .TH form_new 3X "" .SH NAME \fBnew_form\fR, \fBfree_form\fP \- create and destroy forms .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBFORM *new_form(FIELD **\fP\fIfields\fP\fB);\fP .br -FORM *new_form(FIELD **fields); -.br -int free_form(FORM *form); +\fBint free_form(FORM *\fP\fIform\fP\fB);\fP .br .SH DESCRIPTION The function \fBnew_form\fR creates a new form connected to a specified field @@ -48,7 +48,7 @@ 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. -It sets errno according to the function's success: +It sets \fBerrno\fP according to the function's success: .TP 5 .B E_OK The routine succeeded. diff --git a/man/form_new_page.3x b/man/form_new_page.3x index 68dce02..478688f 100644 --- a/man/form_new_page.3x +++ b/man/form_new_page.3x @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_new_page.3x,v 1.15 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_new_page.3x,v 1.17 2020/10/18 00:04:36 tom Exp $ .TH form_new_page 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -39,10 +39,10 @@ \fBnew_page\fR \- form pagination functions .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBint set_new_page(FIELD *\fP\fIfield\fP\fB, bool \fP\fInew_page_flag\fP\fB);\fP .br -int set_new_page(FIELD *field, bool new_page_flag); -.br -bool new_page(const FIELD *field); +\fBbool new_page(const FIELD *\fP\fIfield\fP\fB);\fP .br .SH DESCRIPTION The function \fBset_new_page\fR sets or resets a flag marking the given field diff --git a/man/form_opts.3x b/man/form_opts.3x index 18474fa..db6c491 100644 --- a/man/form_opts.3x +++ b/man/form_opts.3x @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_opts.3x,v 1.15 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_opts.3x,v 1.17 2020/10/18 00:03:49 tom Exp $ .TH form_opts 3X "" .SH NAME \fBset_form_opts\fP, @@ -37,14 +37,14 @@ \fBform_opts\fR \- set and get form options .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBint set_form_opts(FORM *\fP\fIform\fP\fB, Field_Options \fP\fIopts\fP\fB);\fP .br -int set_form_opts(FORM *form, Field_Options opts); +\fBField_Options form_opts(const FORM *\fP\fIform\fP\fB);\fP +.sp +\fBint form_opts_on(FORM *\fP\fIform\fP\fB, Field_Options \fP\fIopts\fP\fB);\fP .br -int form_opts_on(FORM *form, Field_Options opts); -.br -int form_opts_off(FORM *form, Field_Options opts); -.br -Field_Options form_opts(const FORM *form); +\fBint form_opts_off(FORM *\fP\fIform\fP\fB, Field_Options \fP\fIopts\fP\fB);\fP .br .SH DESCRIPTION The function \fBset_form_opts\fR sets all the given form's option bits (form diff --git a/man/form_page.3x b/man/form_page.3x index 4b0e819..da1c725 100644 --- a/man/form_page.3x +++ b/man/form_page.3x @@ -28,24 +28,24 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_page.3x,v 1.17 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_page.3x,v 1.19 2020/10/18 00:02:44 tom Exp $ .TH form_page 3X "" .SH NAME \fBform_page\fR \- set and get form page number .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBint set_current_field(FORM *\fP\fIform\fP\fB, FIELD *\fP\fIfield\fP\fB);\fP .br -int set_current_field(FORM *form, FIELD *field); +\fBFIELD *current_field(const FORM *\fP\fIform\fP\fB);\fP +.sp +\fBint unfocus_current_field(FORM *\fP\fIform\fP\fB);\fP +.sp +\fBint set_form_page(FORM *\fP\fIform\fP\fB, int \fP\fIn\fP\fB);\fP .br -FIELD *current_field(const FORM *); -.br -int unfocus_current_field(FORM *form); -.br -int set_form_page(FORM *form, int n); -.br -int form_page(const FORM *form); -.br -int field_index(const FIELD *field); +\fBint form_page(const FORM *\fP\fIform\fP\fB);\fP +.sp +\fBint field_index(const FIELD *\fP\fIfield\fP\fB);\fP .br .SH DESCRIPTION The function \fBset_current_field\fR sets the current field of the given diff --git a/man/form_post.3x b/man/form_post.3x index 5aa08c7..c0e5baa 100644 --- a/man/form_post.3x +++ b/man/form_post.3x @@ -28,17 +28,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_post.3x,v 1.14 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_post.3x,v 1.16 2020/10/18 00:01:05 tom Exp $ .TH form_post 3X "" .SH NAME \fBpost_form\fR, \fBunpost_form\fR \- write or erase forms from associated subwindows .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBint post_form(FORM *\fP\fIform\fP\fB);\fP .br -int post_form(FORM *form); -.br -int unpost_form(FORM *form); +\fBint unpost_form(FORM *\fP\fIform\fP\fB);\fP .br .SH DESCRIPTION The function \fBpost_form\fR displays a form to its associated subwindow. diff --git a/man/form_requestname.3x b/man/form_requestname.3x index a816370..11e5c0f 100644 --- a/man/form_requestname.3x +++ b/man/form_requestname.3x @@ -28,31 +28,32 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_requestname.3x,v 1.12 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_requestname.3x,v 1.16 2020/12/12 16:37:14 tom Exp $ .TH form_requestname 3X "" .SH NAME \fBform_request_by_name\fP, \fBform_request_name\fR \- handle printable form request names .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBconst char *form_request_name(int \fP\fIrequest\fP\fB);\fP .br -const char *form_request_name(int request); -.br -int form_request_by_name(const char *name); +\fBint form_request_by_name(const char *\fP\fIname\fP\fB);\fP .br .SH DESCRIPTION +.SS form_request_name The function \fBform_request_name\fR returns the printable name of a form request code. -.br +.SS form_request_name_by_name The function \fBform_request_by_name\fR searches in the name-table for a request with the given name and returns its request code. Otherwise E_NO_MATCH is returned. .SH RETURN VALUE -\fBform_request_name\fR returns \fBNULL\fR on error and sets errno +\fBform_request_name\fR returns \fBNULL\fR on error and sets \fBerrno\fP to \fBE_BAD_ARGUMENT\fR. -.br +.PP \fBform_request_by_name\fR returns \fBE_NO_MATCH\fR on error. -It does not set errno. +It does not set \fBerrno\fP. .SH SEE ALSO \fBcurses\fR(3X), \fBform\fR(3X). .SH NOTES diff --git a/man/form_userptr.3x b/man/form_userptr.3x index 4af4e18..5651a95 100644 --- a/man/form_userptr.3x +++ b/man/form_userptr.3x @@ -28,17 +28,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_userptr.3x,v 1.16 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_userptr.3x,v 1.19 2020/10/24 09:00:52 tom Exp $ .TH form_userptr 3X "" .SH NAME \fBset_form_userptr\fP, \fBform_userptr\fR \- associate application data with a form item .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBint set_form_userptr(FORM *\fP\fIform\fP\fB, void *\fP\fIuserptr\fP\fB);\fP .br -int set_form_userptr(FORM *form, void *userptr); -.br -void* form_userptr(const FORM *form); +\fBvoid* form_userptr(const FORM *\fP\fIform\fP\fB);\fP .br .SH DESCRIPTION Every form and every form item has a field that can be used to hold @@ -46,7 +46,7 @@ application-specific data (that is, the form-driver code leaves it alone). These functions get and set the form user pointer field. .SH RETURN VALUE The function \fBform_userptr\fR returns a pointer (which may be \fBNULL\fR). -It does not set errno. +It does not set \fBerrno\fP. .PP The function \fBset_form_userptr\fR returns \fBE_OK\fP (success). .SH SEE ALSO diff --git a/man/form_variables.3x b/man/form_variables.3x index 5b4387e..0419cb7 100644 --- a/man/form_variables.3x +++ b/man/form_variables.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_variables.3x,v 1.6 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_variables.3x,v 1.7 2020/12/12 14:45:16 tom Exp $ .TH form_variables 3X "" .na .hy 0 @@ -56,7 +56,8 @@ .fi .SH DESCRIPTION These are building blocks for the form library, -defining fields that can be created using \fBset_fieldtype\fP(3X). +defining fields that can be created using +the \fBform_fieldtype\fP(3X) functions. Each provides functions for field- and character-validation, according to the given datatype. .SS TYPE_ALNUM diff --git a/man/form_win.3x b/man/form_win.3x index b1dc9df..8d4a46d 100644 --- a/man/form_win.3x +++ b/man/form_win.3x @@ -28,22 +28,22 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_win.3x,v 1.16 2020/02/02 23:34:34 tom Exp $ +.\" $Id: form_win.3x,v 1.18 2020/10/18 00:00:32 tom Exp $ .TH form_win 3X "" .SH NAME \fBform_win\fR \- make and break form window and subwindow associations .SH SYNOPSIS \fB#include <form.h>\fR +.sp +\fBint set_form_win(FORM *\fP\fIform\fP\fB, WINDOW *\fP\fIwin\fP\fB);\fP .br -int set_form_win(FORM *form, WINDOW *win); +\fBWINDOW *form_win(const FORM *\fP\fIform\fP\fB);\fP +.sp +\fBint set_form_sub(FORM *\fP\fIform\fP\fB, WINDOW *\fP\fIsub\fP\fB);\fP .br -WINDOW *form_win(const FORM *form); -.br -int set_form_sub(FORM *form, WINDOW *sub); -.br -WINDOW *form_sub(const FORM *form); -.br -int scale_form(const FORM *form, int *rows, int *columns); +\fBWINDOW *form_sub(const FORM *\fP\fIform\fP\fB);\fP +.sp +\fBint scale_form(const FORM *\fP\fIform\fP\fB, int *\fP\fIrows\fP\fB, int *\fP\fIcolumns\fP\fB);\fP .br .SH DESCRIPTION Every form has an associated pair of \fBcurses\fR windows. diff --git a/man/infocmp.1m b/man/infocmp.1m index 8793ed9..087796f 100644 --- a/man/infocmp.1m +++ b/man/infocmp.1m @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2017,2018 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: infocmp.1m,v 1.76 2020/02/02 23:34:34 tom Exp $ +.\" $Id: infocmp.1m,v 1.79 2021/08/15 20:01:31 tom Exp $ .TH @INFOCMP@ 1M "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -245,10 +245,10 @@ is a full description, using \fB@INFOCMP@\fR will show what can be done to change one description to be relative to the other. .PP -A capability will get printed with an at-sign (@) if it no longer exists in the +A capability will be 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 +A capability's value will be 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. @@ -476,7 +476,7 @@ Omit the \*(``Reconstructed from\*('' comment for source listings. \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 +versions of terminfo like those on SVr1, Ultrix, or HP-UX that do not support the full set of SVR4/XSI Curses terminfo; and variants such as AIX that have their own extensions incompatible with SVr4/XSI. .RS @@ -574,7 +574,7 @@ In addition, he added a few new features such as: the \fB\-e\fP option, to support \fIfallback\fP (compiled-in) terminal descriptions .bP -the \fB\-i\fP option, to help with analysis +the \fB\-i\fP option, to help with analysis .PP Later, Thomas Dickey added the \fB\-x\fP (user-defined capabilities) option, and the \fB\-E\fP option to support fallback entries with diff --git a/man/infotocap.1m b/man/infotocap.1m index 10c95ea..2740b55 100644 --- a/man/infotocap.1m +++ b/man/infotocap.1m @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: infotocap.1m,v 1.16 2020/02/02 23:34:34 tom Exp $ +.\" $Id: infotocap.1m,v 1.17 2020/12/19 21:49:52 tom Exp $ .TH @INFOTOCAP@ 1M "" .ds n 5 .ds d @TERMINFO@ @@ -67,9 +67,9 @@ You can use other \fB@TIC@\fR options such as \fB\-f\fR and \fB\-x\fR. .SH PORTABILITY None of X/Open Curses, Issue 7 (2009), SVr4 or NetBSD document this application. .SH SEE ALSO -\fBcurses\fR(3X), -\fB@TIC@\fR(1M), \fB@INFOCMP@\fR(1M), +\fB@TIC@\fR(1M), +\fBcurses\fR(3X), \fBterminfo\fR(\*n) .PP This describes \fBncurses\fR diff --git a/man/key_defined.3x b/man/key_defined.3x index 9ff86a7..c66c54c 100644 --- a/man/key_defined.3x +++ b/man/key_defined.3x @@ -29,14 +29,14 @@ .\" .\" Author: Thomas E. Dickey 2003 .\" -.\" $Id: key_defined.3x,v 1.9 2020/02/02 23:34:34 tom Exp $ +.\" $Id: key_defined.3x,v 1.10 2020/10/17 23:39:03 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 +\fBint key_defined(const char *\fP\fIdefinition\fP\fB);\fP .SH DESCRIPTION This is an extension to the curses library. It permits an application to determine if a string is currently bound diff --git a/man/keybound.3x b/man/keybound.3x index 6a4642b..d9a069e 100644 --- a/man/keybound.3x +++ b/man/keybound.3x @@ -29,14 +29,14 @@ .\" .\" Author: Thomas E. Dickey 1999 .\" -.\" $Id: keybound.3x,v 1.10 2020/02/02 23:34:34 tom Exp $ +.\" $Id: keybound.3x,v 1.11 2020/10/17 23:39:30 tom Exp $ .TH keybound 3X "" .SH NAME \fBkeybound\fP \- return definition of keycode .SH SYNOPSIS \fB#include <curses.h>\fP .sp -\fBchar * keybound(int keycode, int count);\fP +\fBchar * keybound(int \fP\fIkeycode\fP\fB, int \fP\fIcount);\fP .SH DESCRIPTION This is an extension to the curses library. It permits an application to determine the string which is defined diff --git a/man/keyok.3x b/man/keyok.3x index d3c1c84..937450e 100644 --- a/man/keyok.3x +++ b/man/keyok.3x @@ -29,14 +29,14 @@ .\" .\" Author: Thomas E. Dickey 1997 .\" -.\" $Id: keyok.3x,v 1.14 2020/02/02 23:34:34 tom Exp $ +.\" $Id: keyok.3x,v 1.15 2020/10/17 23:39:59 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 +\fBint keyok(int \fP\fIkeycode\fP\fB, bool \fP\fIenable\fP\fB);\fP .SH DESCRIPTION This is an extension to the curses library. It permits an application to disable specific keycodes, rather than diff --git a/man/legacy_coding.3x b/man/legacy_coding.3x index ff951d6..42c3dd6 100644 --- a/man/legacy_coding.3x +++ b/man/legacy_coding.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2020 Thomas E. Dickey * +.\" Copyright 2020,2021 Thomas E. Dickey * .\" Copyright 2005-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -29,14 +29,14 @@ .\" .\" Author: Thomas E. Dickey .\" -.\" $Id: legacy_coding.3x,v 1.7 2020/02/02 23:34:34 tom Exp $ +.\" $Id: legacy_coding.3x,v 1.9 2021/08/15 19:32:05 tom Exp $ .TH legacy_coding 3X "" .SH NAME \fBuse_legacy_coding\fR \- override locale-encoding checks .SH SYNOPSIS \fB#include <curses.h>\fP .sp -\fBint use_legacy_coding(int level);\fP +\fBint use_legacy_coding(int \fP\fIlevel\fP\fB);\fP .SH DESCRIPTION The \fBuse_legacy_coding\fP function is an extension to the curses library. It allows the caller to change the result of \fBunctrl\fP, @@ -70,6 +70,6 @@ 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. +\fBunctrl\fR(3X). .SH AUTHOR Thomas Dickey (to support lynx's font-switching feature). diff --git a/man/make_sed.sh b/man/make_sed.sh index 92e35eb..30e3a77 100755 --- a/man/make_sed.sh +++ b/man/make_sed.sh @@ -1,7 +1,7 @@ #!/bin/sh -# $Id: make_sed.sh,v 1.11 2020/02/02 23:34:34 tom Exp $ +# $Id: make_sed.sh,v 1.12 2021/06/17 21:20:30 tom Exp $ ############################################################################## -# Copyright 2020 Thomas E. Dickey # +# Copyright 2020,2021 Thomas E. Dickey # # Copyright 1998-2005,2017 Free Software Foundation, Inc. # # # # Permission is hereby granted, free of charge, to any person obtaining a # @@ -58,7 +58,7 @@ done for F in 2 4 do tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ <$COL.$F >$UPPER - mv $UPPER $COL.$F + mv $UPPER $COL.$F done paste $COL.* | \ sed -e 's/^/s\/\\</' \ diff --git a/man/manhtml.aliases b/man/manhtml.aliases index c887322..a9f18ca 100644 --- a/man/manhtml.aliases +++ b/man/manhtml.aliases @@ -1,4 +1,4 @@ -# $Id: manhtml.aliases,v 1.14 2020/02/02 23:34:34 tom Exp $ +# $Id: manhtml.aliases,v 1.19 2020/12/12 14:45:55 tom Exp $ #*************************************************************************** # Copyright 2019,2020 Thomas E. Dickey * # Copyright 2013,2017 Free Software Foundation, Inc. * @@ -28,14 +28,15 @@ # authorization. * #*************************************************************************** # Items in this list will be linked to the corresponding manpages by man2html -assume_default_colors(3X) default_colors(3X) addch(3X) curs_addch(3X) +assume_default_colors(3X) default_colors(3X) curs_set(3X) curs_kernel(3X) delscreen(3X) curs_initscr(3X) doupdate(3X) curs_refresh(3X) endwin(3X) curs_initscr(3X) filter(3X) curs_util(3X) get_wch(3X) curs_get_wch(3X) +getcchar(3X) curs_getcchar(3X) getch(3X) curs_getch(3X) inch(3X) curs_inch(3X) infocmp(1) infocmp(1M) @@ -45,19 +46,24 @@ keypad(3X) curs_inopts(3X) longname(3X) curs_termattrs(3X) meta(3X) curs_inopts(3X) mvcur(3X) curs_terminfo(3X) +mvwin(3X) curs_window(3X) newterm(3X) curs_initscr(3X) refresh(3X) curs_refresh(3X) reset_shell_mode(3X) curs_kernel(3X) -set_fieldtype(3X) form_fieldtype(3X) set_term(3X) curs_initscr(3X) +setcchar(3X) curs_getcchar(3X) setupterm(3X) curs_terminfo(3X) slk_init(3X) curs_slk(3X) +slk_touch(3X) curs_slk(3X) tic(1) tic(1M) tigetstr(3X) curs_terminfo(3X) tparm(3X) curs_terminfo(3X) tputs(3X) curs_terminfo(3X) -use_env(3X) curs_util(3X) use_default_colors(3X) default_colors(3X) +use_env(3X) curs_util(3X) use_extended_names(3X) curs_extend(3X) +use_legacy_coding(3X) legacy_coding(3X) vidputs(3X) curs_terminfo(3X) wgetch(3X) curs_getch(3X) +wnoutrefresh(3X) curs_refresh(3X) +wrefresh(3X) curs_refresh(3X) diff --git a/man/manhtml.externs b/man/manhtml.externs index c6fcace..8787b2c 100644 --- a/man/manhtml.externs +++ b/man/manhtml.externs @@ -1,4 +1,4 @@ -# $Id: manhtml.externs,v 1.13 2020/02/02 23:34:34 tom Exp $ +# $Id: manhtml.externs,v 1.14 2020/04/18 09:48:50 tom Exp $ # Items in this list will not be linked by man2html #*************************************************************************** # Copyright 2019,2020 Thomas E. Dickey * @@ -51,12 +51,14 @@ putchar(3) putwc(3) read(2) scanf(3) +screen(1) sh(1) sscanf(3) stdio(3) stty(1) system(3) termios(3) +tmux(1) tty(4) ttys(5) vprintf(3) diff --git a/man/manlinks.sed b/man/manlinks.sed index 9b57bca..09b055f 100644 --- a/man/manlinks.sed +++ b/man/manlinks.sed @@ -1,6 +1,6 @@ -# $Id: manlinks.sed,v 1.14 2020/02/02 23:34:34 tom Exp $ +# $Id: manlinks.sed,v 1.15 2021/01/05 20:30:00 tom Exp $ ############################################################################## -# Copyright 2020 Thomas E. Dickey # +# Copyright 2020,2021 Thomas E. Dickey # # Copyright 2000-2003,2008 Free Software Foundation, Inc. # # # # Permission is hereby granted, free of charge, to any person obtaining a # @@ -41,10 +41,14 @@ s/^\.IX// s/\\f.//g s/[:,]/ /g # +# ignore C-style comments +s%/\*.*\*/%% +# # eliminate unnecessary whitespace, convert multiple blanks to single space s/^[ ][ ]*// s/[ ][ ]*$// s/[ ][ ]*/ /g +/^$/d # # convert ".SH" into a more manageable form s/\.SH[ ][ ]*/.SH_(/ diff --git a/man/menu_attributes.3x b/man/menu_attributes.3x index 0dcea24..903e303 100644 --- a/man/menu_attributes.3x +++ b/man/menu_attributes.3x @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_attributes.3x,v 1.17 2020/02/02 23:34:34 tom Exp $ +.\" $Id: menu_attributes.3x,v 1.19 2020/10/17 23:58:58 tom Exp $ .TH menu_attributes 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -45,22 +45,22 @@ \fBset_menu_pad\fR \- color and attribute control for menus .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBint set_menu_fore(MENU *\fP\fImenu\fP\fB, chtype \fP\fIattr\fP\fB);\fP .br -int set_menu_fore(MENU *menu, chtype attr); +\fBchtype menu_fore(const MENU *\fP\fImenu\fP\fB);\fP +.sp +\fBint set_menu_back(MENU *\fP\fImenu\fP\fB, chtype \fP\fIattr\fP\fB);\fP .br -chtype menu_fore(const MENU *menu); +\fBchtype menu_back(const MENU *\fP\fImenu\fP\fB);\fP +.sp +\fBint set_menu_grey(MENU *\fP\fImenu\fP\fB, chtype \fP\fIattr\fP\fB);\fP .br -int set_menu_back(MENU *menu, chtype attr); +\fBchtype menu_grey(const MENU *\fP\fImenu\fP\fB);\fP +.sp +\fBint set_menu_pad(MENU *\fP\fImenu\fP\fB, int \fP\fIpad\fP\fB);\fP .br -chtype menu_back(const MENU *menu); -.br -int set_menu_grey(MENU *menu, chtype attr); -.br -chtype menu_grey(const MENU *menu); -.br -int set_menu_pad(MENU *menu, int pad); -.br -int menu_pad(const MENU *menu); +\fBint menu_pad(const MENU *\fP\fImenu\fP\fB);\fP .br .SH DESCRIPTION The function \fBset_menu_fore\fR sets the foreground attribute of diff --git a/man/menu_cursor.3x b/man/menu_cursor.3x index 2ea893d..7a364eb 100644 --- a/man/menu_cursor.3x +++ b/man/menu_cursor.3x @@ -28,14 +28,14 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_cursor.3x,v 1.12 2020/02/02 23:34:34 tom Exp $ +.\" $Id: menu_cursor.3x,v 1.13 2020/10/17 23:41:31 tom Exp $ .TH menu_cursor 3X "" .SH NAME \fBpos_menu_cursor\fR \- position a menu's cursor .SH SYNOPSIS \fB#include <menu.h>\fR -.br -int pos_menu_cursor(const MENU *menu); +.sp +\fBint pos_menu_cursor(const MENU *\fP\fImenu\fP\fB);\fP .br .SH DESCRIPTION The function \fBpos_menu_cursor\fR restores the cursor to the current position diff --git a/man/menu_driver.3x b/man/menu_driver.3x index 27dccbb..e395358 100644 --- a/man/menu_driver.3x +++ b/man/menu_driver.3x @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_driver.3x,v 1.26 2020/02/02 23:34:34 tom Exp $ +.\" $Id: menu_driver.3x,v 1.28 2020/12/19 21:33:37 tom Exp $ .TH menu_driver 3X "" .de bP .ie n .IP \(bu 4 @@ -37,8 +37,8 @@ \fBmenu_driver\fR \- command-processing loop of the menu system .SH SYNOPSIS \fB#include <menu.h>\fR -.br -int menu_driver(MENU *menu, int c); +.sp +\fBint menu_driver(MENU *\fP\fImenu\fP\fB, int \fP\fIc\fP\fB);\fP .br .SH DESCRIPTION Once a menu has been posted (displayed), you should funnel input events to it @@ -193,8 +193,8 @@ Character failed to match. The menu driver could not process the request. .SH SEE ALSO \fBcurses\fR(3X), -\fBmenu\fR(3X), -\fBgetch\fR(3X). +\fBgetch\fR(3X), +\fBmenu\fR(3X). .SH NOTES The header file \fB<menu.h>\fR automatically includes the header files \fB<curses.h>\fR. diff --git a/man/menu_format.3x b/man/menu_format.3x index ca2e8ef..d01f27e 100644 --- a/man/menu_format.3x +++ b/man/menu_format.3x @@ -28,17 +28,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_format.3x,v 1.17 2020/02/02 23:34:34 tom Exp $ +.\" $Id: menu_format.3x,v 1.18 2020/10/17 23:43:11 tom Exp $ .TH menu_format 3X "" .SH NAME \fBset_menu_format\fP, \fBmenu_format\fP \- set and get menu sizes .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBint set_menu_format(MENU *\fP\fImenu\fP\fB, int \fP\fIrows\fP\fB, int \fP\fIcols\fP\fB);\fP .br -int set_menu_format(MENU *menu, int rows, int cols); -.br -void menu_format(const MENU *menu, int *rows, int *cols); +\fBvoid menu_format(const MENU *\fP\fImenu\fP\fB, int *\fP\fIrows\fP\fB, int *\fP\fIcols\fP\fB);\fP .br .SH DESCRIPTION The function \fBset_menu_format\fR sets the maximum display size of the given diff --git a/man/menu_hook.3x b/man/menu_hook.3x index adf0cb4..17a1036 100644 --- a/man/menu_hook.3x +++ b/man/menu_hook.3x @@ -28,28 +28,28 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_hook.3x,v 1.14 2020/02/02 23:34:34 tom Exp $ +.\" $Id: menu_hook.3x,v 1.15 2020/10/17 23:44:57 tom Exp $ .TH menu_hook 3X "" .SH NAME \fBmenu_hook\fR \- set hooks for automatic invocation by applications .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBint set_item_init(MENU *\fP\fImenu\fP\fB, Menu_Hook \fP\fIfunc);\fP .br -int set_item_init(MENU *menu, Menu_Hook func); +\fBMenu_Hook item_init(const MENU *\fP\fImenu);\fP +.sp +\fBint set_item_term(MENU *\fP\fImenu\fP\fB, Menu_Hook \fP\fIfunc);\fP .br -Menu_Hook item_init(const MENU *menu); +\fBMenu_Hook item_term(const MENU *\fP\fImenu);\fP +.sp +\fBint set_menu_init(MENU *\fP\fImenu\fP\fB, Menu_Hook \fP\fIfunc);\fP .br -int set_item_term(MENU *menu, Menu_Hook func); +\fBMenu_Hook menu_init(const MENU *\fP\fImenu);\fP +.sp +\fBint set_menu_term(MENU *\fP\fImenu\fP\fB, Menu_Hook \fP\fIfunc);\fP .br -Menu_Hook item_term(const MENU *menu); -.br -int set_menu_init(MENU *menu, Menu_Hook func); -.br -Menu_Hook menu_init(const MENU *menu); -.br -int set_menu_term(MENU *menu, Menu_Hook func); -.br -Menu_Hook menu_term(const MENU *menu); +\fBMenu_Hook menu_term(const MENU *\fP\fImenu);\fP .br .SH DESCRIPTION These functions make it possible to set hook functions to be called at various diff --git a/man/menu_items.3x b/man/menu_items.3x index 4d01802..7c04243 100644 --- a/man/menu_items.3x +++ b/man/menu_items.3x @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_items.3x,v 1.14 2020/02/02 23:34:34 tom Exp $ +.\" $Id: menu_items.3x,v 1.17 2020/10/24 09:00:06 tom Exp $ .TH menu_items 3X "" .SH NAME \fBset_menu_items\fR, @@ -36,12 +36,12 @@ \fBitem_count\fP \- make and break connections between items and menus .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBint set_menu_items(MENU *\fP\fImenu\fP\fB, ITEM **\fP\fIitems\fP\fB);\fP .br -int set_menu_items(MENU *menu, ITEM **items); +\fBITEM **menu_items(const MENU *\fP\fImenu\fP\fB);\fP .br -ITEM **menu_items(const MENU *menu); -.br -int item_count(const MENU *menu); +\fBint item_count(const MENU *\fP\fImenu\fP\fB);\fP .br .SH DESCRIPTION The function \fBset_menu_items\fR changes the item pointer array of the given @@ -52,7 +52,7 @@ The function \fBmenu_items\fR returns the item array of the given menu. The function \fBitem_count\fR returns the count of items in \fImenu\fR. .SH RETURN VALUE The function \fBmenu_items\fR returns a pointer (which may be \fBNULL\fR). -It does not set errno. +It does not set \fBerrno\fP. .PP The function \fBitem_count\fR returns \fBERR\fR (the general \fBcurses\fR error return value) if its \fImenu\fP parameter is \fBNULL\fP. diff --git a/man/menu_mark.3x b/man/menu_mark.3x index 9ad0989..9601135 100644 --- a/man/menu_mark.3x +++ b/man/menu_mark.3x @@ -28,17 +28,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_mark.3x,v 1.15 2020/02/02 23:34:34 tom Exp $ +.\" $Id: menu_mark.3x,v 1.18 2020/10/24 08:59:04 tom Exp $ .TH menu_mark 3X "" .SH NAME \fBset_menu_mark\fP, \fBmenu_mark\fR \- get and set the menu mark string .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBint set_menu_mark(MENU *\fP\fImenu\fP\fB, const char *\fP\fImark\fP\fB);\fP .br -int set_menu_mark(MENU *menu, const char *mark); -.br -const char *menu_mark(const MENU *menu); +\fBconst char *menu_mark(const MENU *\fP\fImenu\fP\fB);\fP .br .SH DESCRIPTION In order to make menu selections visible on older terminals without @@ -58,7 +58,7 @@ 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 a pointer (which may be \fBNULL\fR). -It does not set errno. +It does not set \fBerrno\fP. .PP The function \fBset_menu_mark\fR may return the following error codes: .TP 5 diff --git a/man/menu_new.3x b/man/menu_new.3x index 46e415e..3b04f93 100644 --- a/man/menu_new.3x +++ b/man/menu_new.3x @@ -28,17 +28,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_new.3x,v 1.15 2020/02/02 23:34:34 tom Exp $ +.\" $Id: menu_new.3x,v 1.18 2020/10/24 08:57:51 tom Exp $ .TH menu_new 3X "" .SH NAME \fBnew_menu\fP, \fBfree_menu\fR \- create and destroy menus .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBMENU *new_menu(ITEM **\fP\fIitems\fP\fB);\fP .br -MENU *new_menu(ITEM **items); -.br -int free_menu(MENU *menu); +\fBint free_menu(MENU *\fP\fImenu\fP\fB);\fP .br .SH DESCRIPTION The function \fBnew_menu\fR creates a new menu connected to a specified item @@ -48,7 +48,7 @@ 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: +It sets \fBerrno\fP according to the function's failure: .TP 5 .B E_NOT_CONNECTED No items are connected to the menu. diff --git a/man/menu_opts.3x b/man/menu_opts.3x index 4a0d435..99e950e 100644 --- a/man/menu_opts.3x +++ b/man/menu_opts.3x @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_opts.3x,v 1.17 2020/02/02 23:34:34 tom Exp $ +.\" $Id: menu_opts.3x,v 1.18 2020/10/17 23:46:35 tom Exp $ .TH menu_opts 3X "" .SH NAME \fBset_menu_opts\fP, @@ -37,14 +37,14 @@ \fBmenu_opts\fR \- set and get menu options .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBint set_menu_opts(MENU *\fP\fImenu\fP\fB, Menu_Options \fP\fIopts\fP\fB);\fP .br -int set_menu_opts(MENU *menu, Menu_Options opts); +\fBMenu_Options menu_opts(const MENU *\fP\fImenu\fP\fB);\fP +.sp +\fBint menu_opts_on(MENU *\fP\fImenu\fP\fB, Menu_Options \fP\fIopts\fP\fB);\fP .br -int menu_opts_on(MENU *menu, Menu_Options opts); -.br -int menu_opts_off(MENU *menu, Menu_Options opts); -.br -Menu_Options menu_opts(const MENU *menu); +\fBint menu_opts_off(MENU *\fP\fImenu\fP\fB, Menu_Options \fP\fIopts\fP\fB);\fP .br .SH DESCRIPTION The function \fBset_menu_opts\fR sets all the given menu's option bits (menu diff --git a/man/menu_pattern.3x b/man/menu_pattern.3x index ce439b4..a24ffa0 100644 --- a/man/menu_pattern.3x +++ b/man/menu_pattern.3x @@ -27,17 +27,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_pattern.3x,v 1.18 2020/02/02 23:34:34 tom Exp $ +.\" $Id: menu_pattern.3x,v 1.21 2020/10/18 00:41:14 tom Exp $ .TH menu_pattern 3X "" .SH NAME \fBset_menu_pattern\fP, \fBmenu_pattern\fR \- set and get a menu's pattern buffer .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBint set_menu_pattern(MENU *\fP\fImenu\fP\fB, const char *\fP\fIpattern\fP\fB);\fP .br -int set_menu_pattern(MENU *menu, const char *pattern); -.br -char *menu_pattern(const MENU *menu); +\fBchar *menu_pattern(const MENU *\fP\fImenu\fP\fB);\fP .br .SH DESCRIPTION Every menu has an associated pattern match buffer. @@ -57,7 +57,7 @@ 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. +It does not set \fBerrno\fP. .PP The function \fBset_menu_pattern\fR may return the following error codes: .TP 5 diff --git a/man/menu_post.3x b/man/menu_post.3x index 71f31a7..6f14a45 100644 --- a/man/menu_post.3x +++ b/man/menu_post.3x @@ -28,17 +28,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_post.3x,v 1.18 2020/02/02 23:34:34 tom Exp $ +.\" $Id: menu_post.3x,v 1.19 2020/10/17 23:47:21 tom Exp $ .TH menu_post 3X "" .SH NAME \fBpost_menu\fR, \fBunpost_menu\fR \- write or erase menus from associated subwindows .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBint post_menu(MENU *\fP\fImenu\fP\fB);\fP .br -int post_menu(MENU *menu); -.br -int unpost_menu(MENU *menu); +\fBint unpost_menu(MENU *\fP\fImenu\fP\fB);\fP .br .SH DESCRIPTION The function \fBpost_menu\fR displays a menu to its associated subwindow. diff --git a/man/menu_requestname.3x b/man/menu_requestname.3x index c62ec50..d10874c 100644 --- a/man/menu_requestname.3x +++ b/man/menu_requestname.3x @@ -28,17 +28,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_requestname.3x,v 1.12 2020/02/02 23:34:34 tom Exp $ +.\" $Id: menu_requestname.3x,v 1.15 2020/10/18 00:40:34 tom Exp $ .TH menu_requestname 3X "" .SH NAME \fBmenu_request_by_name\fP, \fBmenu_request_name\fR \- handle printable menu request names .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBconst char *menu_request_name(int \fP\fIrequest\fP\fB);\fP .br -const char *menu_request_name(int request); -.br -int menu_request_by_name(const char *name); +\fBint menu_request_by_name(const char *\fP\fIname\fP\fB);\fP .br .SH DESCRIPTION The function \fBmenu_request_name\fR returns the printable name of a menu @@ -49,10 +49,10 @@ 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. +and sets \fBerrno\fP to \fBE_BAD_ARGUMENT\fR. .br \fBmenu_request_by_name\fR returns \fBE_NO_MATCH\fR on error. -It does not set errno. +It does not set \fBerrno\fP. .SH SEE ALSO \fBcurses\fR(3X), \fBmenu\fR(3X). .SH NOTES diff --git a/man/menu_spacing.3x b/man/menu_spacing.3x index 04ccb57..7d67f0b 100644 --- a/man/menu_spacing.3x +++ b/man/menu_spacing.3x @@ -28,23 +28,23 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_spacing.3x,v 1.16 2020/02/02 23:34:34 tom Exp $ +.\" $Id: menu_spacing.3x,v 1.17 2020/10/17 23:48:53 tom Exp $ .TH menu_spacing 3X "" .SH NAME \fBset_menu_spacing\fP, \fBmenu_spacing\fR \- set and get spacing between menu items. .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBint set_menu_spacing(MENU *\fP\fImenu\fP\fB,\fP + \fBint \fP\fIspc_description\fP\fB,\fP + \fBint \fP\fIspc_rows\fP\fB,\fP + \fBint \fP\fIspc_columns\fP\fB);\fP .br -int set_menu_spacing(MENU *menu, - int spc_description, - int spc_rows, - int spc_columns); -.br -int menu_spacing(const MENU *menu, - int* spc_description, - int* spc_rows, - int* spc_columns); +\fBint menu_spacing(const MENU *\fP\fImenu\fP\fB,\fP + \fBint* \fP\fIspc_description\fP\fB,\fP + \fBint* \fP\fIspc_rows\fP\fB,\fP + \fBint* \fP\fIspc_columns\fP\fB);\fP .br .SH DESCRIPTION The function \fBset_menu_spacing\fR sets the spacing information for the menu. diff --git a/man/menu_userptr.3x b/man/menu_userptr.3x index 15cc14b..afc393e 100644 --- a/man/menu_userptr.3x +++ b/man/menu_userptr.3x @@ -28,17 +28,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_userptr.3x,v 1.13 2020/02/02 23:34:34 tom Exp $ +.\" $Id: menu_userptr.3x,v 1.16 2020/10/18 00:39:49 tom Exp $ .TH menu_userptr 3X "" .SH NAME \fBset_menu_userptr\fP, \fBmenu_userptr\fR \- associate application data with a menu item .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBint set_menu_userptr(MENU *\fP\fImenu\fP\fB, void *\fP\fIuserptr\fP\fB);\fP .br -int set_menu_userptr(MENU *menu, void *userptr); -.br -void *menu_userptr(const MENU *menu); +\fBvoid *menu_userptr(const MENU *\fP\fImenu\fP\fB);\fP .br .SH DESCRIPTION Every menu and every menu item has a field that can be used to hold @@ -46,7 +46,7 @@ application-specific data (that is, the menu-driver code leaves it alone). These functions get and set the menu user pointer field. .SH RETURN VALUE \fBmenu_userptr\fR returns a pointer (which may be \fBNULL\fR). -It does not set errno. +It does not set \fBerrno\fP. .PP \fBset_menu_userptr\fP returns \fBE_OK\fP (success). .SH SEE ALSO diff --git a/man/menu_win.3x b/man/menu_win.3x index 99ba546..ae764ec 100644 --- a/man/menu_win.3x +++ b/man/menu_win.3x @@ -28,22 +28,22 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_win.3x,v 1.14 2020/02/02 23:34:34 tom Exp $ +.\" $Id: menu_win.3x,v 1.15 2020/10/17 23:50:51 tom Exp $ .TH menu_win 3X "" .SH NAME \fBmenu_win\fR \- make and break menu window and subwindow associations .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBint set_menu_win(MENU *\fP\fImenu\fP\fB, WINDOW *\fP\fIwin\fP\fB);\fP .br -int set_menu_win(MENU *menu, WINDOW *win); +\fBWINDOW *menu_win(const MENU *\fP\fImenu\fP\fB);\fP +.sp +\fBint set_menu_sub(MENU *\fP\fImenu\fP\fB, WINDOW *\fP\fIsub\fP\fB);\fP .br -WINDOW *menu_win(const MENU *menu); -.br -int set_menu_sub(MENU *menu, WINDOW *sub); -.br -WINDOW *menu_sub(const MENU *menu); -.br -int scale_menu(const MENU *menu, int *rows, int *columns); +\fBWINDOW *menu_sub(const MENU *\fP\fImenu\fP\fB);\fP +.sp +\fBint scale_menu(const MENU *\fP\fImenu, int *\fP\fIrows\fP\fB, int *\fP\fIcolumns);\fP .br .SH DESCRIPTION Every menu has an associated pair of \fBcurses\fR windows. diff --git a/man/mitem_current.3x b/man/mitem_current.3x index b1736c7..4cd37b6 100644 --- a/man/mitem_current.3x +++ b/man/mitem_current.3x @@ -28,22 +28,22 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: mitem_current.3x,v 1.17 2020/02/02 23:34:34 tom Exp $ +.\" $Id: mitem_current.3x,v 1.20 2020/10/18 00:39:06 tom Exp $ .TH mitem_current 3X "" .SH NAME \fBmitem_current\fR \- set and get current_menu_item .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBint set_current_item(MENU *\fP\fImenu\fP\fB, ITEM *\fP\fIitem\fP\fB);\fP .br -int set_current_item(MENU *menu, ITEM *item); +\fBITEM *current_item(const MENU *\fP\fImenu\fP\fB);\fP +.sp +\fBint set_top_row(MENU *\fP\fImenu\fP\fB, int \fP\fIrow\fP\fB);\fP .br -ITEM *current_item(const MENU *menu); -.br -int set_top_row(MENU *menu, int row); -.br -int top_row(const MENU *menu); -.br -int item_index(const ITEM *item); +\fBint top_row(const MENU *\fP\fImenu\fP\fB);\fP +.sp +\fBint item_index(const ITEM *\fP\fIitem\fP\fB);\fP .br .SH DESCRIPTION The function \fBset_current_item\fR sets the current item (the item on which @@ -63,7 +63,7 @@ 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 a pointer (which may be \fBNULL\fR). -It does not set errno. +It does not set \fBerrno\fP. .PP \fBtop_row\fR and \fBitem_index\fR return \fBERR\fR (the general \fBcurses\fR error value) if their \fImenu\fP parameter is \fBNULL\fP. diff --git a/man/mitem_name.3x b/man/mitem_name.3x index 0207a9a..bf50cfd 100644 --- a/man/mitem_name.3x +++ b/man/mitem_name.3x @@ -28,17 +28,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: mitem_name.3x,v 1.11 2020/02/02 23:34:34 tom Exp $ +.\" $Id: mitem_name.3x,v 1.14 2020/10/18 00:37:48 tom Exp $ .TH mitem_name 3X "" .SH NAME \fBitem_name\fR, \fBitem_description\fR \- get menu item name and description fields .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBconst char *item_name(const ITEM *\fP\fIitem\fP\fB);\fP .br -const char *item_name(const ITEM *item); -.br -const char *item_description(const ITEM *item); +\fBconst char *item_description(const ITEM *\fP\fIitem\fP\fB);\fP .br .SH DESCRIPTION The function \fBitem_name\fR returns the name part of the given item. @@ -47,7 +47,7 @@ The function \fBitem_description\fR returns the description part of the given item. .SH RETURN VALUE These routines return a pointer (which may be \fBNULL\fR). -They do not set errno. +They do not set \fBerrno\fP. .SH SEE ALSO \fBcurses\fR(3X), \fBmenu\fR(3X). .SH NOTES diff --git a/man/mitem_new.3x b/man/mitem_new.3x index 9f591f6..ce52044 100644 --- a/man/mitem_new.3x +++ b/man/mitem_new.3x @@ -28,17 +28,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: mitem_new.3x,v 1.16 2020/02/02 23:34:34 tom Exp $ +.\" $Id: mitem_new.3x,v 1.19 2020/10/18 00:37:03 tom Exp $ .TH mitem_new 3X "" .SH NAME \fBnew_item\fP, \fBfree_item\fR \- create and destroy menu items .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBITEM *new_item(const char *\fP\fIname\fP\fB, const char *\fP\fIdescription\fP\fB);\fP .br -ITEM *new_item(const char *name, const char *description); -.br -int free_item(ITEM *item); +\fBint free_item(ITEM *\fP\fIitem\fP\fB);\fP .br .SH DESCRIPTION The function \fBnew_item\fR allocates a new item and initializes it from the @@ -56,7 +56,7 @@ 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: +It sets \fBerrno\fP according to the function's failure: .TP 5 .B E_BAD_ARGUMENT Routine detected an incorrect or out-of-range argument. diff --git a/man/mitem_opts.3x b/man/mitem_opts.3x index 2745943..105f9de 100644 --- a/man/mitem_opts.3x +++ b/man/mitem_opts.3x @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: mitem_opts.3x,v 1.15 2020/02/02 23:34:34 tom Exp $ +.\" $Id: mitem_opts.3x,v 1.16 2020/10/17 23:52:26 tom Exp $ .TH mitem_opts 3X "" .SH NAME \fBset_item_opts\fP, @@ -37,14 +37,14 @@ \fBitem_opts\fR \- set and get menu item options .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBint set_item_opts(ITEM *\fP\fIitem\fP\fB, Item_Options \fP\fIopts\fP\fB);\fP .br -int set_item_opts(ITEM *item, Item_Options opts); +\fBItem_Options item_opts(const ITEM *\fP\fIitem\fP\fB);\fP +.sp +\fBint item_opts_on(ITEM *\fP\fIitem\fP\fB, Item_Options \fP\fIopts\fP\fB);\fP .br -int item_opts_on(ITEM *item, Item_Options opts); -.br -int item_opts_off(ITEM *item, Item_Options opts); -.br -Item_Options item_opts(const ITEM *item); +\fBint item_opts_off(ITEM *\fP\fIitem\fP\fB, Item_Options \fP\fIopts\fP\fB);\fP .br .SH DESCRIPTION The function \fBset_item_opts\fR sets all the given item's option bits (menu diff --git a/man/mitem_userptr.3x b/man/mitem_userptr.3x index f2639fd..3c3feb2 100644 --- a/man/mitem_userptr.3x +++ b/man/mitem_userptr.3x @@ -28,17 +28,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: mitem_userptr.3x,v 1.14 2020/02/02 23:34:34 tom Exp $ +.\" $Id: mitem_userptr.3x,v 1.17 2020/10/18 00:36:16 tom Exp $ .TH mitem_userptr 3X "" .SH NAME \fBset_item_userptr\fP, \fBitem_userptr\fR \- associate application data with a menu item .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBint set_item_userptr(ITEM *\fP\fIitem\fP\fB, void *\fP\fIuserptr\fP\fB);\fP .br -int set_item_userptr(ITEM *item, void *userptr); -.br -void *item_userptr(const ITEM *item); +\fBvoid *item_userptr(const ITEM *\fP\fIitem\fP\fB);\fP .br .SH DESCRIPTION Every menu item has a field that can be used to hold application-specific data @@ -47,7 +47,7 @@ These functions get and set that field. .SH RETURN VALUE The function \fBitem_userptr\fR returns a pointer (possibly \fBNULL\fR). -It does not set errno. +It does not set \fBerrno\fP. .PP The \fBset_item_userptr\fP always returns \fBE_OK\fP (success). . diff --git a/man/mitem_value.3x b/man/mitem_value.3x index ddbc0f5..3dc20f1 100644 --- a/man/mitem_value.3x +++ b/man/mitem_value.3x @@ -27,17 +27,17 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: mitem_value.3x,v 1.14 2020/02/02 23:34:34 tom Exp $ +.\" $Id: mitem_value.3x,v 1.15 2020/10/17 23:53:24 tom Exp $ .TH mitem_value 3X "" .SH NAME \fBset_item_value\fP, \fBitem_value\fP \- set and get menu item values .SH SYNOPSIS \fB#include <menu.h>\fR +.sp +\fBint set_item_value(ITEM *\fP\fIitem\fP\fB, bool \fP\fIvalue\fP\fB);\fP .br -int set_item_value(ITEM *item, bool value); -.br -bool item_value(const ITEM *item); +\fBbool item_value(const ITEM *\fP\fIitem\fP\fB);\fP .br .SH DESCRIPTION If you turn off the menu option \fBO_ONEVALUE\fR (e.g., with diff --git a/man/mitem_visible.3x b/man/mitem_visible.3x index 37f569c..5e6d168 100644 --- a/man/mitem_visible.3x +++ b/man/mitem_visible.3x @@ -28,14 +28,14 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: mitem_visible.3x,v 1.9 2020/02/02 23:34:34 tom Exp $ +.\" $Id: mitem_visible.3x,v 1.10 2020/10/17 23:53:55 tom Exp $ .TH mitem_visible 3X "" .SH NAME \fBmitem_visible\fR \- check visibility of a menu item .SH SYNOPSIS \fB#include <menu.h>\fR -.br -bool item_visible(const ITEM *item); +.sp +\fBbool item_visible(const ITEM *\fP\fIitem\fP\fB);\fP .br .SH DESCRIPTION A menu item is visible when it is in the portion of a posted menu that diff --git a/man/ncurses.3x b/man/ncurses.3x index fdd2a71..fb12794 100644 --- a/man/ncurses.3x +++ b/man/ncurses.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: ncurses.3x,v 1.144 2020/02/02 23:34:34 tom Exp $ +.\" $Id: ncurses.3x,v 1.153 2021/08/22 17:17:16 tom Exp $ .hy 0 .TH ncurses 3X "" .ie \n(.g .ds `` \(lq @@ -89,7 +89,7 @@ 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 +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 @@ -127,7 +127,6 @@ sequence should be used: .PP Most programs would additionally use the sequence: .NS -\fBnonl();\fR \fBintrflush(stdscr, FALSE);\fR \fBkeypad(stdscr, TRUE);\fR .NE @@ -319,8 +318,9 @@ For example, \fBwaddch\fP becomes \fBwadd_wch\fP. .PP .\" .SS Routine Name Index -The following table lists each \fBcurses\fR routine and the name of -the manual page on which it is described. +The following table lists the \fBcurses\fR routines provided in +the \*(``normal\*('' and \*(``wide\*('' libraries and the names of +the manual pages on which they are described. Routines flagged with \*(``*\*('' are ncurses-specific, not described by XPG4 or present in SVr4. .PP @@ -332,17 +332,6 @@ l l . = COLOR_PAIR/\fBcurs_color\fR(3X) PAIR_NUMBER/\fBcurs_attr\fR(3X) -_nc_free_and_exit/\fBcurs_memleaks\fR(3X)* -_nc_freeall/\fBcurs_memleaks\fR(3X)* -_nc_tracebits/\fBcurs_trace\fR(3X)* -_traceattr/\fBcurs_trace\fR(3X)* -_traceattr2/\fBcurs_trace\fR(3X)* -_tracechar/\fBcurs_trace\fR(3X)* -_tracechtype/\fBcurs_trace\fR(3X)* -_tracechtype2/\fBcurs_trace\fR(3X)* -_tracedump/\fBcurs_trace\fR(3X)* -_tracef/\fBcurs_trace\fR(3X)* -_tracemouse/\fBcurs_trace\fR(3X)* add_wch/\fBcurs_add_wch\fR(3X) add_wchnstr/\fBcurs_add_wchstr\fR(3X) add_wchstr/\fBcurs_add_wchstr\fR(3X) @@ -383,6 +372,7 @@ color_content/\fBcurs_color\fR(3X) color_set/\fBcurs_attr\fR(3X) copywin/\fBcurs_overlay\fR(3X) curs_set/\fBcurs_kernel\fR(3X) +curses_trace/\fBcurs_trace\fR(3X)* curses_version/\fBcurs_extend\fR(3X)* def_prog_mode/\fBcurs_kernel\fR(3X) def_shell_mode/\fBcurs_kernel\fR(3X) @@ -403,6 +393,8 @@ endwin/\fBcurs_initscr\fR(3X) erase/\fBcurs_clear\fR(3X) erasechar/\fBcurs_termattrs\fR(3X) erasewchar/\fBcurs_termattrs\fR(3X) +exit_curses/\fBcurs_memleaks\fR(3X)* +exit_terminfo/\fBcurs_memleaks\fR(3X)* extended_color_content/\fBcurs_color\fR(3X)* extended_pair_content/\fBcurs_color\fR(3X)* extended_slk_color/\fBcurs_slk\fR(3X)* @@ -441,6 +433,7 @@ has_colors/\fBcurs_color\fR(3X) has_ic/\fBcurs_termattrs\fR(3X) has_il/\fBcurs_termattrs\fR(3X) has_key/\fBcurs_getch\fR(3X)* +has_mouse/\fBcurs_mouse\fR(3X)* hline/\fBcurs_border\fR(3X) hline_set/\fBcurs_border_set\fR(3X) idcok/\fBcurs_outopts\fR(3X) @@ -589,18 +582,19 @@ napms/\fBcurs_kernel\fR(3X) newpad/\fBcurs_pad\fR(3X) newterm/\fBcurs_initscr\fR(3X) newwin/\fBcurs_window\fR(3X) -nl/\fBcurs_outopts\fR(3X) +nl/\fBcurs_inopts\fR(3X) nocbreak/\fBcurs_inopts\fR(3X) nodelay/\fBcurs_inopts\fR(3X) noecho/\fBcurs_inopts\fR(3X) nofilter/\fBcurs_util\fR(3X)* -nonl/\fBcurs_outopts\fR(3X) +nonl/\fBcurs_inopts\fR(3X) noqiflush/\fBcurs_inopts\fR(3X) noraw/\fBcurs_inopts\fR(3X) notimeout/\fBcurs_inopts\fR(3X) overlay/\fBcurs_overlay\fR(3X) overwrite/\fBcurs_overlay\fR(3X) pair_content/\fBcurs_color\fR(3X) +pecho_wchar/\fBcurs_pad\fR(3X)* pechochar/\fBcurs_pad\fR(3X) pnoutrefresh/\fBcurs_pad\fR(3X) prefresh/\fBcurs_pad\fR(3X) @@ -611,6 +605,7 @@ qiflush/\fBcurs_inopts\fR(3X) raw/\fBcurs_inopts\fR(3X) redrawwin/\fBcurs_refresh\fR(3X) refresh/\fBcurs_refresh\fR(3X) +reset_color_pairs/\fBcurs_color\fR(3X)* reset_prog_mode/\fBcurs_kernel\fR(3X) reset_shell_mode/\fBcurs_kernel\fR(3X) resetty/\fBcurs_kernel\fR(3X) @@ -632,7 +627,6 @@ set_term/\fBcurs_initscr\fR(3X) setcchar/\fBcurs_getcchar\fR(3X) setscrreg/\fBcurs_outopts\fR(3X) setsyx/\fBcurs_kernel\fR(3X) -setterm/\fBcurs_terminfo\fR(3X) setupterm/\fBcurs_terminfo\fR(3X) slk_attr/\fBcurs_slk\fR(3X)* slk_attr_off/\fBcurs_slk\fR(3X) @@ -650,6 +644,7 @@ slk_refresh/\fBcurs_slk\fR(3X) slk_restore/\fBcurs_slk\fR(3X) slk_set/\fBcurs_slk\fR(3X) slk_touch/\fBcurs_slk\fR(3X) +slk_wset/\fBcurs_slk\fR(3X)* standend/\fBcurs_attr\fR(3X) standout/\fBcurs_attr\fR(3X) start_color/\fBcurs_color\fR(3X) @@ -781,6 +776,19 @@ wunctrl/\fBcurs_util\fR(3X) wvline/\fBcurs_border\fR(3X) wvline_set/\fBcurs_border_set\fR(3X) .TE +.PP +Depending on the configuration, +additional sets of functions may be available: +.RS 3 +.TP 5 +\fBcurs_memleaks\fP(3X) - curses memory-leak checking +.TP 5 +\fBcurs_sp_funcs\fP(3X) - curses screen-pointer extension +.TP 5 +\fBcurs_threads\fP(3X) - curses thread support +.TP 5 +\fBcurs_trace\fP(3X) - curses debugging routines +.RE .SH RETURN VALUE Routines that return an integer return \fBERR\fR upon failure and an integer value other than \fBERR\fR upon successful completion, unless @@ -799,6 +807,13 @@ The return values of \fBgetmaxyx\fR are undefined (i.e., these should not be used as the right-hand side of assignment statements). .PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +Most \*(``mv\*(''-prefixed functions +(except variadic functions such as \fBmvprintw\fP) +are provided both as macros and functions. +.PP Routines that return pointers return \fBNULL\fR on error. .SH ENVIRONMENT .PP @@ -1290,6 +1305,32 @@ 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\-termlib +Low-level functions which do not depend upon whether the library +supports wide-characters, are provided in the tinfo library. +.IP +By doing this, it is possible to share the tinfo library between +wide/normal configurations as well as reduce the size of the library +when only low-level functions are needed. +.IP +Those functions are described in these pages: +.RS +.bP +\fBcurs_extend\fP(3X) \- miscellaneous curses extensions +.bP +\fBcurs_inopts\fR(3X) \- \fBcurses\fR input options +.bP +\fBcurs_kernel\fR(3X) \- low-level \fBcurses\fR routines +.bP +\fBcurs_termattrs\fR(3X) \- \fBcurses\fR environment query routines +.bP +\fBcurs_termcap\fR(3X) \- \fBcurses\fR emulation of termcap +.bP +\fBcurs_terminfo\fR(3X) \- \fBcurses\fR interfaces to terminfo database +.bP +\fBcurs_util\fR(3X) \- miscellaneous \fBcurses\fR utility routines +.RE +.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. @@ -1354,6 +1395,10 @@ The EXTENDED XSI Curses functionality A small number of local differences (that is, individual differences between the XSI Curses and \fBncurses\fR calls) are described in \fBPORTABILITY\fR sections of the library man pages. +.SS Error checking +.PP +In many cases, X/Open Curses is vague about error conditions, +omitting some of the SVr4 documentation. .PP Unlike other implementations, this one checks parameters such as pointers to WINDOW structures to ensure they are not null. @@ -1363,8 +1408,12 @@ The standard interface does not provide a way for the library to tell an application which of several possible errors were detected. Relying on this (or some other) extension will adversely affect the portability of curses applications. +.SS Extensions versus portability .PP -This implementation also contains several extensions: +Most of the extensions provided by ncurses have not been standardized. +Some have been incorporated into other implementations, such as +PDCurses or NetBSD curses. +Here are a few to consider: .bP The routine \fBhas_key\fR is not part of XPG4, nor is it present in SVr4. See the \fBcurs_getch\fR(3X) manual page for details. @@ -1394,6 +1443,7 @@ See \fBcurs_threads\fR(3X) for details. This implementation can also be configured to provide a set of functions which improve the ability to manage multiple screens. See \fBcurs_sp_funcs\fR(3X) for details. +.SS Padding differences .PP In historic curses versions, delays embedded in the capabilities \fBcr\fR, \fBind\fR, \fBcub1\fR, \fBff\fR and \fBtab\fR activated corresponding delay @@ -1402,10 +1452,103 @@ In this implementation, all padding is done by sending NUL bytes. This method is slightly more expensive, but narrows the interface to the UNIX kernel significantly and increases the package's portability correspondingly. -.SH NOTES +.SS Header files The header file \fB<curses.h>\fR automatically includes the header files \fB<stdio.h>\fR and \fB<unctrl.h>\fR. .PP +X/Open Curses has more to say, +but does not finish the story: +.RS 4 +.PP +The inclusion of <curses.h> may make visible all symbols +from the headers <stdio.h>, <term.h>, <termios.h>, and <wchar.h>. +.RE +.PP +Here is a more complete story: +.bP +Starting with BSD curses, all implementations have included <stdio.h>. +.IP +BSD curses included <curses.h> and <unctrl.h> from an internal header +"curses.ext" ("ext" was a short name for \fIexterns\fP). +.IP +BSD curses used <stdio.h> internally (for \fBprintw\fP and \fBscanw\fP), +but nothing in <curses.h> itself relied upon <stdio.h>. +.bP +SVr2 curses added \fBnewterm\fP(3X), which relies upon <stdio.h>. +That is, the function prototype uses \fBFILE\fP. +.IP +SVr4 curses added \fBputwin\fP and \fBgetwin\fP, which also use <stdio.h>. +.IP +X/Open Curses documents all three of these functions. +.IP +SVr4 curses and X/Open Curses do not require the developer to +include <stdio.h> before including <curses.h>. +Both document curses showing <curses.h> as the only required header. +.IP +As a result, standard <curses.h> will always include <stdio.h>. +.bP +X/Open Curses is inconsistent with respect to SVr4 regarding <unctrl.h>. +.IP +As noted in \fBcurs_util\fP(3X), ncurses includes <unctrl.h> from +<curses.h> (like SVr4). +.bP +X/Open's comments about <term.h> and <termios.h> may refer to HP-UX and AIX: +.IP +HP-UX curses includes <term.h> from <curses.h> +to declare \fBsetupterm\fP in curses.h, +but ncurses (and Solaris curses) do not. +.IP +AIX curses includes <term.h> and <termios.h>. +Again, ncurses (and Solaris curses) do not. +.bP +X/Open says that <curses.h> \fImay\fP include <term.h>, +but there is no requirement that it do that. +.IP +Some programs use functions declared in both <curses.h> and <term.h>, +and must include both headers in the same module. +Very old versions of AIX curses required including <curses.h> +before including <term.h>. +.IP +Because ncurses header files include the headers needed to +define datatypes used in the headers, +ncurses header files can be included in any order. +But for portability, you should include <curses.h> before <term.h>. +.bP +X/Open Curses says \fI"may make visible"\fP +because including a header file does not necessarily make all symbols +in it visible (there are ifdef's to consider). +.IP +For instance, in ncurses <wchar.h> \fImay\fP be included if +the proper symbol is defined, and if ncurses is configured for +wide-character support. +If the header is included, its symbols may be made visible. +That depends on the value used for \fB_XOPEN_SOURCE\fP +feature test macro. +.bP +X/Open Curses documents one required header, +in a special case: <stdarg.h> before <curses.h> to prototype +the \fBvw_printw\fP and \fBvw_scanw\fP functions +(as well as the obsolete +the \fBvwprintw\fP and \fBvwscanw\fP functions). +Each of those uses a \fBva_list\fP parameter. +.IP +The two obsolete functions were introduced in SVr3. +The other functions were introduced in X/Open Curses. +In between, SVr4 curses provided for the possibility that +an application might include either <varargs.h> or <stdarg.h>. +Initially, that was done by using \fBvoid*\fP for the \fBva_list\fP +parameter. +Later, a special type (defined in <stdio.h>) was introduced, +to allow for compiler type-checking. +That special type is always available, +because <stdio.h> is always included by <curses.h>. +.IP +None of the X/Open Curses implementations require an application +to include <stdarg.h> before <curses.h> because they either +have allowed for a special type, or (like ncurses) include <stdarg.h> +directly to provide a portable interface. +.SH NOTES +.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/man/new_pair.3x b/man/new_pair.3x index 3f1e3ac..98166a9 100644 --- a/man/new_pair.3x +++ b/man/new_pair.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -29,7 +29,7 @@ .\" .\" Author: Thomas E. Dickey .\" -.\" $Id: new_pair.3x,v 1.14 2020/02/02 23:34:34 tom Exp $ +.\" $Id: new_pair.3x,v 1.16 2021/06/17 21:26:02 tom Exp $ .TH new_pair 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -60,11 +60,11 @@ .SH SYNOPSIS \fB#include <curses.h>\fP .sp -\fBint alloc_pair(int fg, int bg);\fP +\fBint alloc_pair(int \fP\fIfg\fP\fB, int \fP\fIbg\fP\fB);\fP .br -\fBint find_pair(int fg, int bg);\fP +\fBint find_pair(int \fP\fIfg\fP\fB, int \fP\fIbg\fP\fB);\fP .br -\fBint free_pair(int pair);\fP +\fBint free_pair(int \fP\fIpair\fP\fB);\fP .SH DESCRIPTION These functions are an extension to the curses library. They permit an application to dynamically allocate a color pair using @@ -82,7 +82,7 @@ That is, the foreground and background colors are applied as a pair. .bP Color pairs are the curses library's way of managing a color palette on a terminal. -If the library does not keep track of the \fIcombinations\fP of +If the library does not keep track of the \fIcombinations\fP of colors which are displayed, it will be inefficient. .bP For simple terminal emulators @@ -94,7 +94,7 @@ as the limit on color pairs: .NE .bP Terminals which support \fIdefault colors\fP distinct -from \*(``ANSI colors\*('' +from \*(``ANSI colors\*('' add to the possible combinations, producing this total: .NS \fI( \fP\fBCOLORS\fP\fI + 1 ) * ( \fP\fBCOLORS\fP\fI + 1 )\fP @@ -104,7 +104,7 @@ An application might use up to a few dozen color pairs to implement a predefined color scheme. .IP Beyond that lies in the realm of programs using the foreground -and background colors for \*(``ASCII art\*('' +and background colors for \*(``ASCII art\*('' (or some other non-textual application). .IP Also beyond those few dozen pairs, the required size for a table diff --git a/man/panel.3x b/man/panel.3x index 32dd487..932ef48 100644 --- a/man/panel.3x +++ b/man/panel.3x @@ -27,12 +27,16 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: panel.3x,v 1.28 2020/02/02 23:34:34 tom Exp $ +.\" $Id: panel.3x,v 1.39 2020/02/15 21:06:40 tom Exp $ .TH panel 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` .ie \n(.g .ds '' \(rq .el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. .SH NAME panel \- panel stack extension for curses .SH SYNOPSIS @@ -40,35 +44,41 @@ panel \- panel stack extension for curses .P \fBcc [flags] sourcefiles \-lpanel \-lncurses\fR .P -\fBPANEL *new_panel(WINDOW *win);\fR +\fBPANEL *new_panel(WINDOW *\fIwin\fB);\fR +.sp +\fBint bottom_panel(PANEL *\fIpan\fB);\fR .br -\fBint bottom_panel(PANEL *pan);\fR +\fBint top_panel(PANEL *\fIpan\fB);\fR .br -\fBint top_panel(PANEL *pan);\fR -.br -\fBint show_panel(PANEL *pan);\fR +\fBint show_panel(PANEL *\fIpan\fB);\fR .br \fBvoid update_panels(void);\fR .br -\fBint hide_panel(PANEL *pan);\fR -.br -\fBWINDOW *panel_window(const PANEL *pan);\fR +\fBint hide_panel(PANEL *\fIpan\fB);\fR +.sp +\fBWINDOW *panel_window(const PANEL *\fIpan\fB);\fR .br -\fBint replace_panel(PANEL *pan, WINDOW *window);\fR +\fBint replace_panel(PANEL *\fIpan\fB, WINDOW *\fIwindow\fB);\fR .br -\fBint move_panel(PANEL *pan, int starty, int startx);\fR +\fBint move_panel(PANEL *\fIpan\fB, int \fIstarty\fB, int \fIstartx\fB);\fR .br -\fBint panel_hidden(const PANEL *pan);\fR +\fBint panel_hidden(const PANEL *\fIpan\fB);\fR +.sp +\fBPANEL *panel_above(const PANEL *\fIpan\fB);\fR .br -\fBPANEL *panel_above(const PANEL *pan);\fR +\fBPANEL *panel_below(const PANEL *\fIpan\fB);\fR +.sp +\fBint set_panel_userptr(PANEL *\fIpan\fB, const void *\fIptr\fB);\fR .br -\fBPANEL *panel_below(const PANEL *pan);\fR +\fBconst void *panel_userptr(const PANEL *\fIpan\fB);\fR +.sp +\fBint del_panel(PANEL *\fIpan\fB);\fR +.sp +/* ncurses-extensions */ .br -\fBint set_panel_userptr(PANEL *pan, const void *ptr);\fR +\fBPANEL *ground_panel(SCREEN *\fIsp\fB);\fR .br -\fBconst void *panel_userptr(const PANEL *pan);\fR -.br -\fBint del_panel(PANEL *pan);\fR +\fBPANEL *ceiling_panel(SCREEN *\fIsp\fB);\fR .br .SH DESCRIPTION Panels are \fBcurses\fR(3X) windows with the added feature of @@ -89,87 +99,113 @@ panel at any desired location in the stack. Panel routines are a functional layer added to \fBcurses\fR(3X), make only high-level curses calls, and work anywhere terminfo curses does. .SH FUNCTIONS -.TP -.B new_panel(win) -allocates a \fBPANEL\fR structure, associates it with -\fBwin\fR, places the panel on the top of the stack (causes it -to be displayed above any other panel) and returns a -pointer to the new panel. -.TP -.B update_panels -refreshes the \fIvirtual screen\fP to reflect the relations between the -panels in the stack, but does not call \fBdoupdate\fP to refresh the -\fIphysical screen\fP. -Use this function and not \fBwrefresh\fP or \fBwnoutrefresh\fP. -.B update_panels -may be called more than once before a call to -\fBdoupdate\fP, but \fBdoupdate\fP is the function responsible for updating -the \fIphysical screen\fP. -.TP -.B del_panel(pan) -removes the given panel from the stack and deallocates the +.\" --------- +.SS bottom_panel +\fBbottom_panel(\fIpan\fB)\fR +puts panel \fIpan\fP at the bottom of all panels. +.\" --------- +.SS ceiling_panel +\fBceiling_panel(\fIsp\fB)\fR +acts like \fBpanel_below(NULL)\fP, for the given \fBSCREEN\fP \fIsp\fP. +.\" --------- +.SS del_panel +\fBdel_panel(\fIpan\fB)\fR +removes the given panel \fIpan\fP from the stack and deallocates the \fBPANEL\fR structure (but not its associated window). -.TP -.B hide_panel(pan) -removes the given panel from the panel stack and thus hides it from -view. +.\" --------- +.SS ground_panel +\fBground_panel(\fIsp\fB)\fR +acts like \fBpanel_above(NULL)\fP, for the given \fBSCREEN\fP \fIsp\fP. +.\" --------- +.SS hide_panel +\fBhide_panel(\fIpan\fB)\fR +removes the given panel \fIpan\fP from the panel stack +and thus hides it from view. The \fBPANEL\fR structure is not lost, merely removed from the stack. -.TP -.B panel_hidden(pan) -returns \fBTRUE\fP if the panel is in the panel stack, -\fBFALSE\fP if it is not. -If the panel is a null pointer, return \fBERR\fP. -.TP -.B show_panel(pan) -makes a hidden panel visible by placing it on top of the panels in the -panel stack. -See COMPATIBILITY below. -.TP -.B top_panel(pan) -puts the given visible panel on top of all panels in the stack. -See -COMPATIBILITY below. -.TP -.B bottom_panel(pan) -puts panel at the bottom of all panels. -.TP -.B move_panel(pan,starty,startx) -moves the given panel window so that its upper-left corner is at -\fBstarty\fR, \fBstartx\fR. -It does not change the position of the -panel in the stack. -Be sure to use this function, not \fBmvwin\fR, -to move a panel window. -.TP -.B replace_panel(pan,window) -replaces the current window of panel with \fBwindow\fR (useful, for -example if you want to resize a panel; if you're using \fBncurses\fR, -you can call \fBreplace_panel\fR on the output of \fBwresize\fR(3X)). +.\" --------- +.SS move_panel +\fBmove_panel(\fIpan\fB,\fIstarty\fB,\fIstartx\fB)\fR +moves the given panel \fIpan\fP's window so that its upper-left corner is at +\fIstarty\fR, \fIstartx\fR. It does not change the position of the panel in the stack. -.TP -.B panel_above(pan) -returns a pointer to the panel above pan. +Be sure to use this function, not \fBmvwin\fR(3X), to move a panel window. +.\" --------- +.SS new_panel +\fBnew_panel(\fIwin\fB)\fR allocates a \fBPANEL\fR structure, +associates it with \fIwin\fR, places the panel on the top of the stack +(causes it to be displayed above any other panel) and returns a +pointer to the new panel. +.\" --------- +.SS panel_above +\fBpanel_above(\fIpan\fB)\fR +returns a pointer to the panel above \fIpan\fP. If the panel argument is \fB(PANEL *)0\fR, it returns a pointer to the bottom panel in the stack. -.TP -.B panel_below(pan) -returns a pointer to the panel just below pan. +.\" --------- +.SS panel_below +\fBpanel_below(\fIpan\fB)\fR +returns a pointer to the panel just below \fIpan\fP. If the panel argument is \fB(PANEL *)0\fR, it returns a pointer to the top panel in the stack. -.TP -.B set_panel_userptr(pan,ptr) +.\" --------- +.SS panel_hidden +\fBpanel_hidden(\fIpan\fB)\fR +returns \fBTRUE\fP if the panel \fIpan\fP is in the panel stack, +\fBFALSE\fP if it is not. +If the panel is a null pointer, return \fBERR\fP. +.\" --------- +.SS panel_userptr +\fBpanel_userptr(\fIpan\fB)\fR +returns the user pointer for a given panel \fIpan\fP. +.\" --------- +.SS panel_window +\fBpanel_window(\fIpan\fB)\fR +returns a pointer to the window of the given panel \fIpan\fP. +.\" --------- +.SS replace_panel +\fBreplace_panel(\fIpan\fB,\fIwindow\fB)\fR +replaces the current window of panel \fIpan\fP with \fIwindow\fR +This is useful, for example if you want to resize a panel. +In \fBncurses\fR, you can call \fBreplace_panel\fR +to resize a panel using a window resized with \fBwresize\fR(3X). +It does not change the position of the panel in the stack. +.\" --------- +.SS set_panel_userptr +\fBset_panel_userptr(\fIpan\fB,\fIptr\fB)\fR sets the panel's user pointer. -.TP -.B panel_userptr(pan) -returns the user pointer for a given panel. -.TP -.B panel_window(pan) -returns a pointer to the window of the given panel. +.\" --------- +.SS show_panel +\fBshow_panel(\fIpan\fB)\fR +makes a hidden panel visible by placing it on top of the panels in the +panel stack. +See \fBCOMPATIBILITY\fP below. +.\" --------- +.SS top_panel +\fBtop_panel(\fIpan\fB)\fR +puts the given visible panel \fIpan\fP on top of all panels in the stack. +See \fBCOMPATIBILITY\fP below. +.\" --------- +.SS update_panels +\fBupdate_panels()\fR +refreshes the \fIvirtual screen\fP to reflect the relations between the +panels in the stack, but does not call \fBdoupdate\fP(3X) to refresh the +\fIphysical screen\fP. +Use this function and not \fBwrefresh\fP(3X) or \fBwnoutrefresh\fP(3X). +.PP +\fBupdate_panels\fP may be called more than once before a call to +\fBdoupdate\fP, but \fBdoupdate\fP is the function responsible for updating +the \fIphysical screen\fP. .SH DIAGNOSTICS Each routine that returns a pointer returns \fBNULL\fR if an error occurs. Each routine that returns an int value returns \fBOK\fR if it executes successfully and \fBERR\fR if not. +.PP +Except as noted, the \fIpan\fP and \fIwindow\fP parameters must be non-null. +If those are null, an error is returned. +.PP +The \fBmove_panel\fP function uses \fBmvwin\fP(3X), +and will return an error if \fBmvwin\fP returns an error. .SH COMPATIBILITY Reasonable care has been taken to ensure compatibility with the native panel facility introduced in System V (inspection of @@ -198,8 +234,27 @@ The panel facility was documented in SVr4.2 in .PP It is not part of X/Open Curses. .PP -Aside from ncurses, only systems based on SVr4 source code, -e.g., Solaris provide this library. +A few implementations exist: +.bP +Systems based on SVr4 source code, +e.g., Solaris, provide this library. +.bP +\fBncurses\fP (since version 0.6 in 1993) +and \fBPDCurses\fP (since version 2.2 in 1995) +provide a panel library whose common ancestor +was a public domain implementation by Warren Tucker +published in \fIu386mon\fP 2.20 (1990). +.IP +According to Tucker, the SystemV panel library +was first released in SVr3.2 (1988), +and his implementation helped with a port to SVr3.1 (1987). +.IP +Several developers have improved each of these; +they are no longer the same as Tucker's implementation. +.bP +NetBSD 8 (2018) +has a panel library begun by Valery Ushakov in 2015. +This is based on the AT&T documentation. .SH FILES .P panel.h @@ -214,7 +269,11 @@ the panels library itself This describes \fBncurses\fR version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). .SH AUTHOR +.PP Originally written by Warren Tucker <wht@n4hgf.mt-park.ga.us>, -primarily to assist in porting u386mon to systems without a native +primarily to assist in porting \fIu386mon\fP to systems without a native panels library. +.PP Repackaged for ncurses by Zeyd ben-Halim. +.PP +Juergen Pfeifer and Thomas E. Dickey revised/improved the library. diff --git a/man/resizeterm.3x b/man/resizeterm.3x index 5f2bc93..ae5106e 100644 --- a/man/resizeterm.3x +++ b/man/resizeterm.3x @@ -29,7 +29,7 @@ .\" .\" Author: Thomas E. Dickey 1996-on .\" -.\" $Id: resizeterm.3x,v 1.27 2020/02/02 23:34:34 tom Exp $ +.\" $Id: resizeterm.3x,v 1.28 2020/10/17 23:55:41 tom Exp $ .TH resizeterm 3X "" .de bP .ie n .IP \(bu 4 @@ -42,11 +42,11 @@ .SH SYNOPSIS \fB#include <curses.h>\fR .sp -\fBbool is_term_resized(int lines, int columns);\fR +\fBbool is_term_resized(int \fP\fIlines\fP\fB, int \fP\fIcolumns\fP\fB);\fR .br -\fBint resize_term(int lines, int columns);\fR +\fBint resize_term(int \fP\fIlines\fP\fB, int \fP\fIcolumns\fP\fB);\fR .br -\fBint resizeterm(int lines, int columns);\fR +\fBint resizeterm(int \fP\fIlines\fP\fB, int \fP\fIcolumns\fP\fB);\fR .SH DESCRIPTION .PP This is an extension to the curses library. diff --git a/man/scr_dump.5 b/man/scr_dump.5 index 7ef68cd..43ee58c 100644 --- a/man/scr_dump.5 +++ b/man/scr_dump.5 @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: scr_dump.5,v 1.16 2020/02/02 23:34:34 tom Exp $ +.\" $Id: scr_dump.5,v 1.17 2021/06/17 21:26:02 tom Exp $ .TH scr_dump 5 .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -353,31 +353,31 @@ VMIN=1 VTIME=0 FLAGS=0x1000 FG=0,0 -BG=0,0, +BG=0,0, 0,0,0,1, -0,19,0,0, +0,19,0,0, 1,0,0,1, -1,19,0,0, +1,19,0,0, 2,0,0,1, -2,19,0,0, +2,19,0,0, 3,0,0,1, -3,19,0,0, +3,19,0,0, 4,0,0,1, 4,5,0x20,0,Hello 4,10,0,1, -4,19,0,0, +4,19,0,0, 5,0,0,1, 5,5,0x4,2,World! 5,11,0,1, -5,19,0,0, +5,19,0,0, 6,0,0,1, -6,19,0,0, +6,19,0,0, 7,0,0,1, -7,19,0,0, +7,19,0,0, 8,0,0,1, -8,19,0,0, +8,19,0,0, 9,0,0,1, -9,19,0,0, +9,19,0,0, CUR=11,5 .NE .PP @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 2008-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tabs.1,v 1.27 2020/02/02 23:34:34 tom Exp $ +.\" $Id: tabs.1,v 1.32 2021/10/16 13:37:43 tom Exp $ .TH @TABS@ 1 "" .ds n 5 .ie \n(.g .ds `` \(lq @@ -140,34 +140,78 @@ tabs 1,+5,+5,+5,+5 .PP which is equivalent to the 1,6,11,16,21 example. .SS Predefined Tab-Stops -X/Open defines several predefined lists of tab stops. +POSIX defines several predefined lists of tab stops. .TP 5 .B \-a Assembler, IBM S/370, first format +.br +1,10,16,36,72 .TP 5 .B \-a2 Assembler, IBM S/370, second format +.br +1,10,16,40,72 .TP 5 .B \-c COBOL, normal format +.br +1,8,12,16,20,55 .TP 5 .B \-c2 COBOL compact format +.br +1,6,10,14,49 .TP 5 .B \-c3 COBOL compact format extended +.br +1,6,10,14,18,22,26,30,34,38,42,46,50,54,58,62,67 .TP 5 .B \-f FORTRAN +.br +1,7,11,15,19,23 .TP 5 .B \-p PL/I +.br +1,5,9,13,17,21,25,29,33,37,41,45,49,53,57,61 .TP 5 .B \-s SNOBOL +.br +1,10,55 .TP 5 .B \-u UNIVAC 1100 Assembler +.br +1,12,20,44 +.SS Margins +A few terminals provide the capability for changing their left/right margins. +The @TABS@ program has an option to use this feature: +.TP 5 +.BI \+m \ margin +The effect depends on whether the terminal has the margin capabilities: +.RS +.bP +If the terminal provides the capability for setting the left margin, +@TABS@ uses this, and adjusts the available width for tab-stops. +.bP +If the terminal does not provide the margin capabilities, +@TABS@ imitates the effect, putting the tab stops at the appropriate +place on each line. +The terminal's left-margin is not modified. +.RE +.IP +If the \fImargin\fP parameter is omitted, the default is 10. +Use \fB\+m0\fP to reset the left margin, +i.e., to the left edge of the terminal's display. +Before setting a left-margin, +@TABS@ resets the margin to reduce problems which might arise +on moving the cursor before the current left-margin. +.PP +When setting or resetting the left-margin, +@TABS@ may reset the right-margin. .SH PORTABILITY .PP \fIIEEE Std 1003.1/The Open Group Base Specifications Issue 7\fP (POSIX.1-2008) @@ -181,7 +225,7 @@ Very few of the entries in the terminal database provide the capability needed to support the feature. .bP There is no counterpart in X/Open Curses Issue 7 for this utility, -unlike \fB@TPUT@(1)\fP. +unlike \fB@TPUT@\fP(1). .PP The \fB\-d\fP (debug) and \fB\-n\fP (no-op) options are extensions not provided by other implementations. @@ -195,17 +239,28 @@ That option is not documented by POSIX. .PP The PWB/Unix \fBtabs\fP utility, which was included in System III (1980), used built-in tables rather than the terminal database, -to support a half-dozen terminal types. +to support a half-dozen hardcopy terminal (printer) types. It also had built-in logic to support the left-margin, as well as a feature for copying the tab settings from a file. .PP Later versions of Unix, e.g., SVr4, added support for the terminal database, -but kept the tables, as a fallback. +but kept the tables to support the printers. In an earlier development effort, the tab-stop initialization provided by \fBtset\fP (1982) and incorporated into \fBtput\fP uses the terminal database, .PP +The \fB\+m\fP option was documented +in the Base Specifications Issue 5 (Unix98, 1997), +and omitted in Issue 6 (Unix03, 2004) without documenting the rationale, +though an introductory comment +\fI\*(``and optionally adjusts the margin\*(''\fP remains, +overlooked in the removal. +The documented \fBtabs\fP utility in Issues 6 and later has no mechanism +for setting margins. +The \fB\+m\fP option in this implementation differs from the feature +in SVr4 by using terminal capabilities rather than built-in tables. +.PP POSIX documents no limits on the number of tab stops. Documentation for other implementations states that there is a limit on the number of tab stops @@ -229,8 +284,8 @@ However, the \fIExplicit Lists\fP described in this manual page were implemented in PWB/Unix. Those provide the capability of setting abitrary tab stops. .SH SEE ALSO -\fB@TSET@\fR(1), \fB@INFOCMP@\fR(1M), +\fB@TSET@\fR(1), \fBcurses\fR(3X), \fBterminfo\fR(\*n). .PP @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: term.5,v 1.33 2020/02/02 23:34:34 tom Exp $ +.\" $Id: term.5,v 1.40 2021/08/15 19:38:47 tom Exp $ .TH term 5 .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -99,83 +99,116 @@ or sign extension are made. The compiled file is created with the \fB@TIC@\fP program, and read by the routine \fBsetupterm\fP(3X). The file is divided into six parts: -the header, -terminal names, -boolean flags, -numbers, -strings, -and -string table. +.RS 5 +.TP 3 +a) \fIheader\fP, +.TP 3 +b) \fIterminal names\fP, +.TP 3 +c) \fIboolean flags\fP, +.TP 3 +d) \fInumbers\fP, +.TP 3 +e) \fIstrings\fP, and +.TP 3 +f) \fIstring table\fP. +.RE .PP -The header section begins the file. +The \fIheader\fP section begins the file. This section contains six short integers in the format described below. These integers are .RS 5 .TP 5 -(1) the magic number (octal 0432); +(1) the \fImagic number\fP (octal 0432); .TP 5 -(2) the size, in bytes, of the names section; +(2) the size, in bytes, of the \fIterminal names\fP section; .TP 5 -(3) the number of bytes in the boolean section; +(3) the number of bytes in the \fIboolean flags\fP section; .TP 5 -(4) the number of short integers in the numbers section; +(4) the number of short integers in the \fInumbers\fP section; .TP 5 -(5) the number of offsets (short integers) in the strings section; +(5) the number of offsets (short integers) in the \fIstrings\fP section; .TP 5 -(6) the size, in bytes, of the string table. +(6) the size, in bytes, of the \fIstring table\fP. .RE .PP -Short integers are stored in two 8-bit bytes. +The capabilities in the +\fIboolean flags\fP, +\fInumbers\fP, and +\fIstrings\fP +sections are in the same order as the file <term.h>. +.PP +Short integers are signed, in the range \-32768 to 32767. +They are stored as two 8-bit bytes. The first byte contains the least significant 8 bits of the value, and the second byte contains the most significant 8 bits. (Thus, the value represented is 256*second+first.) -The value \-1 is represented by the two bytes 0377, 0377; other negative -values are illegal. -This value generally -means that the corresponding capability is missing from this terminal. -Note that this format corresponds to the hardware of the \s-1VAX\s+1 +This format corresponds to the hardware of the \s-1VAX\s+1 and \s-1PDP\s+1-11 (that is, little-endian machines). Machines where this does not correspond to the hardware must read the integers as two bytes and compute the little-endian value. .PP -The terminal names section comes next. +Numbers in a terminal description, +whether they are entries in the \fInumbers\fP or \fIstrings\fP table, +are positive integers. +Boolean flags are treated as positive one-byte integers. +In each case, those positive integers represent a terminal capability. +The terminal compiler @TIC@ uses negative integers to handle the cases where +a capability is not available: +.bP +If a capability is absent from this terminal, +@TIC@ stores a \-1 in the corresponding table. +.IP +The integer value \-1 is represented by two bytes 0377, 0377. +.br +Absent boolean values are represented by the byte 0 (false). +.bP +If a capability has been canceled from this terminal, +@TIC@ stores a \-2 in the corresponding table. +.IP +The integer value \-2 is represented by two bytes 0377, 0376. +.br +The boolean value \-2 is represented by the byte 0376. +.br +.bP +Other negative values are illegal. +.PP +The \fIterminal names\fP section comes after the \fIheader\fP. It contains the first line of the terminfo description, listing the various names for the terminal, separated by the \*(``|\*('' character. -The section is terminated with an \s-1ASCII NUL\s+1 character. +The \fIterminal names\fP section is terminated +with an \s-1ASCII NUL\s+1 character. .PP -The boolean flags have one byte for each flag. -This byte is either 0 or 1 as the flag is present or absent. -The capabilities are in the same order as the file <term.h>. +The \fIboolean flags\fP section has one byte for each flag. +Boolean capabilities are either 1 or 0 (true or false) +according to whether the terminal supports the given capability or not. .PP -Between the boolean section and the number section, +Between the \fIboolean flags\fP section and the \fInumber\fP section, a null byte will be inserted, if necessary, -to ensure that the number section begins on an even byte (this is a -relic of the PDP\-11's word-addressed architecture, originally -designed in to avoid IOT traps induced by addressing a word on an -odd byte boundary). +to ensure that the \fInumber\fP section begins on an even byte +This is a relic of the PDP\-11's word-addressed architecture, +originally designed to avoid traps induced +by addressing a word on an odd byte boundary. All short integers are aligned on a short word boundary. .PP -The numbers section is similar to the flags section. +The \fInumbers\fP section is similar to the \fIboolean flags\fP section. Each capability takes up two bytes, and is stored as a little-endian short integer. -If the value represented is \-1, the capability is taken to be missing. .PP -The strings section is also similar. -Each capability is stored as a short integer, in the format above. -A value of \-1 means the capability is missing. -Otherwise, the value is taken as an offset from the beginning -of the string table. +The \fIstrings\fP section is also similar. +Each capability is stored as a short integer. +The capability value is an index into the \fIstring table\fP. +.PP +The \fIstring table\fP is the last section. +It contains all of the values of string capabilities referenced in +the \fIstrings\fP section. +Each string is null-terminated. Special characters in ^X or \ec notation are stored in their interpreted form, not the printing representation. Padding information $<nn> and parameter information %x are stored intact in uninterpreted form. -.PP -The final section is the string table. -It contains all the values of string capabilities referenced in -the string section. -Each string is null terminated. .SS EXTENDED STORAGE FORMAT The previous section describes the conventional terminfo binary format. With some minor variations of the offsets (see PORTABILITY), @@ -253,7 +286,7 @@ to expect a different set of capabilities than are actually present in the file. Either the database may have been updated since .B setupterm -has been recompiled +was recompiled (resulting in extra unrecognized entries in the file) or the program may have been recompiled more recently than the database was updated @@ -361,8 +394,13 @@ total compiled entries cannot exceed 4096 bytes in the legacy format. total compiled entries cannot exceed 32768 bytes in the extended format. .bP the name field cannot exceed 128 bytes. +.PP +Compiled entries are limited to 32768 bytes because offsets into the +\fIstrings table\fP use two-byte integers. +The legacy format could have supported 32768-byte entries, +but was limited a virtual memory page's 4096 bytes. .SH FILES -\*d/*/* compiled terminal capability data base +\*d/*/* compiled terminal capability database .SH SEE ALSO \fBcurses\fR(3X), \fBterminfo\fR(\*n). .SH AUTHORS @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2011,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: term.7,v 1.28 2020/02/02 23:34:34 tom Exp $ +.\" $Id: term.7,v 1.30 2021/08/15 19:39:57 tom Exp $ .TH term 7 .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -61,7 +61,7 @@ There can be problems if the remote terminfo or termcap entry for your type is not compatible with yours, but this situation is rare and can almost always be avoided by explicitly exporting \*(``vt100\*('' (assuming you are in fact using a VT100-superset console, -terminal, or terminal emulator.) +terminal, or terminal emulator). .PP In any case, you are free to override the system \fBTERM\fR setting to your taste in your shell profile. @@ -213,7 +213,7 @@ should be unique within the first 14 characters. .SH FILES .TP 5 \*d/?/* -compiled terminal capability data base +compiled terminal capability database .TP 5 /etc/inittab tty line initialization (AT&T-like UNIXes) diff --git a/man/terminfo.head b/man/terminfo.head index f6a31c8..15be24e 100644 --- a/man/terminfo.head +++ b/man/terminfo.head @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: terminfo.head,v 1.39 2020/02/02 23:34:34 tom Exp $ +.\" $Id: terminfo.head,v 1.41 2021/08/15 19:32:53 tom Exp $ .TH terminfo 5 "" "" "File Formats" .ds n 5 .ds d @TERMINFO@ @@ -54,12 +54,12 @@ .el .in -2 .. .SH NAME -terminfo \- terminal capability data base +terminfo \- terminal capability database .SH SYNOPSIS \*d/*/* .SH DESCRIPTION .I Terminfo -is a data base describing terminals, +is a database describing terminals, used by screen-oriented programs such as \fBnvi\fR(1), \fBlynx\fR(1), @@ -83,7 +83,7 @@ Entries in .I terminfo consist of a sequence of fields: .bP -Each field ends with a comma \*(``,\*('' +Each field ends with a comma \*(``,\*('' (embedded commas may be escaped with a backslash or written as \*(``\\054\*(''). .bP diff --git a/man/terminfo.tail b/man/terminfo.tail index f6ccf6b..d3cbbf3 100644 --- a/man/terminfo.tail +++ b/man/terminfo.tail @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: terminfo.tail,v 1.99 2020/02/02 23:34:34 tom Exp $ +.\" $Id: terminfo.tail,v 1.108 2021/10/09 23:13:23 tom Exp $ .ps +1 .SS User-Defined Capabilities . @@ -197,7 +197,7 @@ The reason for this quirk is to maintain binary compatibility of the compiled terminfo files with other implementations, e.g., the SVr4 systems, which document this. Compiled terminfo files use null-terminated strings, with no lengths. -Modifying this would require a new binary format, +Modifying this would require a new binary format, which would not work with other implementations. .PP Finally, characters may be given as three octal digits after a \fB\e\fR. @@ -442,8 +442,8 @@ The parameter mechanism uses a stack and special \fB%\fP codes to manipulate it. Typically a sequence will push one of the parameters onto the stack and then print it in some format. -Print (e.g., "%d") is a special case. -Other operations, including "%t" pop their operand from the stack. +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 @@ -483,9 +483,39 @@ 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(3X). However, that fact is not documented in other implementations. -Relying on it will adversely impact portability to other implementations. +Relying on it will adversely impact portability to other implementations: +.RS +.bP +SVr2 curses supported \fIdynamic\fP variables. +Those are set only by a \fB%P\fP operator. +A \fB%g\fP for a given variable without first setting it with \fB%P\fP +will give unpredictable results, because dynamic variables are +an uninitialized local array on the stack in the \fBtparm\fP function. +.bP +SVr3.2 curses supported \fIstatic\fP variables. +Those are an array in the \fBTERMINAL\fP +structure (declared in \fBterm.h\fP), +and are zeroed automatically when the \fBsetupterm\fP function +allocates the data. +.bP +SVr4 curses made no further improvements +to the \fIdynamic/static\fP variable feature. +.bP +Solaris XPG4 curses does not distinguish between \fIdynamic\fP and +\fIstatic\fP variables. +They are the same. +Like SVr4 curses, XPG4 curses does not initialize these explicitly. +.bP +Before version 6.3, ncurses stores both \fIdynamic\fP and \fIstatic\fP +variables in persistent storage, initialized to zeros. +.bP +Beginning with version 6.3, ncurses stores \fIstatic\fP and \fIdynamic\fP +variables in the same manner as SVr4. +Unlike other implementations, ncurses zeros dynamic variables +before the first \fB%g\fP or \fB%P\fP operator. +.RE .TP -\fB%'\fP\fIc\fP\fB'\fP +\fB%\(aq\fP\fIc\fP\fB\(aq\fP char constant \fIc\fP .TP \fB%{\fP\fInn\fP\fB}\fP @@ -533,7 +563,7 @@ 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}%-". +That is, to get x\-5 one would use \*(``%gx%{5}%\-\*(''. \fB%P\fP and \fB%g\fP variables are persistent across escape-string evaluations. .PP @@ -557,7 +587,7 @@ tabs are never expanded, so \et is safe to send. This turns out to be essential for the Ann Arbor 4080.) .PP A final example is the \s-1LSI ADM\s0-3a, which uses row and column -offset by a blank character, thus \*(``cup=\eE=%p1%' '%+%c%p2%' '%+%c\*(''. +offset by a blank character, thus \*(``cup=\eE=%p1%\(aq \(aq%+%c%p2%\(aq \(aq%+%c\*(''. After sending \*(``\eE=\*('', this pushes the first parameter, pushes the ASCII value for a space (32), adds them (pushing the sum on the stack in place of the two previous values) and outputs that value as a character. @@ -617,6 +647,131 @@ If the \fBsmcup\fP sequence will not restore the screen after an \fBrmcup\fP sequence is output (to the state prior to outputting \fBrmcup\fP), specify \fBnrrmc\fP. .PP +.SS Margins +SVr4 (and X/Open Curses) +list several string capabilities for setting margins. +Two were intended for use with terminals, +and another six were intended for use with printers. +.bP +The two terminal capabilities assume that the terminal may have +the capability of setting the left and/or right margin at the current +cursor column position. +.bP +The printer capabilities assume that the printer may have +two types of capability: +.RS +.bP +the ability to set a top and/or bottom margin using the current +line position, and +.bP +parameterized capabilities for setting the top, bottom, left, right margins +given the number of rows or columns. +.RE +.RE +.PP +In practice, the categorization into \*(``terminal\*('' and \*(``printer\*('' +is not suitable: +.bP +The AT&T SVr4 terminal database uses \fBsmgl\fP four times, +for AT&T hardware. +.IP +Three of the four are printers. +They lack the ability to set left/right margins by specifying the column. +.bP +Other (non-AT&T) terminals may support margins +but using different assumptions from AT&T. +.IP +For instance, the DEC VT420 supports left/right margins, +but only using a column parameter. +As an added complication, the VT420 uses two settings to fully enable +left/right margins (left/right margin mode, and origin mode). +The former enables the margins, which causes printed text +to wrap within margins, but the latter is needed to prevent +cursor-addressing outside those margins. +.bP +Both DEC VT420 left/right margins are set with a single control sequence. +If either is omitted, the corresponding margin is set to the left or +right edge of the display (rather than leaving the margin unmodified). +.PP +These are the margin-related capabilities: +.TS +center; +l l +_ _ +lw8 lw18. +\fBName Description\fP +smgl Set left margin at current column +smgr Set right margin at current column +smgb Set bottom margin at current line +smgt Set top margin at current line +smgbp Set bottom margin at line \fIN\fP +smglp Set left margin at column \fIN\fP +smgrp Set right margin at column \fIN\fP +smgtp Set top margin at line \fIN\fP +smglr Set both left and right margins to \fIL\fP and \fIR\fP +smgtb Set both top and bottom margins to \fIT\fP and \fIB\fP +.TE +.PP +When writing an application that +uses these string capabilities, +the pairs should be first checked to see +if each capability in the pair is set or only one is set: +.bP +If both \fBsmglp\fP and \fBsmgrp\fP are set, +each is used with a single argument, \fIN\fP, +that gives the column number of the left and right margin, respectively. +.bP +If both \fBsmgtp\fP and \fBsmgbp\fP are set, +each is used to set the top and bottom margin, +respectively: +.RS 4 +.bP +\fBsmgtp\fP is used with a single argument, \fIN\fP, +the line number of the top margin. +.bP +\fBsmgbp\fP is used with two arguments, \fIN\fP and \fIM\fP, +that give the line number of the bottom margin, +the first counting from the top of the +page and the second counting from the bottom. +This accommodates the two styles of specifying +the bottom margin in different manufacturers' printers. +.RE +.IP +When designing a terminfo entry for a +printer that has a settable bottom margin, +only the first or second argument should be used, depending on the printer. +When developing an application that uses \fBsmgbp\fP to set the bottom margin, +both arguments must be given. +.PP +Conversely, when only one capability in the pair is set: +.bP +If only one of \fBsmglp\fP and \fBsmgrp\fP is set, +then it is used with two arguments, +the column number of the left and right margins, in that order. +.bP +Likewise, if only one of \fBsmgtp\fP and \fBsmgbp\fP is set, then it +is used with two arguments that give the top and bottom margins, +in that order, counting from the top of the page. +.IP +When designing a terminfo entry for a printer that requires setting both +left and right or top and bottom margins simultaneously, +only one capability in the pairs +\fBsmglp\fP and \fBsmgrp\fP or +\fBsmgtp\fP and \fBsmgbp\fP should be defined, +leaving the other unset. +.PP +Except for very old terminal descriptions, e.g., those developed for SVr4, +the scheme just described should be considered obsolete. +An improved set of capabilities was added late in the SVr4 releases +(\fBsmglr\fP and \fBsmgtb\fP), +which explicitly use two parameters for setting the left/right or top/bottom +margins. +.PP +When setting margins, the line- and column-values are zero-based. +.PP +The \fBmgc\fP string capability should be defined. +Applications such as \fBtabs\fP(1) rely upon this to reset all margins. +.\" .SS Area Clears .PP If the terminal can clear from the current position to the end of the @@ -632,6 +787,7 @@ if a true .B ed is not available.) .PP +.\" .SS Insert/delete line and vertical motions .PP If the terminal can open a new blank line before the line where the cursor @@ -1238,7 +1394,7 @@ The \fB@RESET@\fP program writes strings including .BR iprog , etc., in the same order as the .I init -program, using +program, using .BR rs1 , etc., instead of .BR is1 , @@ -1625,7 +1781,7 @@ this can be indicated with the parameterized string .BR rep . The first parameter is the character to be repeated and the second is the number of times to repeat it. -Thus, tparm(repeat_char, 'x', 10) is the same as \*(``xxxxxxxxxx\*(''. +Thus, tparm(repeat_char, \(aqx\(aq, 10) is the same as \*(``xxxxxxxxxx\*(''. .PP If the terminal has a settable command character, such as the \s-1TEKTRONIX\s+1 4025, this can be indicated with @@ -1831,7 +1987,7 @@ binary format) collide with System V and XSI Curses extensions. .SH EXTENSIONS .PP Searching for terminal descriptions in -\fB$HOME/.terminfo\fR and TERMINFO_DIRS +\fB$HOME/.terminfo\fR and TERMINFO_DIRS is not supported by older implementations. .PP Some SVr4 \fBcurses\fR implementations, and all previous to SVr4, do not @@ -1905,15 +2061,15 @@ Supports both the SVr4 set and the AIX extensions. \*d/?/* files containing terminal descriptions .SH SEE ALSO +\fB@INFOCMP@\fR(1M), \fB@TABS@\fR(1), \fB@TIC@\fR(1M), -\fB@INFOCMP@\fR(1M), \fBcurses\fR(3X), \fBcurs_color\fR(3X), \fBcurs_variables\fR(3X), \fBprintf\fR(3), -\fBterm\fR(\*n). \fBterm_variables\fR(3X). +\fBterm\fR(\*n). \fBuser_caps\fR(5). .SH AUTHORS Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tic.1m,v 1.77 2020/02/02 23:34:34 tom Exp $ +.\" $Id: tic.1m,v 1.80 2021/08/15 20:01:19 tom Exp $ .TH @TIC@ 1M "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -279,7 +279,7 @@ Suppress comments and blank lines when showing translated source. \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 +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 @@ -443,7 +443,7 @@ The exceptions were .PP Eric Raymond incorporated parts of \fImytinfo\fP into ncurses to implement the termcap-to-terminfo source conversion, -and extended that to begin development of +and extended that to begin development of the corresponding terminfo-to-termcap source conversion, Thomas Dickey completed that development over the course of several years. .PP @@ -528,7 +528,7 @@ error messages, and can be parsed by GNU Emacs's compile facility. .PP Aside from \fB\-c\fP and \fB\-v\fP, options are not portable: .bP -Most of @TIC@'s options +Most of @TIC@'s options are not supported by SVr4 \fBtic\fP: .sp .RS @@ -573,8 +573,8 @@ 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@INFOCMP@\fR(1M), \fB@INFOTOCAP@\fR(1M), \fB@TOE@\fR(1M), \fBcurses\fR(3X), @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2019,2020 Thomas E. Dickey * +.\" Copyright 2019-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: toe.1m,v 1.32 2020/02/02 23:34:34 tom Exp $ +.\" $Id: toe.1m,v 1.34 2021/06/17 21:26:02 tom Exp $ .TH @TOE@ 1M "" .de bP .ie n .IP \(bu 4 @@ -78,7 +78,7 @@ rather than only the first one that it finds. .IP If the \fB\-s\fR is also given, \fB@TOE@\fR adds a column to the report, -showing (like \fBconflict\fP(1)) which entries which +showing (like \fBconflict\fP(1)) which entries which belong to a given terminal database. An "*" marks entries which differ, and "+" marks equivalent entries. .IP @@ -168,7 +168,7 @@ Compiled terminal description database. .SH HISTORY This utility is not provided by other implementations. There is no relevant X/Open or POSIX standard for \fB@TOE@\fP. -.PP +.PP The program name refers to a developer's pun: .bP \fBtic\fP, @@ -180,13 +180,13 @@ The program name refers to a developer's pun: It replaced a \fB\-T\fP option which was briefly supported by the ncurses \fBinfocmp\fP utility in 1995. .PP -The \fB\-a\fP and \fB\-s\fP options were added to +The \fB\-a\fP and \fB\-s\fP options were added to \fB@TOE@\fR several years later (2006 and 2011, respectively). .SH SEE ALSO -\fB@TIC@\fR(1M), -\fB@INFOCMP@\fR(1M), \fB@CAPTOINFO@\fR(1M), +\fB@INFOCMP@\fR(1M), \fB@INFOTOCAP@\fR(1M), +\fB@TIC@\fR(1M), \fBcurses\fR(3X), \fBterminfo\fR(\*n). .PP @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright 2018,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tput.1,v 1.63 2020/02/02 23:34:34 tom Exp $ +.\" $Id: tput.1,v 1.72 2021/10/02 21:41:00 tom Exp $ .TH @TPUT@ 1 "" .ds d @TERMINFO@ .ds n 1 @@ -276,7 +276,7 @@ named \fBinit\fP has a more well-established use. .PP Besides the special commands (e.g., \fBclear\fP), @TPUT@ treats certain terminfo capabilities specially: -\fBlines\fP and \fBcolumns\fP. +\fBlines\fP and \fBcols\fP. @TPUT@ calls \fBsetupterm\fP(3X) to obtain the terminal size: .bP first, it gets the size from the terminal database @@ -423,7 +423,7 @@ exit code error message \fB0\fR T{ (\fIcapname\fR is a numeric variable that is not specified in the \fBterminfo\fR(5) database for this terminal type, e.g. -\fB@TPUT@ \-T450 lines\fR and \fB@TPUT@ \-T2621 xmc\fR) +\fB@TPUT@ \-T450 lines\fR and \fB@TPUT@ \-Thp2621 xmc\fR) T} \fB1\fR no error message is printed, see the \fBEXIT CODES\fR section. \fB2\fR usage error @@ -436,10 +436,21 @@ T} The \fBtput\fP command was begun by Bill Joy in 1980. The initial version only cleared the screen. .PP -AT&T System V provided a different \fBtput\fP command, -whose \fBinit\fP and \fBreset\fP subcommands +AT&T System V provided a different \fBtput\fP command: +.bP +SVr2 provided a rudimentary \fBtput\fP +which checked the parameter against each +predefined capability and returned the corresponding value. +This version of \fBtput\fP did not use \fBtparm\fP(3X) for +the capabilities which are parameterized. +.bP +SVr3 replaced that, a year later, by a more extensive program +whose \fBinit\fP and \fBreset\fP subcommands (more than half the program) were incorporated from the \fBreset\fP feature of BSD \fBtset\fP written by Eric Allman. +.bP +SVr4 added color initialization using the \fIorig_colors\fP and +\fIorig_pairs\fP capabilities in the \fBinit\fP subcommand. .PP Keith Bostic replaced the BSD \fBtput\fP command in 1989 with a new implementation @@ -505,6 +516,15 @@ requiring \fB@TPUT@\fP to know which type to use. This implementation uses a table to determine the parameter types for the standard \fIcapname\fR operands, and an internal library function to analyze nonstandard \fIcapname\fR operands. +.IP +Besides providing more reliable operation than AT&T's utility, +a portability problem is introduced by this analysis: +An OpenBSD developer adapted the internal library function from ncurses +to port NetBSD's termcap-based \fBtput\fP to terminfo. +That had been modified to interpret multiple commands on a line. +Portable applications should not rely upon this feature; +ncurses provides it to support applications written +specifically for OpenBSD. .PP This implementation (unlike others) can accept both \fItermcap\fP and \fIterminfo\fP names for the \fIcapname\fP feature, @@ -530,7 +550,7 @@ features used in the \fBcup\fR example, were not supported in BSD curses before 4.3reno (1989) or in AT&T/USL curses before SVr4 (1988). .PP -IEEE Std 1003.1/The Open Group Base Specifications Issue 7 (POSIX.1-2008) +IEEE Std 1003.1/The Open Group Base Specifications Issue 7 (POSIX.1-2008) documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP. There are a few interesting observations to make regarding that: .bP @@ -547,6 +567,9 @@ A few platforms such as FreeBSD recognize termcap names rather than terminfo capability names in their respective \fBtput\fP commands. Since 2010, NetBSD's \fBtput\fP uses terminfo names. Before that, it (like FreeBSD) recognized termcap names. +.IP +Beginning in 2021, FreeBSD uses the ncurses \fBtput\fP, +configured for both terminfo (tested first) and termcap (as a fallback). .PP Because (apparently) \fIall\fP of the certified Unix systems support the full set of capability names, the reasoning for documenting @@ -590,8 +613,8 @@ to either ncurses or X/Open. \fBstty\fR(1), \fB@TABS@\fR(\*n), \fB@TSET@\fR(\*n), -\fBterminfo\fR(5), -\fBcurs_termcap\fR(3X). +\fBcurs_termcap\fR(3X), +\fBterminfo\fR(5). .PP This describes \fBncurses\fR version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tset.1,v 1.55 2020/02/02 23:34:34 tom Exp $ +.\" $Id: tset.1,v 1.58 2021/09/18 21:21:55 tom Exp $ .TH @TSET@ 1 "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -143,26 +143,26 @@ you may have to type to work, as carriage-return may no longer work in the abnormal state. .bP Also, the terminal will often not echo the command. -.SH OPTIONS +.SH OPTIONS .PP The options are as follows: .TP 5 .B \-c Set control characters and modes. .TP 5 -.B \-e +.BI \-e\ ch Set the erase character to \fIch\fR. .TP .B \-I Do not send the terminal or tab initialization strings to the terminal. .TP -.B \-i +.BI \-i\ ch Set the interrupt character to \fIch\fR. .TP -.B \-k +.BI \-k\ ch Set the line kill character to \fIch\fR. .TP -.B \-m +.BI \-m\ mapping Specify a mapping from a port type to a terminal. See the section .B TERMINAL TYPE MAPPING @@ -284,33 +284,24 @@ and that \fBcsh\fR users insert a backslash character (\*(``\e\*('') before any exclamation marks (\*(``!\*(''). .SH HISTORY .PP -A \fBreset\fP command appeared in 2BSD (April 1979), written by Kurt Shoens. +A \fBreset\fP command appeared in 1BSD (March 1978), written by Kurt Shoens. This program set the \fIerase\fP and \fIkill\fP characters to \fB^H\fP (backspace) and \fB@\fP respectively. Mark Horton improved that in 3BSD (October 1979), adding \fIintr\fP, \fIquit\fP, \fIstart\fP/\fIstop\fP and \fIeof\fP characters as well as changing the program to avoid modifying any user settings. +That version of \fBreset\fP did not use the termcap database. .PP -Later in 4.1BSD (December 1980), -Mark Horton added a call to the \fBtset\fP program -using the \fB\-I\fP and \fB\-Q\fP options, i.e., -using that to improve the terminal modes. -With those options, -that version of \fBreset\fP did not use the termcap database. -.PP -A separate \fBtset\fP command was provided in 2BSD by Eric Allman. -While the oldest published source (from 1979) -provides both \fBtset\fP and \fBreset\fP, -Allman's comments in the 2BSD source code indicate +A separate \fBtset\fP command was provided in 1BSD by Eric Allman, +using the termcap database. +Allman's comments in the source code indicate that he began work in October 1977, continuing development over the next few years. .PP -In September 1980, Eric Allman modified \fBtset\fP, -adding the code from the existing \*(``reset\*('' -feature when \fBtset\fP was invoked as \fBreset\fP. -Rather than simply copying the existing program, -in this merged version, \fBtset\fP used the termcap database -to do additional (re)initialization of the terminal. +According to comments in the source code, +the \fBtset\fP program was modified in September 1980, +to use logic copied from the 3BSD \*(``reset\*('' +when it was invoked as \fBreset\fP. This version appeared in 4.1cBSD, late in 1982. .PP Other developers (e.g., Keith Bostic and Jim Bloom) diff --git a/man/user_caps.5 b/man/user_caps.5 index 31f4f72..4cc1e16 100644 --- a/man/user_caps.5 +++ b/man/user_caps.5 @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: user_caps.5,v 1.12 2020/02/02 23:34:34 tom Exp $ +.\" $Id: user_caps.5,v 1.17 2021/06/17 21:30:22 tom Exp $ .TH user_caps 5 .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -126,7 +126,7 @@ box characters primary set The memory lock/unlock capabilities were included because they were used in the X11R6 terminal description for \fBxterm\fP. The \fIbox1\fP capability is used in @TIC@ to help with terminal descriptions -written for AIX. +written for AIX. .PP During the 1990s, some users were reluctant to use terminfo in spite of its performance advantages over termcap: @@ -409,16 +409,29 @@ given the list of values, ask \fBkey_defined\fP(3X) for the \fIkey-code\fP which would be returned for those keys by \fBwgetch\fP(3X). .PP +.\" .SH PORTABILITY .PP The \*(``\-x\*('' extension feature of \fB@TIC@\fP and \fB@INFOCMP@\fP has been adopted in NetBSD curses. That implementation stores user-defined capabilities, but makes no use of these capabilities itself. +.\" .SH SEE ALSO .PP -\fB@TIC@\fR(1M), -\fB@INFOCMP@\fR(1M). +\fB@INFOCMP@\fR(1M), +\fB@TIC@\fR(1M). +.PP +The terminal database section +.I "NCURSES USER-DEFINABLE CAPABILITIES" +summarizes commonly-used user-defined capabilities +which are used in the terminal descriptions. +Some of those features are mentioned in \fBscreen\fR(1) or \fBtmux\fR(1). +.PP +.I "XTerm Control Sequences" +provides further information on the \fBxterm\fP features +which are used in these extended capabilities. +.\" .SH AUTHORS .PP Thomas E. Dickey diff --git a/man/wresize.3x b/man/wresize.3x index 8afadda..54c1fc6 100644 --- a/man/wresize.3x +++ b/man/wresize.3x @@ -29,14 +29,14 @@ .\" .\" Author: Thomas E. Dickey 1996 .\" -.\" $Id: wresize.3x,v 1.16 2020/02/02 23:34:34 tom Exp $ +.\" $Id: wresize.3x,v 1.17 2020/10/17 23:56:38 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 +\fBint wresize(WINDOW *\fP\fIwin\fP\fB, int \fP\fIlines\fP\fB, int \fP\fIcolumns\fP\fB);\fR .SH DESCRIPTION This is an extension to the curses library. It reallocates storage for an \fBncurses\fR |