# curs_instr 3x 2024-04-20 ncurses 6.5 Library calls

    curs_instr(3x)                   Library calls                  curs_instr(3x)

## NAME

           instr,  innstr, winstr, winnstr, mvinstr, mvinnstr, mvwinstr, mvwinnstr
           - get a string from a curses window

## SYNOPSIS

           #include <curses.h>

           int instr(char *str);
           int innstr(char *str, int n);
           int winstr(WINDOW *win, char *str);
           int winnstr(WINDOW *win, char *str, int n);

           int mvinstr(int y, int x, char *str);
           int mvinnstr(int y, int x, char *str, int n);
           int mvwinstr(WINDOW *win, int y, int x, char *str);
           int mvwinnstr(WINDOW *win, int y, int x, char *str, int n);

## DESCRIPTION

           These routines return a string of characters in str,  starting  at  the
           current  cursor  position in the named window.  Attributes are stripped
           from the characters.

           The four functions with  n  as  the  last  argument  return  a  leading
           substring  at  most  n characters long (exclusive of the trailing NUL).
           Transfer stops at the end of the current line,  or  when  n  characters
           have been stored at the location referenced by str.

## RETURN VALUE

           All  of  the  functions  return  ERR  upon  failure,  or  the number of
           characters actually read into the string.

           X/Open Curses defines no error conditions.  This implementation returns
           an error

           o   if the win parameter is null or

           o   if the chstr parameter is null.

           Functions  prefixed with "mv" first perform cursor movement and fail if
           the position (y, x) is outside the window boundaries.

## NOTES

           All routines except winnstr may be macros.

           Reading a line that overflows the array pointed to by str  with  instr,
           mvinstr,  mvwinstr  or winstr causes undefined results.  Therefore, the
           use of innstr, mvinnstr, mvwinnstr, or winnstr is recommended.

## PORTABILITY

           SVr4 does not document whether a length limit includes or excludes  the
           trailing NUL.

           The ncurses library extends the X/Open Curses description by allowing a
           negative value for n.  In this case, the functions  return  the  string
           ending at the right margin.

## SEE ALSO

           curs_ins_wstr(3x) describes comparable functions of the ncurses library
           in its wide-character configuration (ncursesw).

           curses(3x), curs_inch(3x), curs_inchstr(3x)

    ncurses 6.5                       2024-04-20                    curs_instr(3x)