Debian Codegraph @

upstream/debian-unstable/man3/getstr.3ncurses

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