Debian Codegraph @

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