X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_getstr.3x.html;h=01c347fbd68abee8ddb9394b6ff174be811c3e88;hb=a47b9e53836434777854387fa6f09f2137ec2111;hp=206b64e1d6151005e6781c542368ae8757e25a9d;hpb=027d0c57c4c4d6690e8d8727888d3282dbe9aa86;p=ncurses.git diff --git a/doc/html/man/curs_getstr.3x.html b/doc/html/man/curs_getstr.3x.html index 206b64e1..01c347fb 100644 --- a/doc/html/man/curs_getstr.3x.html +++ b/doc/html/man/curs_getstr.3x.html @@ -1,6 +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 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); --
- 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). +
+ The function wgetnstr is equivalent to a series of calls to wgetch(3x), + until a newline or carriage return terminates the series: --
- All routines return the integer ERR upon failure and an OK - (SVr4 specifies only "an integer value other than ERR") - upon successful completion. + o The terminating character is not included in the returned string. + + o In all instances, the end of the string is terminated by a NUL. + + o The function stores the result in the area pointed to by the str + parameter. + + o The function 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: + + 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 + both considered equivalent to the user's erase character. + + 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 + case, backspace is echoed as deletion of the previous character (typi- + cally a left motion). + + 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. + + +
+ Any of these functions other than wgetnstr may be macros. + + 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. + + +
+ 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. X/Open defines no error conditions. - In this implementation, these functions return an error if - the window pointer is null, or if its timeout expires - without having any data. + In this implementation, these functions return an error - 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 if the window pointer is null, - 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 if its timeout expires without having any data, or + o if the associated call to wgetch failed. --
- Note that getstr, mvgetstr, and mvwgetstr may be macros. + 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. --
- 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. +
+ These functions are described in The Single Unix Specification, Version + 2. No error conditions are defined. --
- curses(3x), curs_getch(3x), curs_variables(3x). + 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- + 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 + 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 + 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: + o ncurses 6.1 and PDCurses do not count the NUL in the given limit, + while - curs_getstr(3x) + 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. + + 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 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 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 + 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 + 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 + 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. + + 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 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 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 + 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. + + +
+ curses(3x), curs_getch(3x), curs_termattrs(3x), curs_variables(3x). + + + +ncurses 6.4 2023-08-05 curs_getstr(3x)