Debian Codegraph @

upstream/mageia-cauldron/man3/curs_inwstr.3x

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-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_inwstr.3x,v 1.60 2025/03/01 21:29:42 tom Exp $
31 .TH curs_inwstr 3X 2025-03-01 "ncurses 6.5" "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 .de bP
43 .ie n .IP \(bu 4
44 .el .IP \(bu 2
45 ..
46 .SH NAME
47 \fB\%inwstr\fP,
48 \fB\%winwstr\fP,
49 \fB\%mvinwstr\fP,
50 \fB\%mvwinwstr\fP,
51 \fB\%innwstr\fP,
52 \fB\%winnwstr\fP,
53 \fB\%mvinnwstr\fP,
54 \fB\%mvwinnwstr\fP \-
55 get a wide-character string from a \fIcurses\fR window
56 .SH SYNOPSIS
57 .nf
58 \fB#include <curses.h>
59 .PP
60 \fBint inwstr(wchar_t * \fIwstr\fP);
61 \fBint winwstr(WINDOW * \fIwin\fP, wchar_t * \fIwstr\fP);
62 \fBint mvinwstr(int \fIy\fP, int \fIx\fP, wchar_t * \fIwstr\fP);
63 \fBint mvwinwstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, wchar_t * \fIwstr\fP);
64 .PP
65 \fBint innwstr(wchar_t * \fIwstr\fP, int \fIn\fP);
66 \fBint winnwstr(WINDOW * \fIwin\fP, wchar_t * \fIwstr\fP, int \fIn\fP);
67 \fBint mvinnwstr(int \fIy\fP, int \fIx\fP, wchar_t * \fIwstr\fP, int \fIn\fP);
68 \fBint mvwinnwstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, wchar_t * \fIwstr\fP,
69 int \fIn\fP);
70 .fi
71 .SH DESCRIPTION
72 .B \%winwstr
73 extracts a wide-character string from a
74 .I curses
75 window
76 .IR win ","
77 starting at the cursor and stopping at the end of the line,
78 and stores it in
79 .IR wstr ","
80 terminating it with a wide null character
81 and
82 omitting any attributes and color pair identifier
83 that
84 .I curses
85 associates with each character.
86 .B \%winnwstr
87 does the same,
88 but copies at most
89 .I n
90 wide characters from
91 .IR win "."
92 A negative
93 .I n
94 implies no limit;
95 .B \%winnwstr
96 then works like
97 .BR \%winwstr "."
98 \fB\%ncurses\fP(3X) describes the variants of these functions.
99 .SH RETURN VALUE
100 On successful operation,
101 these functions return the count of wide characters copied from
102 .I win
103 to
104 .IR wstr ","
105 or
106 .B ERR
107 upon failure.
108 .BR \%innwstr ","
109 .BR \%winnwstr ","
110 .BR \%mvinnwstr ","
111 and
112 .B \%mvwinnwstr
113 return
114 .B ERR
115 if
116 .I n
117 is insufficiently large to store a complete wide character string.
118 (Recall that a
119 .I curses
120 complex character can contain multiple wide characters,
121 some of which may be non-spacing.)
122 .PP
123 In
124 .IR \%ncurses ","
125 these functions return
126 .B ERR
127 if
128 .bP
129 the
130 .I curses
131 screen has not been initialized,
132 .bP
133 (for functions taking a
134 .I \%WINDOW
135 pointer argument)
136 .I win
137 is a null pointer,
138 or
139 .bP
140 .I wstr
141 is a null pointer.
142 .PP
143 Functions prefixed with \*(``mv\*('' first perform cursor movement and
144 fail if the position
145 .RI ( y ,
146 .IR x )
147 is outside the window boundaries.
148 .SH NOTES
149 All of these functions except
150 .B \%winnwstr
151 may be implemented as macros.
152 .PP
153 Reading a line that overflows the array pointed to by
154 .I wstr
155 with
156 .BR \%inwstr ","
157 .BR \%winwstr ","
158 .BR \%mvinwstr ","
159 or
160 .B \%mvwinwstr
161 causes undefined results.
162 Use of
163 .BR \%innwstr ","
164 .BR \%winnwstr ","
165 .BR \%mvinnwstr ","
166 and
167 .B \%mvwinnwstr
168 is recommended instead.
169 .SH EXTENSIONS
170 .BR \%innwstr ","
171 .BR \%winnwstr ","
172 .BR \%mvinnwstr ","
173 and
174 .BR \%mvwinnwstr "'s"
175 acceptance of negative
176 .I n
177 values is an
178 .I \%ncurses
179 extension.
180 .SH PORTABILITY
181 Applications employing
182 .I \%ncurses
183 extensions should condition their use on the visibility of the
184 .B \%NCURSES_VERSION
185 preprocessor macro.
186 .PP
187 X/Open Curses Issue\ 4 describes these functions.
188 It specifies no error conditions for them.
189 .PP
190 Notwithstanding the foregoing,
191 X/Open Curses Issues 4 and 7 both state that
192 .IR \%innwstr ","
193 .IR \%winnwstr ","
194 .IR \%mvinnwstr ","
195 and
196 .I \%mvwinnwstr
197 \*(``fail .\|.\|. [i]f the array is not large enough to contain any
198 complete characters\*(''.
199 Strictly interpreted,
200 this means that a caller of these functions cannot use their return
201 values to detect truncation of a wide-character string copied from more
202 than one character cell in
203 .IR win "."
204 .I \%ncurses
205 reports any truncation with
206 .IR ERR "."
207 .PP
208 X/Open Curses specifies
209 .IR \%inwstr ","
210 .IR \%winwstr ","
211 .IR \%mvinwstr ","
212 and
213 .I \%mvwinwstr
214 as returning
215 .I OK
216 rather than a (wide) character count,
217 unlike their non-wide counterparts
218 .IR \%instr ","
219 .IR \%winstr ","
220 .IR \%mvinstr ","
221 and
222 .IR \%mvwinstr "."
223 .I \%ncurses
224 regards this inconsistency as an error in the standard.
225 .SH HISTORY
226 The System\ V Interface Definition,
227 Version 4 (1995),
228 specified
229 .I \%winwstr
230 and
231 .I \%winnwstr
232 (and the usual variants).
233 .\" SVID 4, vol 3., p. 516
234 These were later additions to
235 .RI SVr4. x ,
236 not appearing in the first SVr4 (1989).
237 Their synopses described each function as taking
238 an argument of type
239 .RI pointer-to- char
240 instead of
241 .RI pointer-to- wchar_t ,
242 despite describing them as \*(``returning the string of
243 .I \%wchar_t
244 in
245 .IR str "\*(''."
246 Presumably this was an error in the System\ V Interface Definition.
247 .SH SEE ALSO
248 \fB\%curs_instr\fP(3X) describes comparable functions of the
249 .I \%ncurses
250 library in its non-wide-character configuration.
251 .PP
252 \fB\%curses\fP(3X),
253 \fB\%curs_in_wch\fP(3X),
254 \fB\%curs_in_wchstr\fP(3X)