* 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
