man/curs_getstr.3x

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