- 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 point-
- ed to by the character pointer str.
+ 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
+
+ o discards function key inputs other than those treated as the erase
+ character, calling beep(3x).
+
+ 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.
+
+ If the screen's echo option is enabled (see echo(3x)), wgetstr updates
+ win with wechochar(3x). Further,
- wgetnstr reads at most n characters, thus preventing a
- possible overflow of the input buffer. Any attempt to en-
- ter more characters (other than the terminating newline or
- carriage return) causes a beep. Function keys also cause
- a beep and are ignored. The getnstr function reads from
- the stdscr default window.
+ o the erase character and its function key synonyms move the cursor
+ to the left, and
- 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.
+ o the kill character returns the cursor to where it was located when
+ wgetstr was called.
- Characters input are echoed only if echo is currently on.
- In that case, backspace is echoed as deletion of the pre-
- vious character (typically a left motion).
+ 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 specifies only "an integer value other than ERR")
- upon successful completion.
+ These functions return OK on success and ERR on failure.
+
+ In ncurses, they return ERR if
- X/Open defines no error conditions.
+ owin is NULL, or
- In this implementation, these functions return an error if
- the window pointer is null, or if its timeout expires
- without having any data.
+ o if an internal wgetch call fails.
- This implementation provides an extension as well. If a
- SIGWINCH interrupts the function, it will return KEY_RE-
- SIZE rather than OK or ERR.
+ Further, in ncurses, these functions return KEY_RESIZE if a SIGWINCH
+ event interrupts the function.
- Functions with a "mv" prefix first perform a cursor move-
- ment using wmove, and return an error if the position is
- outside the window, or if the window pointer is null.
+ 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 im-
- plementation returns ERR if the window pointer is null, or
- if the lower-level wgetch 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.)
- SVr3 and early SVr4 curses implementations did not reject
- function keys; the SVr4.0 documentation claimed that "spe-
- cial keys" (such as function keys, "home" key, "clear"
- key, etc.) are "interpreted", without 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).
+ 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.)
- The functions getnstr, mvgetnstr, and mvwgetnstr were
- present but not documented in SVr4.
+ 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.
+
+ oncurses 6.1 and PDCurses do not count the null character toward the
+ limit, while Solaris and NetBSD curses do.
+
+ 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.
+
+ 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 BSD curses lacked wgetnstr, and its wgetstr wrote to str
+ unboundedly, as did that in SVr2.
+
+ 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.
+
+ o Solaris xcurses limits the write to LINE_MAX bytes.
+
+ 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.
+
+ 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.
+
+ 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.
+
+ Implementations vary in their handling of input control characters.
+
+ 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 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.