Debian Codegraph @

upstream/debian-trixie/man3/inwstr.3ncurses

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.56 2025/01/19 00:51:10 tom Exp $
31 .TH inwstr 3NCURSES 2025-01-18 "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(3NCURSES) 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 They return
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 .I win
130 is
131 .I NULL
132 or
133 .bP
134 .I wstr
135 is
136 .IR NULL "."
137 .PP
138 Functions prefixed with \*(``mv\*('' first perform cursor movement and
139 fail if the position
140 .RI ( y ,
141 .IR x )
142 is outside the window boundaries.
143 .SH NOTES
144 All of these functions except
145 .B \%winnwstr
146 may be implemented as macros.
147 .PP
148 Reading a line that overflows the array pointed to by
149 .I str
150 with
151 .BR \%inwstr ","
152 .BR \%winwstr ","
153 .BR \%mvinwstr ","
154 or
155 .B \%mvwinwstr
156 causes undefined results.
157 Use of
158 .BR \%innwstr ","
159 .BR \%winnwstr ","
160 .BR \%mvinnwstr ","
161 and
162 .B \%mvwinnwstr
163 is recommended instead.
164 .SH EXTENSIONS
165 .BR \%innwstr ","
166 .BR \%winnwstr ","
167 .BR \%mvinnwstr ","
168 and
169 .BR \%mvwinnwstr "'s"
170 acceptance of negative
171 .I n
172 values is an
173 .I \%ncurses
174 extension.
175 .SH PORTABILITY
176 Applications employing
177 .I \%ncurses
178 extensions should condition their use on the visibility of the
179 .B \%NCURSES_VERSION
180 preprocessor macro.
181 .PP
182 X/Open Curses Issue\ 4 describes these functions.
183 It specifies no error conditions for them.
184 .PP
185 Notwithstanding the foregoing,
186 X/Open Curses Issues 4 and 7 both state that
187 .BR \%innwstr ","
188 .BR \%winnwstr ","
189 .BR \%mvinnwstr ","
190 and
191 .B \%mvwinnwstr
192 \*(``fail .\|.\|. [i]f the array is not large enough to contain any
193 complete characters\*(''.
194 Strictly interpreted,
195 this means that a caller of these functions cannot use their return
196 values to detect truncation of a wide-character string copied from more
197 than one character cell in
198 .IR win "."
199 .I \%ncurses
200 reports any truncation with
201 .BR ERR "."
202 .PP
203 X/Open Curses specifies
204 .BR \%inwstr ","
205 .BR \%winwstr ","
206 .BR \%mvinwstr ","
207 and
208 .B \%mvwinwstr
209 as returning
210 .B OK
211 rather than a (wide) character count,
212 unlike their non-wide counterparts
213 .BR \%instr ","
214 .BR \%winstr ","
215 .BR \%mvinstr ","
216 and
217 .BR \%mvwinstr "."
218 .I \%ncurses
219 regards this inconsistency as an error in the standard.
220 .SH HISTORY
221 The System\ V Interface Definition,
222 Version 4 (1995),
223 specified
224 .I \%winwstr
225 and
226 .I \%winnwstr
227 (and the usual variants).
228 .\" SVID 4, vol 3., p. 516
229 These were later additions to
230 .RI SVr4. x ,
231 not appearing in the first SVr4 (1989).
232 Their synopses described each function as taking
233 an argument of type
234 .RI pointer-to- char
235 instead of
236 .RI pointer-to- wchar_t ,
237 despite describing them as \*(``returning the string of
238 .I \%wchar_t
239 in
240 .IR str "\*(''."
241 Presumably this was an error in the System\ V Interface Definition.
242 .SH SEE ALSO
243 \fB\%instr\fP(3NCURSES) describes comparable functions of the
244 .I \%ncurses
245 library in its non-wide-character configuration.
246 .PP
247 \fB\%ncurses\fP(3NCURSES),
248 \fB\%in_wch\fP(3NCURSES),
249 \fB\%in_wchstr\fP(3NCURSES)