Debian Codegraph @

upstream/mageia-cauldron/man3/curs_get_wstr.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_get_wstr.3x,v 1.77 2025/07/05 12:52:35 tom Exp $
31 .TH curs_get_wstr 3X 2025-07-05 "ncurses 6.5" "Library calls"
32 .ie \n(.g \{\
33 .ds `` \(lq
34 .ds '' \(rq
35 .ds ^ \(ha
36 .\}
37 .el \{\
38 .ie t .ds `` ``
39 .el .ds `` ""
40 .ie t .ds '' ''
41 .el .ds '' ""
42 .ds ^ ^
43 .\}
44 .
45 .de bP
46 .ie n .IP \(bu 4
47 .el .IP \(bu 2
48 ..
49 .SH NAME
50 \fB\%get_wstr\fP,
51 \fB\%getn_wstr\fP,
52 \fB\%wget_wstr\fP,
53 \fB\%wgetn_wstr\fP,
54 \fB\%mvget_wstr\fP,
55 \fB\%mvgetn_wstr\fP,
56 \fB\%mvwget_wstr\fP,
57 \fB\%mvwgetn_wstr\fP \-
58 read a wide-character string from a \fIcurses\fR terminal keyboard
59 .SH SYNOPSIS
60 .nf
61 \fB#include <curses.h>
62 .PP
63 \fBint get_wstr(wint_t * \fIwstr\fP);
64 \fBint wget_wstr(WINDOW * \fIwin\fP, wint_t * \fIwstr\fP);
65 \fBint mvget_wstr(int \fIy\fP, int \fIx\fP, wint_t * \fIwstr\fP);
66 \fBint mvwget_wstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, wint_t * \fIwstr\fP);
67 .PP
68 \fBint getn_wstr(wint_t * \fIwstr\fP, int \fIn\fP);
69 \fBint wgetn_wstr(WINDOW * \fIwin\fP, wint_t * \fIwstr\fP, int \fIn\fP);
70 \fBint mvgetn_wstr(int \fIy\fP, int \fIx\fP, wint_t * \fIwstr\fP, int \fIn\fP);
71 \fBint mvwgetn_wstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, wint_t * \fIwstr\fP,
72 int \fIn\fP);
73 .fi
74 .SH DESCRIPTION
75 .B \%wget_wstr
76 populates a user-supplied wide-character string buffer
77 .I wstr
78 by repeatedly calling \fBwget_wch\fP(3X)
79 with the
80 .I win
81 argument
82 until a line feed or carriage return character is input.
83 The function
84 .bP
85 does not copy the terminating character to
86 .IR wstr ";"
87 .bP
88 populates
89 .I wstr
90 with
91 .I WEOF
92 (as defined in
93 .IR \%wchar.h )
94 if an end-of-file condition occurs on the input;
95 .bP
96 always terminates the string with a null wide character
97 (after any
98 .IR WEOF );
99 .bP
100 interprets the screen's wide erase and wide kill characters
101 (see \fB\%erasewchar\fP(3X) and \fB\%killwchar\fP(3X));
102 .bP
103 recognizes function keys only if the screen's keypad option is enabled
104 (see \fB\%keypad\fP(3X));
105 .bP
106 treats the function keys
107 .B \%KEY_LEFT
108 and
109 .B \%KEY_BACKSPACE
110 the same as the wide erase character;
111 and
112 .bP
113 discards function key inputs other than those
114 treated as the wide erase or wide kill characters,
115 calling \fBbeep\fP(3X).
116 .PP
117 The wide erase character replaces the character at the end of the buffer
118 with a null wide character,
119 while the wide kill character does the same for the entire buffer.
120 .PP
121 If the screen's echo option is enabled
122 (see \fBecho\fP(3X)),
123 .B \%wget_wstr
124 updates
125 .I win
126 with \fB\%wadd_wch\fP(3X).
127 Further,
128 .bP
129 the wide erase character
130 and its function key synonyms
131 move the cursor to the left,
132 and
133 .bP
134 the wide kill character returns the cursor to where it was located when
135 .B \%wget_wstr
136 was called.
137 .PP
138 .B \%wgetn_wstr
139 is similar,
140 but reads at most
141 .I n
142 wide characters,
143 aiding the application to avoid overrunning the buffer to which
144 .I wstr
145 points.
146 .I curses
147 ignores an attempt to input more than
148 .I n
149 wide characters
150 (other than the terminating line feed or carriage return),
151 calling \fBbeep\fP(3X).
152 If
153 .I n
154 is negative,
155 .B \%wgetn_wstr
156 reads up to
157 .I LINE_MAX
158 wide characters
159 (see
160 .IR sysconf (3)).
161 .PP
162 \fB\%ncurses\fP(3X) describes the variants of these functions.
163 .SH RETURN VALUE
164 These functions return
165 .B OK
166 on success and
167 .B ERR
168 on failure.
169 .PP
170 In
171 .IR \%ncurses ","
172 these functions fail if
173 .bP
174 the
175 .I curses
176 screen has not been initialized,
177 .bP
178 (for functions taking a
179 .I \%WINDOW
180 pointer argument)
181 .I win
182 is a null pointer,
183 .bP
184 .I wstr
185 is a null pointer,
186 or
187 .bP
188 an internal \fB\%wget_wch\fP(3X) call fails.
189 .PP
190 Functions prefixed with \*(``mv\*('' first perform cursor movement and
191 fail if the position
192 .RI ( y ,
193 .IR x )
194 is outside the window boundaries.
195 .SH NOTES
196 All of these functions except
197 .B \%wgetn_wstr
198 may be implemented as macros.
199 .PP
200 Reading input that overruns the buffer pointed to by
201 .I wstr
202 causes undefined results.
203 Use the
204 .BR n -infixed
205 functions,
206 and allocate sufficient storage for
207 .I wstr
208 \(em at least
209 .IR n +1
210 times
211 .BR sizeof(wchar_t) "."
212 .PP
213 These functions cannot store a
214 .B KEY_
215 value in
216 .I wstr
217 because there is no way to distinguish it
218 from a valid
219 .I \%wchar_t
220 value.
221 .PP
222 While these functions conceptually implement
223 a series of calls to
224 .BR \%wget_wch ","
225 they also temporarily change properties of the
226 .I curses
227 screen to permit simple editing of the input buffer.
228 Each function saves the screen's state,
229 calls \fBnl\fP(3X),
230 and,
231 if the screen was in canonical (\*(``cooked\*('') mode,
232 \fB\%cbreak\fP(3X).
233 Before returning,
234 it restores the saved screen state.
235 Other implementations differ in detail,
236 affecting which control characters they can accept in the buffer;
237 see section \*(``PORTABILITY\*('' below.
238 .PP
239 Unlike \fBgetstr\fP(3X) and related functions of
240 .IR \%ncurses 's
241 non-wide API,
242 these functions do not return
243 .B \%KEY_RESIZE
244 if a
245 .I \%SIGWINCH
246 event interrupts the function.
247 .SH EXTENSIONS
248 .BR \%getn_wstr ","
249 .BR \%wgetn_wstr ","
250 .BR \%mvgetn_wstr ","
251 and
252 .BR \%mvwgetn_wstr "'s"
253 handing of negative
254 .I n
255 values is an
256 .I \%ncurses
257 extension.
258 .SH PORTABILITY
259 Applications employing
260 .I \%ncurses
261 extensions should condition their use on the visibility of the
262 .B \%NCURSES_VERSION
263 preprocessor macro.
264 .PP
265 X/Open Curses Issue\ 4 describes these functions.
266 It specifies no error conditions for them.
267 .PP
268 Issue\ 4 documented these functions as passing an array of
269 .IR wchar_t ","
270 but that was an error,
271 conflicting with the following language in the standard.
272 .RS
273 .PP
274 The effect of
275 .IR \%get_wstr "()"
276 is as though a series of calls to
277 .IR \%get_wch "()"
278 were made,
279 until a newline character,
280 end-of-line character,
281 or end-of-file character is processed.
282 .\" X/Open Curses Issue 4, Version 2, p. 96.
283 .RE
284 .PP
285 .I \%get_wch
286 can return a negative value
287 .RI ( WEOF ),
288 but
289 .I \%wchar_t
290 is a unsigned type.
291 All of the vendors implement these functions using
292 .IR \%wint_t ","
293 following the Issue\ 7 standard.
294 .PP
295 X/Open Curses Issue\ 7 is unclear whether the terminating null wide character
296 counts toward the length parameter
297 .IR n "."
298 A similar issue affected
299 .I \%wgetnstr
300 in Issue\ 4,
301 Version\ 2;
302 Issue\ 7 revised that function's description to address the issue,
303 but not that of
304 .IR \%wget_nwstr ","
305 leaving it ambiguous.
306 .I \%ncurses
307 counts the terminator in the length.
308 .PP
309 X/Open Curses does not specify what happens if the length
310 .I n
311 is negative.
312 .bP
313 For consistency with
314 .IR \%wgetnstr ","
315 .I \%ncurses
316 6.2 uses a limit based on
317 .IR LINE_MAX "."
318 .bP
319 Some other implementations
320 (such as Solaris
321 .IR xcurses )
322 do the same,
323 while others
324 .RI \%( PDCurses )
325 do not permit a negative
326 .IR n "."
327 .bP
328 NetBSD\ 7
329 .I curses
330 imitates
331 .I \%ncurses
332 6.1 and earlier,
333 treating a negative
334 .I n
335 as an unbounded count of wide characters.
336 .PP
337 Implementations vary in their handling of input control characters.
338 .bP
339 While they may enable the screen's echo option,
340 some do not take it out of raw mode,
341 and may take cbreak mode into account
342 when deciding whether to handle echoing within
343 .I \%wgetn_wstr
344 or to rely on it as a side effect of calling
345 .IR \%wget_wch "."
346 .IP
347 Since 1995,
348 .I \%ncurses
349 has provided handlers for
350 .I SIGINTR
351 and
352 .I SIGQUIT
353 events,
354 which are typically generated at the keyboard with
355 .B \*^C
356 and
357 .B \*^\e
358 respectively.
359 In cbreak mode,
360 those handlers catch a signal and stop the program,
361 whereas other implementations write those characters into the buffer.
362 .bP
363 Starting with
364 .I \%ncurses
365 6.3 (2021),
366 .I \%wgetn_wstr
367 preserves raw mode if the screen was already in that state,
368 allowing one to enter the characters the terminal interprets
369 as interrupt and quit events
370 into the buffer,
371 for consistency with SVr4
372 .IR curses 's
373 .IR \%wgetnstr .
374 .SH HISTORY
375 X/Open Curses Issue\ 4 (1995) initially specified these functions.
376 The System\ V Interface Definition Version\ 4
377 of the same year
378 specified functions named
379 .I \%wgetwstr
380 and
381 .I \%wgetnwstr
382 (and the usual variants).
383 .\" SVID 4, vol 3., p. 500
384 These were later additions to
385 .RI SVr4. x ,
386 not appearing in the first SVr4 (1989).
387 Except in name,
388 their declarations did not differ from X/Open's later
389 .I \%wget_wstr
390 and
391 .I \%wgetn_wstr
392 until
393 X/Open Curses Issue 7 (2009)
394 eventually changed the type of the buffer argument to a pointer to
395 .IR \%wint_t "."
396 .SH SEE ALSO
397 \fB\%curs_getstr\fP(3X) describes comparable functions of the
398 .I \%ncurses
399 library in its non-wide-character configuration.
400 .PP
401 \fB\%curses\fP(3X),
402 \fB\%curs_get_wch\fP(3X)