curs_getstr(3X)                                   curs_getstr(3X)

NAME
       getstr,  wgetstr,  mvgetstr,  mvwgetstr, wgetnstr - accept
       character strings from curses terminal keyboard

SYNOPSIS
       #include <curses.h>

       int getstr(char *str);
       int getnstr(char *str, int n);
       int wgetstr(WINDOW *win, char *str);
       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 wgetnstr(WINDOW *win, 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
       pointed to by the character pointer str.

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

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.

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 specifies that they return ERR  on  failure,  but
       the  single  error  condition  EOVERFLOW  associated  with
       extended-level conformance is not yet  returned  (the  XSI
       curses  support  for multi-byte characters is not yet pre-
       sent).

       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 pre-
       sent but not documented in SVr4.

SEE ALSO
       curses(3X), curs_getch(3X).

                                                                1