# curs_getstr 3x

## NAME

           getstr,  getnstr,  wgetstr, wgetnstr, mvgetstr, mvgetnstr,
           mvwgetstr, mvwgetnstr  -  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 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);

## 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 multibyte 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).