Debian Codegraph @

upstream/debian-unstable/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.66 2025/10/21 00:04:48 tom Exp $
31 .TH inwstr 3NCURSES 2025-10-20 "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 .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, int \fIn\fP);
69 .fi
70 .SH DESCRIPTION
71 .B \%winwstr
72 extracts a wide-character string from a
73 .I curses
74 window
75 .IR win ","
76 starting at the cursor and stopping at the end of the line,
77 and stores it in
78 .IR wstr ","
79 terminating it with a wide null character
80 and
81 omitting any attributes and color pair identifier
82 that
83 .I curses
84 associates with each character.
85 .B \%winnwstr
86 does the same,
87 but copies at most
88 .I n
89 wide characters from
90 .IR win "."
91 A negative
92 .I n
93 implies no limit;
94 .B \%winnwstr
95 then works like
96 .BR \%winwstr "."
97 \fB\%ncurses\fP(3NCURSES) describes the variants of these functions.
98 .SH RETURN VALUE
99 On successful operation,
100 these functions return the count of wide characters copied from
101 .I win
102 to
103 .I wstr
104 (not including the wide null terminator),
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 and its variants causes undefined results.
156 Instead,
157 use the
158 .IR n -infixed
159 functions with a positive
160 .I n
161 argument no larger than the size of the buffer backing
162 .IR wstr "."
163 .SH EXTENSIONS
164 .BR \%innwstr ","
165 .BR \%winnwstr ","
166 .BR \%mvinnwstr ","
167 and
168 .BR \%mvwinnwstr "'s"
169 acceptance of negative
170 .I n
171 values is an
172 .I \%ncurses
173 extension.
174 .SH PORTABILITY
175 Applications employing
176 .I \%ncurses
177 extensions should condition their use on the visibility of the
178 .B \%NCURSES_VERSION
179 preprocessor macro.
180 .PP
181 X/Open Curses Issue\ 4 describes these functions.
182 It specifies no error conditions for them.
183 .PP
184 Notwithstanding the foregoing,
185 X/Open Curses Issues 4 and 7 both state that
186 .IR \%innwstr ","
187 .IR \%winnwstr ","
188 .IR \%mvinnwstr ","
189 and
190 .I \%mvwinnwstr
191 \*(``fail .\|.\|. [i]f the array is not large enough to contain any
192 complete characters\*(''.
193 Strictly interpreted,
194 this means that a caller of these functions cannot use their return
195 values to detect truncation of a wide-character string copied from more
196 than one character cell in
197 .IR win "."
198 .I \%ncurses
199 reports any truncation with
200 .IR ERR "."
201 .PP
202 X/Open Curses specifies
203 .IR \%inwstr ","
204 .IR \%winwstr ","
205 .IR \%mvinwstr ","
206 and
207 .I \%mvwinwstr
208 as returning
209 .I OK
210 rather than a (wide) character count,
211 unlike their non-wide counterparts
212 .IR \%instr ","
213 .IR \%winstr ","
214 .IR \%mvinstr ","
215 and
216 .IR \%mvwinstr "."
217 .I \%ncurses
218 regards this inconsistency as an error in the standard.
219 .SH HISTORY
220 The System\ V Interface Definition,
221 Version 4 (1995),
222 specified
223 .I \%winwstr
224 and
225 .I \%winnwstr
226 (and the usual variants).
227 .\" SVID 4, vol 3., p. 516
228 These were later additions to
229 .RI SVr4. x ,
230 not appearing in the first SVr4 (1989).
231 Their synopses described each function as taking
232 an argument of type
233 .RI pointer-to- char
234 instead of
235 .RI pointer-to- wchar_t ,
236 despite describing them as \*(``returning the string of
237 .I \%wchar_t
238 in
239 .IR str "\*(''."
240 Presumably this was an error in the System\ V Interface Definition.
241 .SH SEE ALSO
242 \fB\%instr\fP(3NCURSES) describes comparable functions of the
243 .I \%ncurses
244 library in its non-wide-character configuration.
245 .PP
246 \fB\%ncurses\fP(3NCURSES),
247 \fB\%in_wch\fP(3NCURSES),
248 \fB\%in_wchstr\fP(3NCURSES)