Debian Codegraph @

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