ncurses 6.4 - patch 20231202

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

diff --git a/man/curs_ins_wstr.3x b/man/curs_ins_wstr.3x
index 648560708f47dcf2f692fe37d0d7d66daf60fee7..f059fceec61c533e39bf2dc603348eb5a88b0703 100644 (file)
--- a/man/curs_ins_wstr.3x
+++ b/man/curs_ins_wstr.3x
@@ -27,12 +27,23 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_ins_wstr.3x,v 1.20 2023/09/16 23:37:03 tom Exp $
-.TH curs_ins_wstr 3X 2023-09-16 "ncurses 6.4" "Library calls"
-.ie \n(.g .ds `` \(lq
-.el       .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el       .ds '' ''
+.\" $Id: curs_ins_wstr.3x,v 1.29 2023/11/25 11:29:34 tom Exp $
+.TH curs_ins_wstr 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.\}
+.
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..

 .SH NAME
 \fB\%ins_wstr\fP,
 \fB\%ins_nwstr\fP,
 .SH NAME
 \fB\%ins_wstr\fP,
 \fB\%ins_nwstr\fP,


@@ -45,64 +56,68 @@
 insert a wide-character string in a \fIcurses\fR window
 .SH SYNOPSIS
 .nf
 insert a wide-character string in a \fIcurses\fR window
 .SH SYNOPSIS
 .nf

-\fB#include <curses.h>\fP
-.sp
-\fBint ins_wstr(const wchar_t *\fIwstr);\fR
-.br
-\fBint ins_nwstr(const wchar_t *\fIwstr\fB, int \fIn\fB);\fR
-.br
-\fBint wins_wstr(WINDOW *\fIwin\fB, const wchar_t *\fIwstr\fB);\fR
-.br
-\fBint wins_nwstr(WINDOW *\fIwin\fB, const wchar_t *\fIwstr\fB, int \fIn\fB);\fR
-.sp
-\fBint mvins_wstr(int \fIy\fB, int \fIx\fB, const wchar_t *\fIwstr\fB);\fR
-.br
-\fBint mvins_nwstr(int \fIy\fB, int \fIx\fB, const wchar_t *\fIwstr\fB, int \fIn\fB);\fR
-.br
-\fBint mvwins_wstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const wchar_t *\fIwstr\fB);\fR
-.br
-\fBint mvwins_nwstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const wchar_t *\fIwstr\fB, int \fIn\fB);\fR
+\fB#include <curses.h>
+.PP
+\fBint ins_wstr(const wchar_t *\fIwstr\fP);
+\fBint ins_nwstr(const wchar_t *\fIwstr\fP, int \fIn\fP);
+\fBint wins_wstr(WINDOW *\fIwin\fP, const wchar_t *\fIwstr\fP);
+\fBint wins_nwstr(WINDOW *\fIwin\fP, const wchar_t *\fIwstr\fP, int \fIn\fP);
+.PP
+\fBint mvins_wstr(int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP);
+\fBint mvins_nwstr(int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP, int \fIn\fP);
+\fBint mvwins_wstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP);
+\fBint mvwins_nwstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP, int \fIn\fP);

 .fi
 .SH DESCRIPTION
 These routines insert a \fBwchar_t\fP character string
 (as many characters as will fit on the line)
 .fi
 .SH DESCRIPTION
 These routines insert a \fBwchar_t\fP character string
 (as many characters as will fit on the line)

-before the character under the cursor.
+before the character under the cursor,
+as if calling \fBwins_wch\fP(3X).

 All characters to the right of the cursor are shifted right,
 with the possibility of the rightmost characters on the line being lost.
 No wrapping is performed.
 All characters to the right of the cursor are shifted right,
 with the possibility of the rightmost characters on the line being lost.
 No wrapping is performed.

+.PP

 The cursor position does not change
 (after moving to \fIy\fP, \fIx\fP, if specified).
 The cursor position does not change
 (after moving to \fIy\fP, \fIx\fP, if specified).

-The four routines with \fIn\fP as the last argument
+.PP
+The functions with \fIn\fP as the last argument

 insert a leading substring of at most \fIn\fP \fBwchar_t\fP characters.
 insert a leading substring of at most \fIn\fP \fBwchar_t\fP characters.

-If \fIn\fP is less than 1, the entire string is inserted.
+If \fIn\fP is less than zero, the entire string is inserted
+(stopping on a L'\e0' character).
+.PP
+Special characters are handled as in \fBwadd_wch\fP(3X).
+.SH RETURN VALUE
+All functions return the integer \fBERR\fP upon failure and \fBOK\fP on success.

 .PP
 .PP

-If a character in \fIwstr\fP is a tab, newline, carriage return or
-backspace, the cursor is moved appropriately within the window.
-A newline also does a \fBclrtoeol\fP before moving.
-Tabs are considered to be at every eighth column.
-If a character in \fIwstr\fP is another control character,
-it is drawn in the \fB^\fIX\fR notation.
-Calling \fBwin_wch\fP after adding a control character
-(and moving to it, if necessary)
-does not return the control character,
-but instead returns a character in the ^-representation
-of the control character.
+X/Open does not define any error conditions.
+This implementation returns an error
+.bP
+if the \fIwin\fP parameter is null or
+.bP
+if the \fIwstr\fP parameter is null or
+.bP
+if the \fBwins_wch\fP function returns an error.
+.PP
+Functions with a \*(``mv\*('' prefix first perform a cursor movement using
+\fBwmove\fP(3X), and return an error if the position is outside the window,
+or if the window pointer is null.

 .SH NOTES
 .SH NOTES

-Note that all but wins_nwstr may be macros.
+All but \fBwins_nwstr\fP may be macros.

 .PP
 If the first character in the string is a nonspacing character, these
 functions will fail.
 XSI does not define what will happen if a nonspacing character follows
 a control character.
 .PP
 If the first character in the string is a nonspacing character, these
 functions will fail.
 XSI does not define what will happen if a nonspacing character follows
 a control character.

-.SH RETURN VALUE
-Upon successful completion, these functions return \fBOK\fP.
-Otherwise, they return \fBERR\fP.
+.SH PORTABILITY
+These functions are described in the XSI Curses standard, Issue 4,
+which adds \fI\%const\fP qualifiers to the arguments.

 .PP
 .PP

-Functions with a \*(``mv\*('' prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+X/Open states that the entire string is inserted if \fIn\fP is less than 1.
+This is probably an error,
+because it is inconsistent with other functions,
+and differs from the X/Open implementation on Solaris.

 .SH SEE ALSO
 .SH SEE ALSO

-\fBcurses\fP(3X),
-\fBcurs_insstr\fP(3X),
-\fBcurs_in_wch\fP(3X),
-\fBcurs_ins_wch\fP(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_insstr\fP(3X),
+\fB\%curs_ins_wch\fP(3X),
+\fB\%curs_in_wch\fP(3X)