Debian Codegraph @

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