X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_getstr.3x.html;h=01c347fbd68abee8ddb9394b6ff174be811c3e88;hb=a47b9e53836434777854387fa6f09f2137ec2111;hp=12da6a2b9fc3f27fba81d0f0949009f956f595fc;hpb=d79ff7b4d5f5ac63e7d9d7e76706d95a1ddb243c;p=ncurses.git diff --git a/doc/html/man/curs_getstr.3x.html b/doc/html/man/curs_getstr.3x.html index 12da6a2b..01c347fb 100644 --- a/doc/html/man/curs_getstr.3x.html +++ b/doc/html/man/curs_getstr.3x.html @@ -27,22 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_getstr.3x,v 1.40 2023/07/01 15:43:20 tom Exp @ - * X/Open says also until EOf - * X/Open says then an EOS is added to the result - * X/Open doesn't mention n<0 + * @Id: curs_getstr.3x,v 1.42 2023/08/05 12:14:30 tom Exp @ -->
-curs_getstr(3x) Library calls curs_getstr(3x) @@ -69,44 +66,68 @@
- 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 function wgetnstr is equivalent to a series of calls to wgetch(3x), + until a newline or carriage return terminates the series: - The getnstr function reads from the stdscr default window. The other - functions, such as wgetnstr, read from the window given as a parameter. + o The terminating character is not included in the returned string. - 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. + 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 + 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. + 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- + 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 routines return the integer ERR upon failure and an OK (SVr4 speci- - fies only "an integer value other than ERR") upon successful comple- - tion. + 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 + + o if the window pointer is null, + + o if its timeout expires without having any data, or + + o if the associated call to wgetch failed. This implementation provides an extension as well. If a SIGWINCH in- terrupts the function, it will return KEY_RESIZE rather than OK or ERR. @@ -116,79 +137,76 @@ the window pointer is null. -
- Note that getstr, mvgetstr, and mvwgetstr may be macros. +
+ These functions are described in The Single Unix Specification, Version + 2. No error conditions are defined. + This implementation returns ERR if the window pointer is null, or if + the lower-level wgetch(3x) call returns an ERR. -
- 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. - - 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 + 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 + 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 + 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 do, some do not count it: + some implementations count it, some do not: - 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 xcurses provides both: its wide-character wget_nstr re- + 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 + 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. + 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 + 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 + 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 - 2048 byte limit). In either case, it reserves a byte for the ter- + 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 + 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 + 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 + 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. @@ -196,7 +214,7 @@ 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 + 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. @@ -204,13 +222,13 @@ 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 + 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- + and cbreak for better compatibility with SVr4-curses, e.g., allow- ing one to enter a ^C into the buffer. @@ -219,15 +237,15 @@ -ncurses 6.4 2023-07-01 curs_getstr(3x) +ncurses 6.4 2023-08-05 curs_getstr(3x)