# curs_instr 3x 2025-02-01 ncurses 6.5 Library calls

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

## NAME

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

## SYNOPSIS

           #include <curses.h>

           int instr(char * str);
           int winstr(WINDOW * win, char * str);
           int mvinstr(int y, int x, char * str);
           int mvwinstr(WINDOW * win, int y, int x, char * str);

           int innstr(char * str, int n);
           int winnstr(WINDOW * win, char * str, int n);
           int mvinnstr(int y, int x, char * str, int n);
           int mvwinnstr(WINDOW * win, int y, int x, char * str,
                 int n);

## DESCRIPTION

           winstr extracts a string from a curses  window  win,  starting  at  the
           cursor  and  stopping  at  the  end  of the line, and stores it in str,
           terminating it with a null character and omitting  any  attributes  and
           color  pair  identifier  that  curses  associates  with each character.
           winnstr does the same, but copies at most n  characters  from  win.   A
           negative   n   implies  no  limit;  winnstr  then  works  like  winstr.
           ncurses(3x) describes the variants of these functions.

## RETURN VALUE

           These functions return the count of characters copied from win to  str,
           or ERR upon failure.

           In ncurses, they return ERR if

           o   win is NULL or

           o   str is NULL.

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

## NOTES

           All of these functions except winnstr may be implemented as macros.

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

## EXTENSIONS

           innstr, winnstr, mvinnstr, and mvwinnstr's  acceptance  of  negative  n
           values is an ncurses extension.

## PORTABILITY

           Applications employing ncurses extensions should condition their use on
           the visibility of the NCURSES_VERSION preprocessor macro.

           X/Open Curses Issue 4 describes these functions.  It specifies no error
           conditions for them.

           X/Open  Curses  Issues  4 and 7 both state that instr, winstr, mvinstr,
           and mvwinstr return OK rather than a character count.  This  is  likely
           an erratum.

           o   SVr3.1  and  SVr4  implemented  winstr as a wrapper around winnstr,
               returning the latter's return value.  X/Open Curses's specification
               thus  may  have  been  an editorial solecism copied from System V's
               documentation (see below) by X/Open,  rather  than  an  intentional
               change.

           o   ncurses retains compatibility with System V curses behavior.

           SVr4  describes  a  successful  return  value only as "an integer value
           other than ERR".

           SVr4 does not document whether n counts the null terminator that  these
           functions write to str.

## HISTORY

           SVr3.1  (1987)  introduced these functions.  winstr, winnstr, and their
           variants.

## SEE ALSO

           curs_inwstr(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                       2025-02-01                    curs_instr(3x)