# curs_instr 3x 2025-10-20 ncurses 6.6 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
           (not including the null terminator), or ERR upon failure.

           In ncurses, these functions fail if

           o   the curses screen has not been initialized,

           o   (for  functions  taking  a  WINDOW  pointer argument) win is a null
               pointer, or

           o   str is a null pointer.

           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 and its
           variants  causes  undefined  results.   Instead,  use   the   n-infixed
           functions  with  a  positive  n argument no larger than the size of the
           buffer backing str.

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

## 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.6                       2025-10-20                    curs_instr(3x)