X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_getstr.3x.html;h=d157fecf8bacb644515a15578f9a9ffa1f032dd9;hb=HEAD;hp=32d1a2f49e11ceca11accf48ed162c8bb78b6cf9;hpb=f5aadfb8596c96e69ce2b772cd06626f2fba8ddc;p=ncurses.git diff --git a/doc/html/man/curs_getstr.3x.html b/doc/html/man/curs_getstr.3x.html index 32d1a2f4..226514a4 100644 --- a/doc/html/man/curs_getstr.3x.html +++ b/doc/html/man/curs_getstr.3x.html @@ -1,6 +1,6 @@
-curs_getstr(3x) Library calls curs_getstr(3x) @@ -47,206 +47,229 @@
- 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 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 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 *win, int y, int x, char *str, int n); + 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 wgetnstr is equivalent to a series of calls to wgetch(3x), - until a newline or carriage return terminates the series: + 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 The terminating character is not included in the returned string. + o does not copy the terminating character to str; - o In all instances, the end of the string is terminated by a NUL. + o always terminates str with a null character; - o The function stores the result in the area pointed to by the str - parameter. + o interprets the screen's erase and kill characters (see + erasechar(3x) and killchar(3x)); - o The function reads at most n characters, thus preventing a possible - overflow of the input buffer. + o recognizes function keys only if the screen's keypad option is + enabled (see keypad(3x)); - Any attempt to enter more characters (other than the terminating - newline or carriage return) causes a beep. + o treats the function keys KEY_LEFT and KEY_BACKSPACE the same as the + erase character; and - Function keys also cause a beep and are ignored. + 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: + 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. - o The erase character (e.g., ^H) erases the character at the end of - the buffer, moving the cursor to the left. + If the screen's echo option is enabled (see echo(3x)), wgetstr updates + win with wechochar(3x). Further, - If keypad mode is on for the window, KEY_LEFT and KEY_BACKSPACE are - both considered equivalent to the user's erase character. + o the erase character and its function key synonyms move the cursor + to the left, and - o The kill character (e.g., ^U) erases the entire buffer, leaving the - cursor at the beginning of the buffer. + 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 previous character (typi- - cally 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. - The getnstr, mvgetnstr, mvwgetnstr, and wgetnstr functions are identi- - cal to the getstr, mvgetstr, mvwgetstr, and wgetstr functions, respec- - tively, except that the *n* versions read at most n characters, letting - the application prevent overflow of the input buffer. + ncurses(3x) describes the variants of these functions. -
- Any of these functions other than wgetnstr may be macros. +
+ These functions return OK on success and ERR on failure. - Using getstr, mvgetstr, mvwgetstr, or wgetstr to read a line that over- - flows the array pointed to by str causes undefined results. The use of - getnstr, mvgetnstr, mvwgetnstr, or wgetnstr, respectively, is recom- - mended. + In ncurses, they return ERR if + o win is NULL, or -
- All of these functions return the integer OK upon successful comple- - tion. (SVr4 specifies only "an integer value other than ERR") If un- - successful, they return ERR. + o if an internal wgetch call fails. + + Further, in ncurses, these functions return KEY_RESIZE if a SIGWINCH + event interrupts the function. - X/Open defines no error conditions. + Functions prefixed with "mv" first perform cursor movement and fail if + the position (y, x) is outside the window boundaries. - In this implementation, these functions return an error - o if the window pointer is null, or +
+ All of these functions except wgetnstr may be implemented as macros. - o if its timeout expires without having any data. + 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. - o if the associated call to wgetch failed. + 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. - This implementation provides an extension as well. If a SIGWINCH in- - terrupts the function, it will return KEY_RESIZE rather than OK or ERR. - 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. +
+ The return value KEY_RESIZE is an ncurses extension.
- These functions are described in The Single Unix Specification, Version - 2. No error conditions are defined. + Applications employing ncurses extensions should condition their use on + the visibility of the NCURSES_VERSION preprocessor macro. - This implementation returns ERR if the window pointer is null, or if - the lower-level wgetch(3x) call returns an ERR. + 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. - 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). + SVr4 curses describes a successful return value only as "an integer + value other than ERR". - The functions getnstr, mvgetnstr, and mvwgetnstr were present but not - documented in SVr4. + 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 - 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 count it, some do not: + interpreted, as well as any special keys (such as function keys, + "home" key, "clear" key, etc.) - o ncurses 6.1 and PDCurses do not count the NUL in the given limit, - while + 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.) - o Solaris SVr4 and NetBSD curses count the NUL as part of the limit. + 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 Solaris xcurses provides both: its wide-character wget_nstr re- - serves a NUL, but its wgetnstr does not count the NUL consistently. + o ncurses 6.1 and PDCurses do not count the null character toward the + limit, while Solaris and NetBSD curses do. - 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 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 Solaris SVr4 curses and PDCurses limit the result to 255 bytes. - Other Unix systems than Solaris are likely to use the same 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 Solaris xcurses limits the result to LINE_MAX bytes. + o BSD curses lacked wgetnstr, and its wgetstr wrote to str + unboundedly, as did that in SVr2. - 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. + 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. - A comment in NetBSD's source code states that this is specified in - SUSv2. + o Solaris xcurses limits the write to LINE_MAX bytes. - 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 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 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 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. - Although getnstr is equivalent to a series of calls to getch, it also - makes changes to the curses modes to allow simple editing of the input - buffer: + 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. - o getnstr saves the current value of the nl, echo, raw and cbreak - modes, and sets nl, noecho, noraw, and cbreak. + Implementations vary in their handling of input control characters. - getnstr handles the echoing of characters, rather than relying on - the caller to set an appropriate mode. + 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 It also obtains the erase and kill characters from erasechar and - killchar, respectively. + 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. - o On return, getnstr restores the modes to their previous values. + 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. - Other implementations differ in their treatment of special characters: + 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. - o While they may set the echo mode, other implementations do not mod- - ify the raw mode, They may take the cbreak mode set by the caller - into account when deciding whether to handle echoing within getnstr - or as a side-effect of the getch calls. - o The original ncurses (as pcurses in 1986) set noraw and cbreak when - accepting input for getnstr. That may have been done to make func- - tion- and cursor-keys work; it is not necessary with ncurses. +
+ 4BSD (1980) curses introduced wgetstr along with its variants. - Since 1995, ncurses has provided signal handlers for INTR and QUIT - (e.g., ^C or ^\). With the noraw and cbreak settings, those may - catch a signal and stop the program, where other implementations - allow one to enter those characters in the buffer. + SVr3.1 (1987) added wgetnstr, but none of its variants. - o Starting in 2021 (ncurses 6.3), getnstr sets raw, rather than noraw - and cbreak for better compatibility with SVr4-curses, e.g., allow- - ing one to enter a ^C into the buffer. + X/Open Curses Issue 4 (1995) specified getnstr, mvwgetnstr, and + mvgetnstr.
- curses(3x), curs_getch(3x), curs_termattrs(3x), curs_variables(3x). + 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), -ncurses 6.4 2023-07-29 curs_getstr(3x) +ncurses 6.5 2024-06-22 curs_getstr(3x)