X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;ds=inline;f=doc%2Fhtml%2Fman%2Fcurs_getstr.3x.html;h=3460ac7f3ad7adb78e0a2ae772dd4e43e86c1626;hb=81304798ee736c467839c779c9ca5dca48db7bea;hp=6979d654bd57553b7240894be4148534ea80dc9f;hpb=9f479192e3ca3413d235c66bf058f8cc63764898;p=ncurses.git diff --git a/doc/html/man/curs_getstr.3x.html b/doc/html/man/curs_getstr.3x.html index 6979d654..3460ac7f 100644 --- a/doc/html/man/curs_getstr.3x.html +++ b/doc/html/man/curs_getstr.3x.html @@ -37,70 +37,70 @@
--curs_getstr(3X) curs_getstr(3X) +curs_getstr(3x) 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> + #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 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 *win, int y, int x, 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 *win, int y, int x, char *str, int n);
- The function getstr is equivalent to a series of calls to getch, until + 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. + the area pointed to by the character pointer str, followed by a NUL. - The getnstr function reads from the stdscr default window. The other - functions, such as wgetnstr, read from the window given as a parameter. + The getnstr function reads from the stdscr default window. The other + functions, such as wgetnstr, read from the window given as a parameter. - getnstr reads at most n characters, thus preventing a possible overflow + getnstr reads at most n characters, thus preventing a possible overflow of the input buffer. Any attempt to enter more characters (other than the terminating newline or carriage return) causes a beep. Function keys also cause a beep and are ignored. - The user's erase and kill characters are interpreted: + The user's erase and kill characters are interpreted: - o The erase character (e.g., ^H) erases the character at the end of + o The erase character (e.g., ^H) erases the character at the end of the buffer, moving the cursor to the left. - If keypad mode is on for the window, KEY_LEFT and KEY_BACKSPACE are + 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 kill character (e.g., ^U) erases the entire buffer, leaving the + o The kill character (e.g., ^U) erases the entire buffer, leaving the cursor at the beginning of the buffer. - Characters input are echoed only if echo is currently on. In that + 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).
- All routines return the integer ERR upon failure and an OK (SVr4 speci- - fies only "an integer value other than ERR") upon successful comple- + 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. X/Open defines no error conditions. @@ -108,118 +108,118 @@ In this implementation, these functions return an error if the window pointer is null, or if its timeout expires without having any data. - This implementation provides an extension as well. If a SIGWINCH in- - terrupts the function, it will return KEY_RESIZE rather than OK or ERR. + 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 + wmove, and return an error if the position is outside the window, or if the window pointer is null.
- Note that getstr, mvgetstr, and mvwgetstr may be macros. + Note that getstr, mvgetstr, and mvwgetstr may be macros.
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. + any error conditions. This implementation returns ERR if the window + pointer is null, or if the lower-level wgetch(3x) call returns an ERR. 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- + 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). - The functions getnstr, mvgetnstr, and mvwgetnstr were present but not + 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 NUL is counted in + 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, + "read at most n-1 bytes" to allow for the terminating NUL. As of 2018, some implementations do, some do not count it: - o ncurses 6.1 and PDCurses do not count the NUL in the given limit, + o ncurses 6.1 and PDCurses do not count the NUL in the given limit, while - o Solaris SVr4 and NetBSD curses count the NUL as part of the limit. + o Solaris SVr4 and NetBSD curses count the NUL as part of the limit. - o Solaris xcurses provides both: its wide-character wget_nstr re- - serves a NUL, but its wgetnstr does not count the NUL consistently. + o Solaris xcurses provides both: its wide-character wget_nstr re- + serves a NUL, but its wgetnstr does not count the NUL consistently. - In SVr4 curses, a negative value of n tells wgetnstr to assume that the + 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 + 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 SVr4 curses and PDCurses limit the result to 255 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 Solaris xcurses limits the result to LINE_MAX bytes. + o Solaris xcurses limits the result to LINE_MAX bytes. - o NetBSD 7 assumes no particular limit for the result from wgetstr. - However, it limits the wgetnstr parameter n to ensure that it is + 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. A comment in NetBSD's source code states that this is specified in SUSv2. - o ncurses (before 6.2) assumes no particular limit for the result - from wgetstr, and treats the n parameter of wgetnstr like SVr4 + 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 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 + 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. - Although getnstr is equivalent to a series of calls to getch, it also + 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 getnstr saves the current value of the nl, echo, raw and cbreak - modes, and sets nl, noecho, noraw, and cbreak. + o getnstr saves the current value of the nl, echo, raw and cbreak + modes, and sets nl, noecho, noraw, and cbreak. - getnstr handles the echoing of characters, rather than relying on + getnstr handles the echoing of characters, rather than relying on the caller to set an appropriate mode. - o It also obtains the erase and kill characters from erasechar and - killchar, respectively. + o It also obtains the erase and kill characters from erasechar and + killchar, respectively. - o On return, getnstr restores the modes to their previous values. + o On return, getnstr restores the modes to their previous values. Other implementations differ in their treatment of special characters: - 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 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- + 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. Since 1995, ncurses has provided signal handlers for INTR and QUIT - (e.g., ^C or ^\). With the noraw and cbreak settings, those may + (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. - 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. + 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.
- curses(3X), curs_getch(3X), curs_termattrs(3X), curs_variables(3X). + curses(3x), curs_getch(3x), curs_termattrs(3x), curs_variables(3x). - curs_getstr(3X) + curs_getstr(3x)