- The function getstr is equivalent to a series of calls to getch, until
- a newline or carriage return is received (the terminating character is
- not included in the returned string). The resulting value is placed in
- the area pointed to by the character pointer str, followed by a NUL.
+ wgetstr populates a user-supplied string buffer str by repeatedly
+ calling wgetch(3x) with the win argument until a line feed or carriage
+ return character is input. The function
+
+ o does not copy the terminating character to str;
+
+ o always terminates str with a null character;
+
+ o interprets the screen's erase and kill characters (see
+ erasechar(3x) and killchar(3x));
+
+ o recognizes function keys only if the screen's keypad option is
+ enabled (see keypad(3x));
+
+ o treats the function keys KEY_LEFT and KEY_BACKSPACE the same as the
+ erase character; and
- wgetnstr reads at most n characters, thus preventing a possible over-
- flow of the input buffer. Any attempt to enter more characters (other
- than the terminating newline or carriage return) causes a beep. Func-
- tion keys also cause a beep and are ignored. The getnstr function
- reads from the stdscr default window.
+ o discards function key inputs other than those treated as the erase
+ character, calling beep(3x).
- The user's erase and kill characters are interpreted. If keypad mode
- is on for the window, KEY_LEFT and KEY_BACKSPACE are both considered
- equivalent to the user's kill character.
+ The erase character replaces the character at the end of the buffer
+ with a null character, while the kill character does the same for the
+ entire buffer.
- Characters input are echoed only if echo is currently on. In that
- case, backspace is echoed as deletion of the previous character (typi-
- cally a left motion).
+ If the screen's echo option is enabled (see echo(3x)), wgetstr updates
+ win with wechochar(3x). Further,
+
+ o the erase character and its function key synonyms move the cursor
+ to the left, and
+
+ o the kill character returns the cursor to where it was located when
+ wgetstr was called.
+
+ wgetnstr is similar, but reads at most n characters, aiding the
+ application to avoid overrunning the buffer to which str points. An
+ attempt to input more than n characters (other than the terminating
+ line feed or carriage return) is ignored with a beep.
+
+ ncurses(3x) describes the variants of these functions.
- All routines return the integer ERR upon failure and an OK (SVr4 speci-
- fies only "an integer value other than ERR") upon successful comple-
- tion.
+ These functions return OK on success and ERR on failure.
- X/Open defines no error conditions.
+ In ncurses, they return ERR if
- In this implementation, these functions return an error if the window
- pointer is null, or if its timeout expires without having any data.
+ owin is NULL, or
- This implementation provides an extension as well. If a SIGWINCH in-
- terrupts the function, it will return KEY_RESIZE rather than OK or ERR.
+ o if an internal wgetch call fails.
- Functions with a "mv" prefix first perform a cursor movement using
- wmove, and return an error if the position is outside the window, or if
- the window pointer is null.
+ Further, in ncurses, these functions return KEY_RESIZE if a SIGWINCH
+ event interrupts the function.
+
+ Functions prefixed with "mv" first perform cursor movement and fail if
+ the position (y, x) is outside the window boundaries.
- Note that getstr, mvgetstr, and mvwgetstr may be macros.
+ All of these functions except wgetnstr may be implemented as macros.
+
+ Use of getstr, mvgetstr, mvwgetstr, or wgetstr to read input that
+ overruns the buffer pointed to by str causes undefined results. Use
+ their n-infixed counterpart functions instead.
+
+ While wgetnstr is conceptually a series of calls to wgetch, it also
+ temporarily changes properties of the curses screen to permit simple
+ editing of the input buffer. It saves the screen's state and then
+ calls nl(3x) and, if the screen was in normal ("cooked") mode,
+ cbreak(3x). Before returning, it restores the saved screen state.
+ Other implementations differ in detail, affecting which control
+ characters they can accept in the buffer; see section "PORTABILITY"
+ below.
+
+
+
- These functions are described in the XSI Curses standard, Issue 4.
- They read single-byte characters only. The standard does not define
- any error conditions. This implementation returns ERR if the window
- pointer is null, or if the lower-level wgetch(3x) call returns an ERR.
+ Applications employing ncurses extensions should condition their use on
+ the visibility of the NCURSES_VERSION preprocessor macro.
+
+ X/Open Curses Issue 4 describes these functions. It specifies no error
+ conditions for them, but indicates that wgetnstr and its variants read
+ "the entire multi-byte sequence associated with a character" and "fail"
+ if n and str together do not describe a buffer "large enough to contain
+ any complete characters". In ncurses, however, wgetch reads only
+ single-byte characters, so this scenario does not arise.
+
+ SVr4 curses describes a successful return value only as "an integer
+ value other than ERR".
+
+ SVr3 and early SVr4 curses implementations did not reject function
+ keys; the SVr4 documentation asserted that, like the screen's erase and
+ kill characters, they were
+
+ interpreted, as well as any special keys (such as function keys,
+ "home" key, "clear" key, etc.)
+
+ without further detail. It lied. In fact, the "character" value
+ appended to the string by those implementations was predictable but not
+ useful -- being, in fact, the low-order eight bits of the key code's
+ KEY_ constant value. (The same language, unchanged except for styling,
+ survived into X/Open Curses Issue 4, but disappeared from Issue 7.)
- SVr3 and early SVr4 curses implementations did not reject function
- keys; the SVr4.0 documentation claimed that "special keys" (such as
- function keys, "home" key, "clear" key, etc.) are "interpreted", with-
- out giving details. It lied. In fact, the "character" value appended
- to the string by those implementations was predictable but not useful
- (being, in fact, the low-order eight bits of the key's KEY_ value).
+ X/Open Curses Issue 5 (2007) stated that these functions "read at most
+ n bytes" but did not state whether the terminating null character
+ counted toward that limit. X/Open Curses Issue 7 (2009) changed that
+ to say they "read at most n-1 bytes" to allow for the terminating null
+ character. As of 2018, some implementations count it, some do not.
- The functions getnstr, mvgetnstr, and mvwgetnstr were present but not
- documented in SVr4.
+ oncurses 6.1 and PDCurses do not count the null character toward the
+ limit, while Solaris and NetBSD curses do.
- X/Open Curses issue 5 (2007) stated that these functions "read at most
- n bytes" but did not state whether the terminating NUL is counted in
- that limit. X/Open Curses issue 7 (2009) changed that to say they
- "read at most n-1 bytes" to allow for the terminating NUL. As of 2018,
- some implementations do, some do not count it:
+ o Solaris xcurses offers both behaviors: its wide-character
+ wgetn_wstr reserves room for a wide null character, but its non-
+ wide wgetnstr does not consistently count a null character toward
+ the limit.
- o ncurses 6.1 and PDCurses do not count the NUL in the given limit,
- while
+ In SVr4 curses, a negative n tells wgetnstr to assume that the caller's
+ buffer is large enough to hold the result; that is, the function then
+ acts like wgetstr. X/Open Curses does not mention this behavior (or
+ anything related to nonpositive n values), however most curses
+ libraries implement it. Most implementations nevertheless enforce an
+ upper limit on the count of bytes they write to the destination buffer
+ str.
- o Solaris SVr4 and NetBSD curses count the NUL as part of the limit.
+ o BSD curses lacked wgetnstr, and its wgetstr wrote to str
+ unboundedly, as did that in SVr2.
- o Solaris xcurses provides both: its wide-character wget_nstr re-
- serves a NUL, but its wgetnstr does not count the NUL consistently.
+ oPDCurses, and SVr3.1, SVr4, and Solaris curses limit both functions
+ to writing 256 bytes. Other System V-based platforms likely use
+ the same limit.
- In SVr4 curses, a negative value of n tells wgetnstr to assume that the
- caller's buffer is large enough to hold the result, i.e., to act like
- wgetstr. X/Open Curses does not mention this (or anything related to
- negative or zero values of n), however most implementations use the
- feature, with different limits:
+ o Solaris xcurses limits the write to LINE_MAX bytes.
- o Solaris SVr4 curses and PDCurses limit the result to 255 bytes.
- Other Unix systems than Solaris are likely to use the same limit.
+ o NetBSD 7 curses imposes no particular limit on the length of the
+ write, but does validate n to ensure that it is greater than zero.
+ A comment in NetBSD's source code asserts that SUSv2 specifies
+ this.
- o Solaris xcurses limits the result to LINE_MAX bytes.
+ oncurses prior to 6.2 (2020) imposes no limit on the length of the
+ write, and treats wgetnstr's n parameter as SVr4 curses does.
- o NetBSD 7 assumes no particular limit for the result from wgetstr.
- However, it limits the wgetnstr parameter n to ensure that it is
- greater than zero.
+ oncurses 6.2 uses LINE_MAX or a larger (system-dependent) value
+ provided by sysconf(3). If neither LINE_MAX nor sysconf is
+ available, ncurses uses the POSIX minimum value for LINE_MAX
+ (2048). In either case, it reserves a byte for the terminating
+ null character.
- A comment in NetBSD's source code states that this is specified in
- SUSv2.
+ Implementations vary in their handling of input control characters.
- o ncurses (before 6.2) assumes no particular limit for the result
- from wgetstr, and treats the n parameter of wgetnstr like SVr4
- curses.
+ o While they may enable the screen's echo option, some do not take it
+ out of raw mode, and may take cbreak mode into account when
+ deciding whether to handle echoing within wgetnstr or to rely on it
+ as a side effect of calling wgetch.
- o ncurses 6.2 uses LINE_MAX, or a larger (system-dependent) value
- which the sysconf function may provide. If neither LINE_MAX or
- sysconf is available, ncurses uses the POSIX value for LINE_MAX (a
- 2048 byte limit). In either case, it reserves a byte for the ter-
- minating NUL.
+ o Originally, ncurses, like its progenitor pcurses, had its wgetnstr
+ call noraw and cbreak before accepting input. That may have been
+ done to make function keys work; it is not necessary with modern
+ ncurses.
+
+ Since 1995, ncurses has provided handlers for SIGINTR and SIGQUIT
+ events, which are typically generated at the keyboard with ^C and
+ ^\ respectively. In cbreak mode, those handlers catch a signal and
+ stop the program, whereas other implementations write those
+ characters into the buffer.
+
+ o Starting with ncurses 6.3 (2021), wgetnstr preserves raw mode if
+ the screen was already in that state, allowing one to enter the
+ characters the terminal interprets as interrupt and quit events
+ into the buffer, for better compatibility with SVr4 curses.
+
+
+
+ 4BSD (1980) curses introduced wgetstr along with its variants.
+
+ SVr3.1 (1987) added wgetnstr, but none of its variants.
+
+ X/Open Curses Issue 4 (1995) specified getnstr, mvwgetnstr, and
+ mvgetnstr.