Sorry, there's a problem with this one: it makes the "RETURN VALUE" section inaccurate, because while `winstr()` and `winwstr()` (which retrieve window contents as standard C (wide) strings) _do_ return (wide) character counts, their counterparts that retrieve curses (complex) strings `winchstr()` and `win_wchstr()` return only `OK` or `ERR`.
I have more patches in preparation that I plan to submit today or early
tomorrow that will rectify this.
Or Thomas can tell me what alternative remedy he'd prefer.
Regards,
Branden
At 2025-08-14T11:21:06-0500, G. Branden Robinson wrote:
> * Align structure, language, and use of terminology.
> * Add "EXTENSIONS" and "HISTORY" sections.
> * Add note to "PORTABILITY" section regarding ncurses extension.
>
> * 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).
>
> * Quote (single-character) trailing punctuation arguments to man(7) font
> alternation macros. The package does not require this; it avoids
> false positives reported by one of Thomas Dickey's style-checking
> scripts, per his communication.
> ---
> man/curs_inchstr.3x | 135 +++++++++++++++++++++++++++++++-------------
> 1 file changed, 95 insertions(+), 40 deletions(-)
>
> diff --git a/man/curs_inchstr.3x b/man/curs_inchstr.3x
> index f711a1c98..70caa400e 100644
> --- a/man/curs_inchstr.3x
> +++ b/man/curs_inchstr.3x
> @@ -70,34 +70,60 @@ .SH SYNOPSIS
> int \fIn\fP);
> .fi
> .SH DESCRIPTION
> -These routines return a
> -.IR NULL -terminated
> -array of \fBchtype\fP quantities,
> -starting at the current cursor position in the named window and ending at the
> -right margin of the window.
> -.PP
> -The four functions with \fIn\fP as the last argument, return
> -a leading substring at most \fIn\fP characters long
> -(exclusive of the trailing (chtype)0).
> -Transfer stops at the end of the current line, or when \fIn\fP characters
> have
> -been stored at the location referenced by \fIchstr\fP.
> -.PP
> -Constants defined in \fB<curses.h>\fP can be used with the \fB&\fP
> -(logical \*(``and\*('')
> -operator to extract the character or the attribute alone from any position
> -in the \fIchstr\fP [see \fBcurs_inch\fP(3X)].
> +.B \%winchstr
> +extracts a
> +.I curses
> +character string from a
> +.I curses
> +window
> +.IR win ","
> +starting at the cursor and stopping at the end of the line,
> +and stores it in
> +.IR chstr ","
> +terminating it with a null
> +.I curses
> +character.
> +.B \%winchnstr
> +does the same,
> +but copies at most
> +.I n
> +.I curses
> +characters from
> +.IR win "."
> +A negative
> +.I n
> +implies no limit;
> +.B \%winchnstr
> +then works like
> +.BR \%winchstr "."
> +\fB\%ncurses\fP(3X) describes the variants of these functions.
> .SH RETURN VALUE
> -All routines return the integer \fBERR\fP upon failure and an integer value
> -other than \fBERR\fP upon successful completion (the number of characters
> -retrieved, exclusive of the trailing 0).
> -.PP
> -X/Open Curses defines no error conditions.
> -This implementation returns
> +These functions return the count of characters copied from
> +.I win
> +to
> +.I chstr
> +(not counting the null terminator),
> +or
> .B ERR
> +upon failure.
> +.PP
> +In
> +.IR \%ncurses ","
> +these functions fail if
> +.bP
> +the
> +.I curses
> +screen has not been initialized,
> .bP
> -if the \fIwin\fP parameter is null or
> +(for functions taking a
> +.I \%WINDOW
> +pointer argument)
> +.I win
> +is a null pointer,
> +or
> .bP
> -if the \fIchstr\fP parameter is null.
> +.I chstr
> +is a null pointer.
> .PP
> Functions prefixed with \*(``mv\*('' first perform cursor movement and
> fail if the position
> @@ -110,21 +136,39 @@ .SH NOTES
> may be implemented as macros.
> .PP
> Reading a line that overflows the array pointed to by
> -\fIchstr\fP
> +.I chstr
> with
> -\fBinchstr\fP,
> -\fBmvinchstr\fP,
> -\fBmvwinchstr\fP
> +.BR \%inchstr ","
> +.BR \%mvinchstr ","
> +.BR \%mvwinchstr ","
> or
> -\fBwinchstr\fP
> +.B \%winchstr
> causes undefined results.
> -Therefore, the use of
> -\fBinchnstr\fP,
> -\fBmvinchnstr\fP,
> -\fBmvwinchnstr\fP, or
> -\fBwinchnstr\fP
> -is recommended.
> +Use of
> +.BR \%inchnstr ","
> +.BR \%mvinchnstr ","
> +.BR \%mvwinchnstr ","
> +or
> +.B \%winchnstr
> +is recommended instead.
> +.SH EXTENSIONS
> +.BR \%inchnstr ","
> +.BR \%winchnstr ","
> +.BR \%mvinchnstr ","
> +and
> +.BR \%mvwinchnstr "'s"
> +acceptance 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.
> It characterizes the strings stored by these functions as containing
> @@ -136,18 +180,29 @@ .SH PORTABILITY
> but does not specify whether the string stored by these functions is
> null-terminated.
> .PP
> -SVr4 does not document whether it null-terminates the string it stores
> +SVr4 does not document whether it null-terminates the
> +.I curses
> +character string it stores
> in
> .IR chstr ","
> -and does not document whether a trailing null character counts toward the
> -length limit
> +and does not document whether a trailing null
> +.I curses
> +character counts
> +toward the length limit
> .IR n "."
> .PP
> SVr4 describes a successful return value only as
> \*(``an integer value other than
> .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 503
> +.SH HISTORY
> +SVr3.1 (1987)
> +introduced these functions.
> .SH SEE ALSO
> +\fB\%curs_in_wchstr\fP(3X) describes comparable functions of the
> +.I \%ncurses
> +library in its wide-character configuration
> +.RI \%( ncursesw ).
> +.PP
> \fB\%curses\fP(3X),
> \fB\%curs_inch\fP(3X),
> -\fB\%curs_inwstr\fP(3X),
> -\fB\%curs_in_wchstr\fP(3X)
> +\fB\%curs_inwstr\fP(3X)
> --
> 2.30.2
>
signature.asc
Description: PGP signature
