ncurses 6.5 - patch 20240622

[ncurses.git] / man / curs_insstr.3x

diff --git a/man/curs_insstr.3x b/man/curs_insstr.3x
index 888d4250091fd9c6b74ab48356fefd87c61c8a90..2641f05adae4ba8121b52d0e5fb1a6b8b6630fa5 100644 (file)
--- a/man/curs_insstr.3x
+++ b/man/curs_insstr.3x
@@ -27,8 +27,8 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_insstr.3x,v 1.51 2024/04/20 21:20:07 tom Exp $
-.TH curs_insstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_insstr.3x,v 1.55 2024/06/08 21:03:03 tom Exp $
+.TH curs_insstr 3X 2024-06-08 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"

 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq
 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq


@@ -89,13 +89,15 @@ Special characters are handled as in \fBwaddch\fP(3X).
 All functions return the integer \fBERR\fP upon failure and \fBOK\fP on success.
 .PP
 X/Open Curses does not specify any error conditions.
 All functions return the integer \fBERR\fP upon failure and \fBOK\fP on success.
 .PP
 X/Open Curses does not specify any error conditions.

-This implementation returns an error
+This implementation returns
+.B ERR

 .bP
 if the \fIwin\fP parameter is null or
 .bP
 if the \fIstr\fP parameter is null or
 .bP
 .bP
 if the \fIwin\fP parameter is null or
 .bP
 if the \fIstr\fP parameter is null or
 .bP

-the \fBwinsch\fP(3X) function returns an error.
+the \fBwinsch\fP(3X) function returns
+.BR ERR "."

 .PP
 Functions prefixed with \*(``mv\*('' first perform cursor movement and
 fail if the position
 .PP
 Functions prefixed with \*(``mv\*('' first perform cursor movement and
 fail if the position


@@ -105,19 +107,40 @@ is outside the window boundaries.
 .SH NOTES
 All but \fBwinsnstr\fP may be macros.
 .SH PORTABILITY
 .SH NOTES
 All but \fBwinsnstr\fP may be macros.
 .SH PORTABILITY

-These functions are described in X/Open Curses, Issue 4,
-which adds \fI\%const\fP qualifiers to the arguments.
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.

 .PP
 .PP

-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.
+Issue 4 distinguished
+.B \%insnstr
+and
+.B \%winsnstr
+by stating they \*(``do not perform wrapping\*(''.
+This was probably an error,
+since it makes this group of functions inconsistent.
+No implementation of
+.I curses
+documents this inconsistency,
+and Issue 7 removed it.

 .PP
 .PP

-X/Open states that the entire string is inserted if \fIn\fP is less than 1.
+Issue 4 states that the entire string is inserted if
+.I n
+is less than 1.

 This is probably an error,
 because it is inconsistent with other functions,
 This is probably an error,
 because it is inconsistent with other functions,

-and differs from the SVr4 and X/Open implementations on Solaris.
+and differs from the SVr4
+.I curses
+and Solaris
+.I xcurses
+implementations.
+Nevertheless,
+Issue 7 retains it.

 .SH SEE ALSO
 .SH SEE ALSO

+\fB\%curs_ins_wstr\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_ins_wstr\fP(3X),
 \fB\%curses\fP(3X),
 \fB\%curs_inch\fP(3X),
 \fB\%curs_ins_wstr\fP(3X),