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)