[PATCH 23/23] man/curs_getstr.3x: Revise.

[G. Branden Robinson]

Content:
* Discuss elementary function `wgetstr()` first in "DESCRIPTION"
  section.  Then describe how `wgetnstr()` differs.  Refer the reader to
  ncurses(3X) for the variants.
* Discuss function behavior more explicitly in terms of formal arguments
  and return values.
* Stop saying "newline" when we mean "line feed".  A "newline" is,
  depending on context, an abstraction or U+0085, the "Next Line" C1
  control.  The discussion here is at the level of character codes.
* Fully discuss `wgetstr()` behavior before dealing with `wgetnstr()`.
* Cross reference erasechar(3X), killchar(3X), echo(3X), wechochar(3X),
  and keypad(3X) man pages where appropriate.
* Drop examples of terminal erase and kill characters.
* Relocate material about what X/Open Curses specifies from "RETURN
  VALUE" section to "PORTABILITY" section.
* Move discussion of internal behavior from "PORTABILITY" section to
  "NOTES" section.
* Add "EXTENSIONS" section documenting "KEY_RESIZE" return value.
* Advise "NCURSES_VERSION" usage in "PORTABILITY" section when
  exercising ncurses extensions.
* Add "HISTORY" section.
* Move discussion of SVr3 and early SVr4 behavior from "PORTABILITY"
  section to "HISTORY" section.
* Quote X/Open Curses more.
* Drop cross reference to curs_variables(3X) in "SEE ALSO" section;
  nothing in particular that it covers seems to be mentioned here, apart
  from "OK" and "ERR" with which the ncurses(3X) reader should already
  be familiar.

Style:
* Favor active voice over passive.
* Protect man page names from hyphenation.
* Favor term "null character" over "NUL" (character code 0).  (Recall
  that C strings are terminated by null characters, and C wide strings
  by null wide characters.  How such null characters are encoded is a
  slightly different matter.)
* Parallelize wording of "RETURN VALUE", "NOTES", and "PORTABILITY"
  sections with that of other recently edited ncurses man pages.
* Favor saying "ncurses" over "this implementation".
* Favor discussion of function parameters using their names over their
  data types.
* Set "curses", "PDCurses", and "xcurses" in italics, not roman.
* Set C identifiers for Unix signal names in bold, not roman.

Markup:
* Define `^` string for later use, as other ncurses man pages do.
* Favor man(7) font style macros over *roff font selection escape
  sequences, except for man page cross references (because
  man/make_sed.sh recognizes only certain patterns when rewriting such
  cross references) and terms in the "NAME" section (because the
  generated edit_man.sh script expects font selection escape sequences
  when scraping terms thence to gather names for man page aliases).
* Annotate sources of quotations.
* Use `^` string to portably set U+005E.

* man/man_db.renames.in: Add beep.3x and killchar.3x.

* man/manhtml.externs: Add sysconf(3).
---
 man/curs_getstr.3x    | 544 ++++++++++++++++++++++++++++--------------
 man/man_db.renames.in |   2 +
 man/manhtml.externs   |   1 +
 3 files changed, 372 insertions(+), 175 deletions(-)

diff --git a/man/curs_getstr.3x b/man/curs_getstr.3x
index 7248b6665..819f1e288 100644
--- a/man/curs_getstr.3x
+++ b/man/curs_getstr.3x
@@ -32,12 +32,14 @@
 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq
+.ds ^  \(ha
 .\}
 .el \{\
 .ie t .ds `` ``
 .el   .ds `` ""
 .ie t .ds '' ''
 .el   .ds '' ""
+.ds       ^  ^
 .\}
 .
 .de bP
@@ -69,86 +71,108 @@ .SH SYNOPSIS
 \fBint mvwgetnstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, char * 
\fIstr\fP, int \fIn\fP);
 .fi
 .SH DESCRIPTION
+.B \%wgetstr
+populates a user-supplied string buffer
+.I str
+by repeatedly calling \fBwgetch\fP(3X)
+with the
+.I win
+argument
+until a line feed or carriage return character is input.
+.\" Of the two, because wgetnstr() calls nl(), only a line feed (\n)
+.\" will ever be returned by wgetch().
 The function
-\fBwgetnstr\fP
-is equivalent to a series of calls to
-\fBwgetch\fP(3X),
-until a newline or carriage return terminates the series:
 .bP
-The terminating character is not included in the returned string.
+does not copy the terminating character to
+.IR str ";"
 .bP
-In all instances, the end of the string is terminated
-by a NUL.
+always terminates
+.I str
+with a null character;
 .bP
-The function stores the result in the area pointed to
-by the \fIstr\fP parameter.
+interprets the screen's erase and kill characters
+(see \fB\%erasechar\fP(3X) and \fB\%killchar\fP(3X));
 .bP
-The function reads at most \fIn\fP characters,
-thus preventing a possible overflow of the input buffer.
-.IP
-Any attempt to enter more characters
-(other than the terminating newline or carriage return)
-causes a beep.
-.IP
-Function keys also cause a beep and are ignored.
+recognizes function keys only if the screen's keypad option is enabled
+(see \fB\%keypad\fP(3X));
+.bP
+treats the function keys
+.B \%KEY_LEFT
+and
+.B \%KEY_BACKSPACE
+the same as the erase character;
+and
+.bP
+discards function key inputs other than those treated as the erase
+character,
+calling \fBbeep\fP(3X).
+.PP
+The erase character replaces the character at the end of the buffer with
+a null character,
+while the kill character does the same for the entire buffer.
 .PP
-The user's \fIerase\fP and \fIkill\fP characters are interpreted:
+If the screen's echo option is enabled
+(see \fBecho\fP(3X)),
+.B \%wgetstr
+updates
+.I win
+with \fB\%wechochar\fP(3X).
+Further,
 .bP
-The \fIerase\fP character (e.g., \fB^H\fP) erases the character
-at the end of the buffer, moving the cursor to the left.
-.IP
-If \fIkeypad\fP mode is on for the window,
-\fBKEY_LEFT\fP and \fBKEY_BACKSPACE\fP
-are both considered equivalent to the user's \fIerase\fP character.
+the erase character
+and its function key synonyms
+move the cursor to the left,
+and
 .bP
-The \fIkill\fP character (e.g., \fB^U\fP) erases the entire buffer,
-leaving the cursor at the beginning of the buffer.
+the kill character returns the cursor to where it was located when
+.B \%wgetstr
+was called.
 .PP
-Characters input are echoed only if \fBecho\fP is currently on.
-In that case,
-backspace is echoed as deletion of the previous character
-(typically a left motion).
+.B \%wgetnstr
+is similar,
+but reads at most
+.I n
+characters,
+aiding the application to avoid overrunning the buffer to which
+.I str
+points.
+An attempt to input more than
+.I n
+characters
+(other than the terminating line feed or carriage return)
+is ignored with a beep.
 .PP
-The
-\fBgetnstr\fP,
-\fBmvgetnstr\fP,
-\fBmvwgetnstr\fP, and
-\fBwgetnstr\fP
-functions are identical
-to the
-\fBgetstr\fP,
-\fBmvgetstr\fP,
-\fBmvwgetstr\fP, and
-\fBwgetstr\fP
-functions, respectively,
-except that the
-\fB*n*\fP
-versions read at most
-\fIn\fP
-characters, letting the application prevent overflow of the
-input buffer.
+\fB\%ncurses\fP(3X) describes the variants of these functions.
 .SH RETURN VALUE
-All of these functions return the integer \fBOK\fP upon successful completion.
-(SVr4 specifies only \*(``an integer value other than \fBERR\fP\*('')
-If unsuccessful, they return \fBERR\fP.
-.PP
-X/Open defines no error conditions.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
 .PP
-In this implementation,
-these functions return
+In
+.IR \%ncurses ","
+they return
 .B ERR
+if
 .bP
-if the window pointer is null,
+.I win
+is
+.BR NULL ","
+or
 .bP
-if its timeout expires without having any data, or
-.bP
-if the associated call to
-\fBwgetch\fP
-failed.
+if an internal
+.B \%wgetch
+call fails.
 .PP
-This implementation provides an extension as well.
-If a \fBSIGWINCH\fP interrupts the function, it will return \fBKEY_RESIZE\fP
-rather than \fBOK\fP or \fBERR\fP.
+Further,
+in
+.IR \%ncurses ","
+these functions return
+.B \%KEY_RESIZE
+if a
+.B \%SIGWINCH
+event interrupts the function.
 .PP
 Functions prefixed with \*(``mv\*('' first perform cursor movement and
 fail if the position
@@ -156,138 +180,307 @@ .SH RETURN VALUE
 .IR x )
 is outside the window boundaries.
 .SH NOTES
-Any of these functions other than
-\fBwgetnstr\fP
-may be macros.
+All of these functions except
+.B \%wgetnstr
+may be implemented as macros.
+.PP
+Use of
+.BR \%getstr ","
+.BR \%mvgetstr ","
+.BR \%mvwgetstr ","
+or
+.B \%wgetstr
+to read input that
+overruns the buffer pointed to by
+.I str
+causes undefined results.
+Use their
+.BR n -infixed
+counterpart functions instead.
 .PP
-Using
-\fBgetstr\fP,
-\fBmvgetstr\fP,
-\fBmvwgetstr\fP, or
-\fBwgetstr\fP
-to read a line that
-overflows the array pointed to by
-\fBstr\fP
-causes undefined
-results.
-The use of
-\fBgetnstr\fP,
-\fBmvgetnstr\fP,
-\fBmvwgetnstr\fP, or
-\fBwgetnstr\fP,
-respectively, is recommended.
+While
+.B \%wgetnstr
+is conceptually a series of calls to
+.BR \%wgetch ","
+it also temporarily changes properties of the
+.I curses
+screen to permit simple editing of the input buffer.
+It saves the screen's state and then calls \fBnl\fP(3X) and,
+if the screen was in normal (\*(``cooked\*('') mode,
+\fB\%cbreak\fP(3X).
+Before returning,
+it restores the saved screen state.
+Other implementations differ in detail,
+affecting which control characters they can accept in the buffer;
+see section \*(``PORTABILITY\*('' below.
+.SH EXTENSIONS
+The return value
+.B \%KEY_RESIZE
+is an
+.I \%ncurses
+extension.
 .SH PORTABILITY
-X/Open Curses,
-Issue 4 describes these functions.
-It specifies no error conditions for them.
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
 .PP
-SVr3 and early SVr4 curses implementations did not reject function keys;
-the SVr4.0 documentation claimed that \*(``special keys\*(''
+X/Open Curses Issue 4 describes these functions.
+It specifies no error conditions for them,
+but indicates that
+.I \%wgetnstr
+and its variants read
+\*(``the entire multi-byte sequence associated with a character\*(''
+and \*(``fail\*('' if
+.I n
+and
+.I str
+together do not describe a buffer
+\*(``large enough to contain any complete characters\*(''.
+In
+.IR \%ncurses ","
+however,
+.I \%wgetch
+reads only single-byte characters,
+so this scenario does not arise.
+.\" You can pass ncurses wgetnstr n=0 and it will beep at you with each
+.\" key stroke.
+.PP
+SVr4
+.I curses
+describes a successful return value only as
+\*(``an integer value other than
+.BR ERR \*(''.
+.PP
+SVr3 and early SVr4
+.I curses
+implementations did not reject function keys;
+the SVr4 documentation asserted that,
+like the screen's erase and kill characters,
+they were
+.PP
+.RS
+interpreted,
+as well as any special keys
 (such as function keys,
 \*(``home\*('' key,
 \*(``clear\*('' key,
-\fIetc\fP.) are \*(``interpreted\*('',
-without giving details.
-It lied.
-In fact, the \*(``character\*('' value appended to the
-string by those implementations was predictable but not useful
-(being, in fact, the low-order eight bits of the key's KEY_ value).
+.IR etc. )
+.\" SVID 4, Volume 3, p. 495
+.RE
 .PP
-The functions \fBgetnstr\fP, \fBmvgetnstr\fP, and \fBmvwgetnstr\fP were
-present but not documented in SVr4.
+without further detail.
+It lied.
+In fact,
+the \*(``character\*('' value
+appended to the string
+by those implementations
+was predictable but not useful \(em
+being,
+in fact,
+the low-order eight bits of the key code's
+.B KEY_
+constant value.
+(The same language,
+unchanged except for styling,
+survived into X/Open Curses Issue 4, \" p. 94 (PDF 114)
+but disappeared from Issue 7.) \" p. 105 (PDF 119)
 .PP
-X/Open Curses, Issue 5 (2007) stated that these functions
-\*(``read at most \fIn\fP bytes\*(''
-but did not state whether the terminating NUL counted toward that limit.
-X/Open Curses, Issue 7 (2009) changed that to say they
-\*(``read at most \fIn\fP\-1 bytes\*(''
-to allow for the terminating NUL.
-As of 2018, some implementations count it, some do not:
-.bP
-\fI\%ncurses\fP 6.1 and PDCurses do not count the NUL in the given limit, while
+X/Open Curses Issue 5 (2007) stated that these functions
+\*(``read at most
+.I n
+bytes\*(''
+but did not state whether the terminating null character
+counted toward that limit.
+X/Open Curses Issue 7 (2009) changed that to say they
+\*(``read at most
+.IR n \-1
+bytes\*(''
+to allow for the terminating null character.
+As of 2018,
+some implementations count it,
+some do not.
 .bP
-Solaris SVr4 and NetBSD curses count the NUL as part of the limit.
+.I \%ncurses
+6.1 and
+.I PDCurses
+do not count the null character toward the limit,
+while Solaris and NetBSD
+.I curses
+do.
 .bP
-Solaris xcurses provides both:
-its wide-character \fBwget_nstr\fP reserves a NUL,
-but its \fBwgetnstr\fP does not count the NUL consistently.
+Solaris
+.I xcurses
+offers both behaviors:
+its wide-character
+.I \%wgetn_wstr
+reserves room for a wide null character,
+but its non-wide
+.I \%wgetnstr
+does not consistently count a null character toward the limit.
 .PP
-In SVr4 curses,
-a negative value of \fIn\fP tells \fBwgetnstr\fP to assume that the
-caller's buffer is large enough to hold the result,
-i.e., to act like \fBwgetstr\fP.
-X/Open Curses does not mention this
-(or anything related to negative or zero values of \fIn\fP),
-however most implementations
-use the feature, with different limits:
+In SVr4
+.IR curses ","
+a negative
+.I n
+tells
+.I \%wgetnstr
+to assume that the caller's buffer
+is large enough to hold the result;
+that is,
+the function then acts like
+.IR \%wgetstr "."
+X/Open Curses does not mention this behavior
+(or anything related to nonpositive
+.I n
+values),
+however most
+.I curses
+libraries implement it.
+Most implementations nevertheless enforce an upper limit
+on the count of bytes they write to the destination buffer
+.IR str "."
 .bP
-Solaris SVr4 curses and PDCurses limit the result to 255 bytes.
-Other Unix systems than Solaris are likely to use the same limit.
+BSD
+.I curses
+lacked
+.IR \%wgetnstr ","
+and its
+.I \%wgetstr
+wrote to
+.I str
+unboundedly,
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
+.\"   libcurses/getstr.c
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/src/lib/\
+.\"   libcurses/getstr.c
+as did that in SVr2.
+.\" https://github.com/ryanwoodsmall/oldsysv/blob/master/sysvr2-vax/\
+.\"   src/lib/libcurses/screen/getstr.c
 .bP
-Solaris xcurses limits the result to \fBLINE_MAX\fP bytes.
-.bP
-NetBSD 7 assumes no particular limit for the result from \fBwgetstr\fP.
-However, it limits the \fBwgetnstr\fP parameter \fIn\fP to ensure
-that it is greater than zero.
-.IP
-A comment in NetBSD's source code states that this is specified in SUSv2.
+.IR PDCurses ","
+and
+SVr3.1,
+SVr4,
+and
+Solaris
+.I curses
+limit both functions to writing 256 bytes.
+Other System\ V-based platforms likely use the same limit.
+.\" https://github.com/ryanwoodsmall/oldsysv/blob/master/\
+.\"   sysvr3/31/usr/src/lib/libcurses/screen/wgetstr.c#L10
+.\"   sysvr4/svr4/lib/xlibcurses/screen/wgetstr.c#L12
 .bP
-\fI\%ncurses\fP (before 6.2) assumes no particular limit for the result
-from \fBwgetstr\fP, and treats the \fIn\fP parameter of \fBwgetnstr\fP
-like SVr4 curses.
+Solaris
+.I xcurses
+limits the write to
+.B LINE_MAX
+bytes.
 .bP
-\fI\%ncurses\fP 6.2 uses \fBLINE_MAX\fP,
-or a larger (system-dependent) value
-which the \fBsysconf\fP function may provide.
-If neither \fBLINE_MAX\fP or \fBsysconf\fP is available,
-\fI\%ncurses\fP uses the POSIX value for \fBLINE_MAX\fP (a 2048 byte limit).
-In either case, it reserves a byte for the terminating NUL.
-.PP
-Although \fBgetnstr\fP is equivalent to a series of calls to \fBgetch\fP,
-it also makes changes to the curses modes to allow simple editing of
-the input buffer:
-.bP
-\fBgetnstr\fP saves the current value of the \fBnl\fP, \fBecho\fP,
-\fBraw\fP and \fBcbreak\fP modes, and sets
-\fBnl\fP,
-\fBnoecho\fP,
-\fBnoraw\fP, and
-\fBcbreak\fP.
-.IP
-\fBgetnstr\fP handles the echoing of characters,
-rather than relying on the caller to set an appropriate mode.
+NetBSD 7
+.I curses
+imposes no particular limit on the length of the write,
+but does validate
+.I n
+to ensure that it is greater than zero.
+A comment in NetBSD's source code asserts that SUSv2 specifies this.
 .bP
-It also obtains the \fIerase\fP and \fIkill\fP characters
-from \fBerasechar\fP and \fBkillchar\fP, respectively.
+.I \%ncurses
+prior to 6.2 (2020)
+imposes no limit on the length of the write,
+and treats
+.IR wgetnstr 's
+.I n
+parameter as SVr4
+.I curses
+does.
 .bP
-On return, \fBgetnstr\fP restores the modes to their previous values.
+.I \%ncurses
+6.2 uses
+.B LINE_MAX
+or a larger (system-dependent) value
+provided by \fI\%sysconf\fP(3).
+If neither
+.B LINE_MAX
+nor
+.I \%sysconf
+is available,
+.I \%ncurses
+uses the POSIX minimum value for
+.B LINE_MAX
+(2048). \" _POSIX2_LINE_MAX
+In either case,
+it reserves a byte for the terminating null character.
 .PP
-Other implementations differ in their treatment of special characters:
+Implementations vary in their handling of input control 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.
+While they may enable the screen's echo option,
+some do not take it out of raw mode,
+and may take cbreak mode into account
+when deciding whether to handle echoing within
+.I \%wgetnstr
+or to rely on it as a side effect of calling
+.IR \%wgetch "."
 .bP
-The original \fI\%ncurses\fP
-(as \fIpcurses\fP in 1986)
-set \fBnoraw\fP and \fBcbreak\fP when accepting input for \fBgetnstr\fP.
-That may have been done to make function- and cursor-keys work;
-it is not necessary with \fI\%ncurses\fP.
+Originally,
+.IR \%ncurses ","
+like its progenitor
+.IR \%pcurses ","
+had its
+.I \%wgetnstr
+call
+.I \%noraw
+and
+.I \%cbreak
+before accepting input.
+That may have been done to make function keys work;
+it is not necessary with modern
+.IR \%ncurses "."
 .IP
 Since 1995,
-\fI\%ncurses\fP has provided signal handlers for INTR and QUIT
-(e.g., \fB^C\fP or \fB^\e\fP).
-With the \fBnoraw\fP and \fBcbreak\fP settings,
-those may catch a signal and stop the program,
-where other implementations allow one to enter those characters in the buffer.
+.I \%ncurses
+has provided handlers for
+.B SIGINTR
+and
+.B SIGQUIT
+events,
+which are typically generated at the keyboard with
+.B \*^C
+and
+.B \*^\e
+respectively.
+In cbreak mode,
+those handlers catch a signal and stop the program,
+whereas other implementations write those characters into the buffer.
 .bP
-Starting in 2021
-\%(\fIncurses\fP 6.3),
-\fBgetnstr\fP sets \fBraw\fP,
-rather than \fBnoraw\fP and \fBcbreak\fP for better compatibility with
-SVr4-curses, e.g., allowing one to enter a \fB^C\fP into the buffer.
+Starting with
+.I \%ncurses
+6.3 (2021),
+.I \%wgetnstr
+preserves raw mode if the screen was already in that state,
+allowing one to enter the characters the terminal interprets
+as interrupt and quit events
+into the buffer,
+for better compatibility with SVr4
+.IR curses "."
+.SH HISTORY
+4BSD (1980)
+.I curses
+introduced
+.I \%wgetstr
+along with its variants.
+.PP
+SVr3.1 (1987)
+added
+.IR \%wgetnstr ","
+but none of its variants.
+.PP
+X/Open Curses Issue 4 (1995) specified
+.IR \%getnstr ","
+.IR \%mvwgetnstr ","
+and
+.IR \%mvgetnstr "."
 .SH SEE ALSO
 \fB\%curs_get_wstr\fP(3X) describes comparable functions of the
 .I \%ncurses
@@ -295,6 +488,7 @@ .SH SEE ALSO
 .RI \%( ncursesw ).
 .PP
 \fB\%curses\fP(3X),
+\fB\%curs_addch\fP(3X),
 \fB\%curs_getch\fP(3X),
-\fB\%curs_termattrs\fP(3X),
-\fB\%curs_variables\fP(3X)
+\fB\%curs_inopts\fP(3X), \" echo(), keypad()
+\fB\%curs_termattrs\fP(3X), \" erasechar(), killchar()
diff --git a/man/man_db.renames.in b/man/man_db.renames.in
index 637688034..0e8de7fe4 100644
--- a/man/man_db.renames.in
+++ b/man/man_db.renames.in
@@ -178,6 +178,7 @@ attr_get.3x                 attr_get.3ncurses
 attr_on.3x                     attr_on.3ncurses
 attron.3x                      attron.3ncurses
 baudrate.3x                    baudrate.3ncurses
+beep.3x                                beep.3ncurses
 bkgd.3x                                bkgd.3ncurses
 bkgrnd.3x                      bkgrnd.3ncurses
 cbreak.3x                      cbreak.3ncurses
@@ -217,6 +218,7 @@ initscr.3x                  initscr.3ncurses
 is_scrollok.3x                 is_scrollok.3ncurses
 keyname.3x                     keyname.3ncurses
 keypad.3x                      keypad.3ncurses
+killchar.3x                    killchar.3ncurses
 leaveok.3x                     leaveok.3ncurses
 longname.3x                    longname.3ncurses
 meta.3x                                meta.3ncurses
diff --git a/man/manhtml.externs b/man/manhtml.externs
index 1cf3af64c..e9656656a 100644
--- a/man/manhtml.externs
+++ b/man/manhtml.externs
@@ -72,6 +72,7 @@ sscanf(3)
 stdio(3)
 stty(1)
 swprintf(3)
+sysconf(3)
 system(3)
 termios(3)
 tmux(1)
-- 
2.30.2

signature.asc
Description: PGP signature