X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_getstr.3x.html;h=ca39dbf3beecbf3c7ca664c89d757aae418fff7c;hp=4c9de8839d15a567d18ad1a003153984ad57f018;hb=c0f109a299a82a33c16bd7af942a12ce9aefaaf0;hpb=2560bc3dae7f4919060c02c91a593566c908091c diff --git a/doc/html/man/curs_getstr.3x.html b/doc/html/man/curs_getstr.3x.html index 4c9de883..ca39dbf3 100644 --- a/doc/html/man/curs_getstr.3x.html +++ b/doc/html/man/curs_getstr.3x.html @@ -1,6 +1,7 @@ - + curs_getstr 3x - + @@ -67,7 +71,7 @@ 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. + the area pointed to by the character pointer str, followed by a NUL. wgetnstr reads at most n characters, thus preventing a possible over- flow of the input buffer. Any attempt to enter more characters (other @@ -109,8 +113,8 @@

PORTABILITY

        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
@@ -122,6 +126,48 @@
        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 do, some do not count it:
+
+       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-
+           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.
+

SEE ALSO

        curses(3x), curs_getch(3x), curs_variables(3x).