Debian Codegraph @

upstream/mageia-cauldron/man3/curs_getstr.3x

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2010,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_getstr.3x,v 1.92 2025/07/05 12:52:05 tom Exp $
31 .TH curs_getstr 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\%getstr\fP,
51 \fB\%getnstr\fP,
52 \fB\%wgetstr\fP,
53 \fB\%wgetnstr\fP,
54 \fB\%mvgetstr\fP,
55 \fB\%mvgetnstr\fP,
56 \fB\%mvwgetstr\fP,
57 \fB\%mvwgetnstr\fP \-
58 read a character string from \fIcurses\fR terminal keyboard
59 .SH SYNOPSIS
60 .nf
61 \fB#include <curses.h>
62 .PP
63 \fBint getstr(char * \fIstr\fP);
64 \fBint wgetstr(WINDOW * \fIwin\fP, char * \fIstr\fP);
65 \fBint mvgetstr(int \fIy\fP, int \fIx\fP, char * \fIstr\fP);
66 \fBint mvwgetstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, char * \fIstr\fP);
67 .PP
68 \fBint getnstr(char * \fIstr\fP, int \fIn\fP);
69 \fBint wgetnstr(WINDOW * \fIwin\fP, char * \fIstr\fP, int \fIn\fP);
70 \fBint mvgetnstr(int \fIy\fP, int \fIx\fP, char * \fIstr\fP, int \fIn\fP);
71 \fBint mvwgetnstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, char * \fIstr\fP,
72 int \fIn\fP);
73 .fi
74 .SH DESCRIPTION
75 .B \%wgetstr
76 populates a user-supplied string buffer
77 .I str
78 by repeatedly calling \fBwgetch\fP(3X)
79 with the
80 .I win
81 argument
82 until a line feed or carriage return character is input.
83 .\" Of the two, because wgetnstr() calls nl(), only a line feed (\n)
84 .\" will ever be returned by wgetch().
85 The function
86 .bP
87 does not copy the terminating character to
88 .IR str ";"
89 .bP
90 always terminates
91 .I str
92 with a null character;
93 .bP
94 interprets the screen's erase and kill characters
95 (see \fB\%erasechar\fP(3X) and \fB\%killchar\fP(3X));
96 .bP
97 recognizes function keys only if the screen's keypad option is enabled
98 (see \fB\%keypad\fP(3X));
99 .bP
100 treats the function keys
101 .B \%KEY_LEFT
102 and
103 .B \%KEY_BACKSPACE
104 the same as the erase character;
105 and
106 .bP
107 discards function key inputs other than those
108 treated as the erase or kill characters,
109 calling \fBbeep\fP(3X).
110 .PP
111 If any characters have been written to the input buffer,
112 the erase character replaces the character
113 at the current position in the buffer
114 with a null character,
115 then decrements the position by one;
116 the kill character does the same repeatedly,
117 backtracking to the beginning of the buffer.
118 .PP
119 If the screen's echo option is enabled
120 (see \fBecho\fP(3X)),
121 .B \%wgetstr
122 updates
123 .I win
124 with \fB\%waddch\fP(3X).
125 Further,
126 .bP
127 the erase character
128 and its function key synonyms
129 move the cursor to the left
130 (if not already where it was located when
131 .B \%wgetstr
132 was called)
133 and
134 .bP
135 the kill character returns the cursor to where it was located when
136 .B \%wgetstr
137 was called.
138 .PP
139 .B \%wgetnstr
140 is similar,
141 but reads at most
142 .I n
143 characters,
144 aiding the application to avoid overrunning the buffer to which
145 .I str
146 points.
147 .I curses
148 ignores an attempt to input more than
149 .I n
150 characters
151 (other than the terminating line feed or carriage return),
152 calling \fBbeep\fP(3X).
153 If
154 .I n
155 is negative,
156 .B \%wgetn_wstr
157 reads up to
158 .I LINE_MAX
159 characters
160 (see
161 .IR sysconf (3)).
162 .PP
163 \fB\%ncurses\fP(3X) describes the variants of these functions.
164 .SH RETURN VALUE
165 These functions return
166 .B OK
167 on success and
168 .B ERR
169 on failure.
170 .PP
171 In
172 .IR \%ncurses ,
173 these functions fail if
174 .bP
175 the
176 .I curses
177 screen has not been initialized,
178 .bP
179 (for functions taking a
180 .I \%WINDOW
181 pointer argument)
182 .I win
183 is a null pointer,
184 .bP
185 .I str
186 is a null pointer,
187 or
188 .bP
189 an internal \fB\%wgetch\fP(3X) call fails.
190 .PP
191 Further,
192 in
193 .IR \%ncurses ","
194 these functions return
195 .B \%KEY_RESIZE
196 if a
197 .I \%SIGWINCH
198 event interrupts the function.
199 .PP
200 Functions prefixed with \*(``mv\*('' first perform cursor movement and
201 fail if the position
202 .RI ( y ,
203 .IR x )
204 is outside the window boundaries.
205 .SH NOTES
206 All of these functions except
207 .B \%wgetnstr
208 may be implemented as macros.
209 .PP
210 Reading input that overruns the buffer pointed to by
211 .I str
212 causes undefined results.
213 Use the
214 .BR n -infixed
215 functions,
216 and allocate sufficient storage for
217 .I str
218 \(em at least
219 .IR n +1
220 times
221 .BR sizeof(char) "."
222 .PP
223 While these functions conceptually implement
224 a series of calls to
225 .BR \%wgetch ","
226 they also temporarily change properties of the
227 .I curses
228 screen to permit simple editing of the input buffer.
229 Each function saves the screen's state,
230 calls \fBnl\fP(3X),
231 and,
232 if the screen was in canonical (\*(``cooked\*('') mode,
233 \fB\%cbreak\fP(3X).
234 Before returning,
235 it restores the saved screen state.
236 Other implementations differ in detail,
237 affecting which control characters they can accept in the buffer;
238 see section \*(``PORTABILITY\*('' below.
239 .SH EXTENSIONS
240 .BR \%getnstr ","
241 .BR \%wgetnstr ","
242 .BR \%mvgetnstr ","
243 and
244 .BR \%mvwgetnstr "'s"
245 handing of negative
246 .I n
247 values is an
248 .I \%ncurses
249 extension.
250 .PP
251 The return value
252 .B \%KEY_RESIZE
253 is an
254 .I \%ncurses
255 extension.
256 .SH PORTABILITY
257 Applications employing
258 .I \%ncurses
259 extensions should condition their use on the visibility of the
260 .B \%NCURSES_VERSION
261 preprocessor macro.
262 .PP
263 X/Open Curses Issue\ 4 describes these functions.
264 It specifies no error conditions for them,
265 but indicates that
266 .I \%wgetnstr
267 and its variants read
268 \*(``the entire multi-byte sequence associated with a character\*(''
269 and \*(``fail\*('' if
270 .I n
271 and
272 .I str
273 together do not describe a buffer
274 \*(``large enough to contain any complete characters\*(''.
275 In
276 .IR \%ncurses ","
277 however,
278 .I \%wgetch
279 reads only single-byte characters,
280 so this scenario does not arise.
281 .\" You can pass ncurses wgetnstr n=0 and it will beep at you with each
282 .\" key stroke.
283 .PP
284 SVr4 describes a successful return value only as
285 \*(``an integer value other than
286 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 495
287 .PP
288 SVr3 and early SVr4
289 .I curses
290 implementations did not reject function keys;
291 the SVr4 documentation asserted that,
292 like the screen's erase and kill characters,
293 they were
294 .PP
295 .RS
296 interpreted,
297 as well as any special keys
298 (such as function keys,
299 \*(``home\*('' key,
300 \*(``clear\*('' key,
301 .IR etc. )
302 .\" SVID 4, vol. 3, p. 495
303 .RE
304 .PP
305 without further detail.
306 It lied.
307 The \*(``character\*('' value
308 appended to the string
309 by those implementations
310 was predictable but not useful \(em
311 being,
312 in fact,
313 the low-order eight bits of the key code's
314 .I KEY_
315 constant value.
316 (The same language,
317 unchanged except for styling,
318 survived into X/Open Curses Issue\ 4,
319 Version\ 2 \" p. 94 (PDF 114)
320 but disappeared from Issue\ 7.) \" p. 105 (PDF 119)
321 .PP
322 A draft of X/Open Curses Issue\ 5
323 (which never saw final release)
324 stated that these functions
325 \*(``read at most
326 .I n
327 bytes\*(''
328 but did not state whether the terminating null character
329 counted toward that limit.
330 X/Open Curses Issue\ 7 changed that to say they
331 \*(``read at most
332 .IR n \-1
333 bytes\*(''
334 to allow for the terminating null character.
335 As of 2018,
336 some implementations count it,
337 some do not.
338 .bP
339 .I \%ncurses
340 6.1 and
341 .I \%PDCurses
342 do not count the null character toward the limit,
343 while Solaris and NetBSD
344 .I curses
345 do.
346 .bP
347 Solaris
348 .I xcurses
349 offers both behaviors:
350 its wide-character
351 .I \%wgetn_wstr
352 reserves room for a wide null character,
353 but its non-wide
354 .I \%wgetnstr
355 does not consistently count a null character toward the limit.
356 .PP
357 X/Open Curses does not specify what happens if the length
358 .I n
359 is negative.
360 .bP
361 .I \%ncurses
362 6.2 uses
363 .I LINE_MAX
364 or a larger (system-dependent) value
365 provided by \fI\%sysconf\fP(3).
366 If neither
367 .I LINE_MAX
368 nor
369 .I \%sysconf
370 is available,
371 .I \%ncurses
372 uses the POSIX minimum value for
373 .I LINE_MAX
374 (2048). \" _POSIX2_LINE_MAX
375 In either case,
376 it reserves a byte for the terminating null character.
377 .bP
378 In SVr4
379 .IR curses ","
380 a negative
381 .I n
382 tells
383 .I \%wgetnstr
384 to assume that the caller's buffer
385 is large enough to hold the result;
386 that is,
387 the function then acts like
388 .IR \%wgetstr "."
389 X/Open Curses does not mention this behavior
390 (or anything related to nonpositive
391 .I n
392 values),
393 however most
394 .I curses
395 libraries implement it.
396 Most implementations nevertheless enforce an upper limit
397 on the count of bytes they write to the destination buffer
398 .IR str "."
399 .bP
400 BSD
401 .I curses
402 lacked
403 .IR \%wgetnstr ","
404 and its
405 .I \%wgetstr
406 wrote to
407 .I str
408 unboundedly,
409 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
410 .\" libcurses/getstr.c
411 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/src/lib/\
412 .\" libcurses/getstr.c
413 as did that in SVr2.
414 .\" https://github.com/ryanwoodsmall/oldsysv/blob/master/sysvr2-vax/\
415 .\" src/lib/libcurses/screen/getstr.c
416 .bP
417 .IR PDCurses ","
418 and
419 SVr3 and later,
420 .\" https://github.com/ryanwoodsmall/oldsysv/blob/master/\
421 .\" sysvr3/301/usr/src/lib/libcurses/screen/getstr.c#L21
422 .\" sysvr3/31/usr/src/lib/libcurses/screen/wgetstr.c#L10
423 .\" sysvr4/svr4/lib/xlibcurses/screen/wgetstr.c#L12
424 and
425 Solaris
426 .I curses
427 limit both functions to writing 256 bytes.
428 Other System\ V-based platforms likely use the same limit.
429 .bP
430 Solaris
431 .I xcurses
432 limits the write to
433 .I LINE_MAX
434 bytes
435 (see
436 .IR sysconf (3)).
437 .bP
438 NetBSD 7
439 .I curses
440 imposes no particular limit on the length of the write,
441 but does validate
442 .I n
443 to ensure that it is greater than zero.
444 A comment in NetBSD's source code asserts that SUSv2 specifies this.
445 .PP
446 Implementations vary in their handling of input control characters.
447 .bP
448 While they may enable the screen's echo option,
449 some do not take it out of raw mode,
450 and may take cbreak mode into account
451 when deciding whether to handle echoing within
452 .I \%wgetnstr
453 or to rely on it as a side effect of calling
454 .IR \%wgetch "."
455 .bP
456 Originally,
457 .IR \%ncurses ","
458 like its progenitor
459 .IR \%pcurses ","
460 had its
461 .I \%wgetnstr
462 call
463 .I \%noraw
464 and
465 .I \%cbreak
466 before accepting input.
467 That may have been done to make function keys work;
468 it is not necessary with modern
469 .IR \%ncurses "."
470 .IP
471 Since 1995,
472 .I \%ncurses
473 has provided handlers for
474 .I SIGINTR
475 and
476 .I SIGQUIT
477 events,
478 which are typically generated at the keyboard with
479 .B \*^C
480 and
481 .B \*^\e
482 respectively.
483 In cbreak mode,
484 those handlers catch a signal and stop the program,
485 whereas other implementations write those characters into the buffer.
486 .bP
487 Starting with
488 .I \%ncurses
489 6.3 (2021),
490 .I \%wgetnstr
491 preserves raw mode if the screen was already in that state,
492 allowing one to enter the characters the terminal interprets
493 as interrupt and quit events
494 into the buffer,
495 for better compatibility with SVr4
496 .IR curses "."
497 .SH HISTORY
498 4BSD (1980)
499 introduced
500 .I \%wgetstr
501 along with its variants.
502 .PP
503 SVr3.1 (1987)
504 added
505 .IR \%wgetnstr ","
506 but none of its variants.
507 .PP
508 X/Open Curses Issue\ 4 (1995)
509 specified
510 .IR \%getnstr ","
511 .IR \%mvgetnstr ","
512 and
513 .IR \%mvwgetnstr "."
514 .SH SEE ALSO
515 \fB\%curs_get_wstr\fP(3X) describes comparable functions of the
516 .I \%ncurses
517 library in its wide-character configuration
518 .RI \%( ncursesw ).
519 .PP
520 \fB\%curses\fP(3X),
521 \fB\%curs_addch\fP(3X),
522 \fB\%curs_getch\fP(3X),
523 \fB\%curs_inopts\fP(3X), \" echo(), keypad()
524 \fB\%curs_termattrs\fP(3X), \" erasechar(), killchar()