# curs_instr 3x 2025-03-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, these functions return ERR 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 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.

## 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-03-01                    curs_instr(3x)