X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_getstr.3x.html;h=d157fecf8bacb644515a15578f9a9ffa1f032dd9;hb=HEAD;hp=f7cffded9a17c78d83147ad30d2b11faa4a0bf26;hpb=761e4f0825b330e970558e82a4bd638383914429;p=ncurses.git diff --git a/doc/html/man/curs_getstr.3x.html b/doc/html/man/curs_getstr.3x.html index f7cffded..226514a4 100644 --- a/doc/html/man/curs_getstr.3x.html +++ b/doc/html/man/curs_getstr.3x.html @@ -1,7 +1,7 @@ - - +
-- -curs_getstr(3x) curs_getstr(3x) +curs_getstr(3x) Library calls curs_getstr(3x) --
- getstr, getnstr, wgetstr, wgetnstr, mvgetstr, mvgetnstr, - mvwgetstr, mvwgetnstr - accept character strings from - curses terminal keyboard +
+ getstr, getnstr, wgetstr, wgetnstr, mvgetstr, mvgetnstr, mvwgetstr, + mvwgetnstr - accept character strings from curses terminal keyboard --
+
#include <curses.h> - int getstr(char *str); - int getnstr(char *str, int n); - int wgetstr(WINDOW *win, char *str); - int wgetnstr(WINDOW *win, char *str, int n); - int mvgetstr(int y, int x, char *str); - int mvwgetstr(WINDOW *win, int y, int x, char *str); - int mvgetnstr(int y, int x, char *str, int n); - int mvwgetnstr(WINDOW *, int y, int x, char *str, int n); + int getstr(char * str); + int wgetstr(WINDOW * win, char * str); + int mvgetstr(int y, int x, char * str); + int mvwgetstr(WINDOW * win, int y, int x, char * str); + int getnstr(char * str, int n); + int wgetnstr(WINDOW * win, char * str, int n); + int mvgetnstr(int y, int x, char * str, int n); + int mvwgetnstr(WINDOW * win, int y, int x, char * str, int n); --
- 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. - - 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. - - 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. - - 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). +
+ 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 --
- All routines return the integer ERR upon failure and an OK - (SVr4 specifies only "an integer value other than ERR") - upon successful completion. + o does not copy the terminating character to str; - X/Open defines no error conditions. + o always terminates str with a null character; - In this implementation, these functions return an error if - the window pointer is null, or if its timeout expires - without having any data. + o interprets the screen's erase and kill characters (see + erasechar(3x) and killchar(3x)); - This implementation provides an extension as well. If a - SIGWINCH interrupts the function, it will return KEY_RE- - SIZE rather than OK or ERR. + o recognizes function keys only if the screen's keypad option is + enabled (see keypad(3x)); - 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. + 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). --
- Note that getstr, mvgetstr, and mvwgetstr may be macros. + 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, --
- 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. - - 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). - - The functions getnstr, mvgetnstr, and mvwgetnstr were - present but not documented in SVr4. + 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. --
- curses(3x), curs_getch(3x), curs_variables(3x). + 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. + + +
+ These functions return OK on success and ERR on failure. + + In ncurses, they return ERR if + + o win is NULL, or + + o if an internal wgetch call fails. + + 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. + + +
+ 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. + + +
+ The return value KEY_RESIZE is an ncurses extension. + + +
+ 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.) + + 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. + + o ncurses 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. + + o PDCurses, 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. + + o ncurses 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 ncurses 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. + + +
+ curs_get_wstr(3x) describes comparable functions of the ncurses library + in its wide-character configuration (ncursesw). + + curses(3x), curs_addch(3x), curs_getch(3x), curs_inopts(3x), + curs_termattrs(3x), - curs_getstr(3x) +ncurses 6.5 2024-06-22 curs_getstr(3x)-