X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_getstr.3x.html;h=3460ac7f3ad7adb78e0a2ae772dd4e43e86c1626;hp=9116840248a0f7d4c201cfc6925c01302da6fece;hb=81304798ee736c467839c779c9ca5dca48db7bea;hpb=cef50b3afcd58166f3541b701c97bce538844c76 diff --git a/doc/html/man/curs_getstr.3x.html b/doc/html/man/curs_getstr.3x.html index 91168402..3460ac7f 100644 --- a/doc/html/man/curs_getstr.3x.html +++ b/doc/html/man/curs_getstr.3x.html @@ -1,7 +1,7 @@ - - + + + curs_getstr 3x - + -

curs_getstr 3x

-
+

curs_getstr 3x

-
-curs_getstr(3x)                                         curs_getstr(3x)
+curs_getstr(3x)                                                curs_getstr(3x)
 
 
 
 
-
-

NAME

-       getstr, getnstr, wgetstr, wgetnstr, mvgetstr, mvgetnstr,
-       mvwgetstr, mvwgetnstr - accept character strings from
-       curses terminal keyboard
+

NAME

+       getstr, getnstr, wgetstr, wgetnstr, mvgetstr, mvgetnstr, mvwgetstr,
+       mvwgetnstr - accept character strings from curses terminal keyboard
 
 
-
-

SYNOPSIS

+

SYNOPSIS

        #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);
 
-
-

DESCRIPTION

-       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).
 
+

DESCRIPTION

+       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.
 
-
-

RETURN VALUE

-       All routines return the integer ERR upon failure and an OK
-       (SVr4 specifies only "an integer value  other  than  ERR")
-       upon successful completion.
+       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
+       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).
+
+
+

RETURN VALUE

+       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.
 
-       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 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 interrupts the function, it will  return  KEY_RE-
-       SIZE 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 move-
-       ment using wmove, and return an error if the  position  is
-       outside the window, or if the window pointer is null.
+       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.
 
 
-
-

NOTES

+

NOTES

        Note that getstr, mvgetstr, and mvwgetstr may be macros.
 
 
-
-

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 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.
+

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.
 
+       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).
 
-
-

SEE ALSO

-       curses(3x), curs_getch(3x), curs_variables(3x).
+       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.
+
+       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.
+
+
+

SEE ALSO

+       curses(3x), curs_getch(3x), curs_termattrs(3x), curs_variables(3x).
 
 
 
-                                                        curs_getstr(3x)
+                                                               curs_getstr(3x)
 
-
-
-Man(1) output converted with -man2html -
+