Debian Codegraph @

upstream/debian-unstable/man3/ins_wstr.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2019-2024,2025 Thomas E. Dickey *
3 .\" Copyright 2002-2012,2017 Free Software Foundation, Inc. *
4 .\" *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a *
6 .\" copy of this software and associated documentation files (the *
7 .\" "Software"), to deal in the Software without restriction, including *
8 .\" without limitation the rights to use, copy, modify, merge, publish, *
9 .\" distribute, distribute with modifications, sublicense, and/or sell *
10 .\" copies of the Software, and to permit persons to whom the Software is *
11 .\" furnished to do so, subject to the following conditions: *
12 .\" *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
15 .\" *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
23 .\" *
24 .\" Except as contained in this notice, the name(s) of the above copyright *
25 .\" holders shall not be used in advertising or otherwise to promote the *
26 .\" sale, use or other dealings in this Software without prior written *
27 .\" authorization. *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: curs_ins_wstr.3x,v 1.60 2025/03/01 21:30:14 tom Exp $
31 .TH ins_wstr 3NCURSES 2025-03-01 "ncurses 6.6" "Library calls"
32 .ie \n(.g \{\
33 .ds `` \(lq
34 .ds '' \(rq
35 .\}
36 .el \{\
37 .ie t .ds `` ``
38 .el .ds `` ""
39 .ie t .ds '' ''
40 .el .ds '' ""
41 .\}
42 .
43 .de bP
44 .ie n .IP \(bu 4
45 .el .IP \(bu 2
46 ..
47 .SH NAME
48 \fB\%ins_wstr\fP,
49 \fB\%wins_wstr\fP,
50 \fB\%mvins_wstr\fP,
51 \fB\%mvwins_wstr\fP,
52 \fB\%ins_nwstr\fP,
53 \fB\%wins_nwstr\fP,
54 \fB\%mvins_nwstr\fP,
55 \fB\%mvwins_nwstr\fP \-
56 insert a wide-character string in a \fIcurses\fR window
57 .SH SYNOPSIS
58 .nf
59 \fB#include <curses.h>
60 .PP
61 \fBint ins_wstr(const wchar_t * \fIwstr\fP);
62 \fBint wins_wstr(WINDOW * \fIwin\fP, const wchar_t * \fIwstr\fP);
63 \fBint mvins_wstr(int \fIy\fP, int \fIx\fP, const wchar_t * \fIwstr\fP);
64 \fBint mvwins_wstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP,
65 const wchar_t * \fIwstr\fP);
66 .PP
67 \fBint ins_nwstr(const wchar_t * \fIwstr\fP, int \fIn\fP);
68 \fBint wins_nwstr(WINDOW * \fIwin\fP, const wchar_t * \fIwstr\fP, int \fIn\fP);
69 \fBint mvins_nwstr(int \fIy\fP, int \fIx\fP, const wchar_t * \fIwstr\fP, int \fIn\fP);
70 \fBint mvwins_nwstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP,
71 const wchar_t * \fIwstr\fP, int \fIn\fP);
72 .fi
73 .SH DESCRIPTION
74 .B \%wins_wstr
75 inserts a wide-character string
76 .I wstr
77 before the character at the cursor in window
78 .I win
79 as if by calling \fBwins_wch\fP(3NCURSES) for each
80 .I \%wchar_t
81 in
82 .IR wstr "."
83 No line wrapping is performed.
84 Characters to the right of the cursor are shifted right;
85 those at the right edge of the window may be lost.
86 .B \%wins_wstr
87 stops inserting if it would have to wrap to the next line to write the
88 next
89 .I \%wchar_t
90 in
91 .IR wstr "."
92 The cursor position does not change
93 (after moving to
94 .RI ( y ,
95 .IR x "),"
96 if specified).
97 .B \%wins_nwstr
98 does the same,
99 but inserts at most
100 .I n
101 wide characters,
102 or as many as possible
103 (up to the end of the line)
104 if
105 .I n
106 is negative.
107 \fB\%ncurses\fP(3NCURSES) describes the variants of these functions.
108 .SH RETURN VALUE
109 These functions return
110 .B OK
111 on success and
112 .B ERR
113 on failure.
114 .PP
115 In
116 .IR \%ncurses ","
117 they return
118 .B ERR
119 if
120 .bP
121 .I win
122 is
123 .IR NULL ","
124 .bP
125 .I wstr
126 is
127 .IR NULL ","
128 .bP
129 the first wide character in
130 .I wstr
131 is a non-spacing character,
132 or
133 .bP
134 an internal \fB\%wins_wch\fP(3NCURSES) call returns
135 .BR ERR "."
136 .PP
137 Functions prefixed with \*(``mv\*('' first perform cursor movement and
138 fail if the position
139 .RI ( y ,
140 .IR x )
141 is outside the window boundaries.
142 .SH NOTES
143 All of these functions except
144 .B \%wins_nwstr
145 may be implemented as macros.
146 .SH EXTENSIONS
147 .BR \%ins_nwstr ","
148 .BR \%wins_nwstr ","
149 .BR \%mvins_nwstr ","
150 and
151 .BR \%mvwins_nwstr "'s"
152 acceptance of negative
153 .I n
154 values is an
155 .I \%ncurses
156 extension.
157 .SH PORTABILITY
158 Applications employing
159 .I \%ncurses
160 extensions should condition their use on the visibility of the
161 .B \%NCURSES_VERSION
162 preprocessor macro.
163 .PP
164 X/Open Curses Issue\ 4 describes these functions.
165 It specifies no error conditions for them.
166 .PP
167 X/Open Curses does not specify what happens
168 if a non-spacing character follows a control character.
169 .PP
170 Issue\ 4 states that the entire string is inserted if
171 .I n
172 is less than 1.
173 This is probably an error,
174 .\" ...copied from SVID 4, which made the same error; see p. 513.
175 because it is inconsistent with other functions
176 such as
177 .IR \%waddwstr ","
178 and differs from the SVr4
179 .I curses
180 and Solaris
181 .I xcurses
182 implementations.
183 Nevertheless,
184 Issue\ 7 retains the language.
185 .SH HISTORY
186 X/Open Curses Issue\ 4 (1995) initially specified these functions.
187 The System\ V Interface Definition Version\ 4 (1995),
188 specified functions named
189 .I \%winswstr
190 and
191 .I \%winsnwstr
192 (and the usual variants).
193 .\" SVID 4, vol 3., p. 513
194 .\" The prototypes also identify the data type as `wchar`, not
195 .\" `wchar_t`, but this may be an error since the "DESCRIPTION" section
196 .\" consistently uses the latter. --GBR
197 These were later additions to
198 .RI SVr4. x ,
199 not appearing in the first SVr4 (1989).
200 They differ from X/Open's later
201 .I \%wins_wstr
202 and
203 .I \%wins_nwstr
204 in that their
205 .I wstr
206 parameters are not
207 .IR const "-qualified."
208 .SH SEE ALSO
209 \fB\%insstr\fP(3NCURSES) describes comparable functions of the
210 .I \%ncurses
211 library in its non-wide-character configuration.
212 .PP
213 \fB\%ncurses\fP(3NCURSES),
214 \fB\%ins_wch\fP(3NCURSES),
215 \fB\%in_wch\fP(3NCURSES)