[PATCH 046/177] man/curs_get{,_w}str.3x: Revise/parallelize discussion of bounded writes.

[G. Branden Robinson]

* Generalize discussion of negative argument to *n* functions in
  get_wstr(); only its sign is significant; "-1" is not special.
* Reorganize getstr() discussion to note X/Open Curses's
  non-specification of negative `n` handling, and to lead with
  discussion of ncurses's current behavior instead of a strictly
  chronological account of behavior.
* Add "EXTENSIONS" section documenting this behavior as such.
* Add advice on extension usage to "PORTABILITY" section.
* Broaden characterization of System V behavior based on inspection of
  pre-SVr3.1 sources.  Annotate.
* Drop confusing and contradictory comment claiming that "ncurses prior
  to 6.2 treats wgetnstr's n parameter as SVr4 curses does"; we just got
  done saying that SVr4 limited the write to 256 bytes, whereas ncurses
  6.1 and earlier would write unboundedly.  (Bear in mind that if your
  destination buffer is smaller than 256 bytes, your write may be
  "bounded" but could still result in undefined behavior.)
---
 man/curs_get_wstr.3x | 39 ++++++++++++++++++----
 man/curs_getstr.3x   | 78 ++++++++++++++++++++++++++------------------
 2 files changed, 78 insertions(+), 39 deletions(-)

diff --git a/man/curs_get_wstr.3x b/man/curs_get_wstr.3x
index e167451c2..95e021123 100644
--- a/man/curs_get_wstr.3x
+++ b/man/curs_get_wstr.3x
@@ -148,6 +148,15 @@ .SH DESCRIPTION
 wide characters
 (other than the terminating line feed or carriage return)
 is ignored with a beep.
+If
+.I n
+is negative,
+.B \%wgetn_wstr
+reads up to
+.I LINE_MAX
+wide characters
+(see
+.IR sysconf (3)).
 .PP
 \fB\%ncurses\fP(3X) describes the variants of these functions.
 .SH RETURN VALUE
@@ -227,7 +236,24 @@ .SH NOTES
 if a
 .I \%SIGWINCH
 event interrupts the function.
+.SH EXTENSIONS
+.BR \%getn_wstr ","
+.BR \%wgetn_wstr ","
+.BR \%mvgetn_wstr ","
+and
+.BR \%mvwgetn_wstr "'s"
+handing of negative
+.I n
+values is an
+.I \%ncurses
+extension.
 .SH PORTABILITY
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
+.PP
 X/Open Curses Issue\ 4 describes these functions.
 It specifies no error conditions for them.
 .PP
@@ -280,11 +306,10 @@ .SH PORTABILITY
 .IR \%wgetnstr ","
 .I \%ncurses
 6.2 uses a limit based on
-.I LINE_MAX
-(see
-.IR sysconf (3)).
+.IR LINE_MAX "."
 .bP
-Some other implementations (such as Solaris
+Some other implementations
+(such as Solaris
 .IR xcurses )
 do the same,
 while others
@@ -296,9 +321,9 @@ .SH PORTABILITY
 .I curses
 imitates
 .I \%ncurses
-6.1 in this regard,
-treating
-.B \-1
+6.1 and earlier,
+treating a negative
+.I n
 as an unbounded count of wide characters.
 .PP
 Implementations vary in their handling of input control characters.
diff --git a/man/curs_getstr.3x b/man/curs_getstr.3x
index 75d034bcf..34a170065 100644
--- a/man/curs_getstr.3x
+++ b/man/curs_getstr.3x
@@ -142,6 +142,15 @@ .SH DESCRIPTION
 characters
 (other than the terminating line feed or carriage return)
 is ignored with a beep.
+If
+.I n
+is negative,
+.B \%wgetn_wstr
+reads up to
+.I LINE_MAX
+characters
+(see
+.IR sysconf (3)).
 .PP
 \fB\%ncurses\fP(3X) describes the variants of these functions.
 .SH RETURN VALUE
@@ -213,6 +222,17 @@ .SH NOTES
 affecting which control characters they can accept in the buffer;
 see section \*(``PORTABILITY\*('' below.
 .SH EXTENSIONS
+.BR \%getnstr ","
+.BR \%wgetnstr ","
+.BR \%mvgetnstr ","
+and
+.BR \%mvwgetnstr "'s"
+handing of negative
+.I n
+values is an
+.I \%ncurses
+extension.
+.PP
 The return value
 .B \%KEY_RESIZE
 is an
@@ -323,6 +343,27 @@ .SH PORTABILITY
 .I \%wgetnstr
 does not consistently count a null character toward the limit.
 .PP
+X/Open Curses does not specify what happens if the length
+.I n
+is negative.
+.bP
+.I \%ncurses
+6.2 uses
+.I LINE_MAX
+or a larger (system-dependent) value
+provided by \fI\%sysconf\fP(3).
+If neither
+.I LINE_MAX
+nor
+.I \%sysconf
+is available,
+.I \%ncurses
+uses the POSIX minimum value for
+.I LINE_MAX
+(2048). \" _POSIX2_LINE_MAX
+In either case,
+it reserves a byte for the terminating null character.
+.bP
 In SVr4
 .IR curses ","
 a negative
@@ -364,16 +405,16 @@ .SH PORTABILITY
 .bP
 .IR PDCurses ","
 and
-SVr3.1,
-SVr4,
+SVr3 and later,
+.\" https://github.com/ryanwoodsmall/oldsysv/blob/master/\
+.\"   sysvr3/301/usr/src/lib/libcurses/screen/getstr.c#L21
+.\"   sysvr3/31/usr/src/lib/libcurses/screen/wgetstr.c#L10
+.\"   sysvr4/svr4/lib/xlibcurses/screen/wgetstr.c#L12
 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
 Solaris
 .I xcurses
@@ -390,33 +431,6 @@ .SH PORTABILITY
 .I n
 to ensure that it is greater than zero.
 A comment in NetBSD's source code asserts that SUSv2 specifies this.
-.bP
-.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
-.I \%ncurses
-6.2 uses
-.I LINE_MAX
-or a larger (system-dependent) value
-provided by \fI\%sysconf\fP(3).
-If neither
-.I LINE_MAX
-nor
-.I \%sysconf
-is available,
-.I \%ncurses
-uses the POSIX minimum value for
-.I LINE_MAX
-(2048). \" _POSIX2_LINE_MAX
-In either case,
-it reserves a byte for the terminating null character.
 .PP
 Implementations vary in their handling of input control characters.
 .bP
-- 
2.30.2

signature.asc
Description: PGP signature