# 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

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

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

           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.

           This  implementation  provides an extension as well.  If a
           SIGWINCH interrupts the function, it will  return  KEY_RE-
           SIZE rather than OK or ERR.

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

## SEE ALSO

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

                                                            curs_getstr(3x)