https://invisible-island.net/ncurses/man/


curs_instr 3x 2025-08-16 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
       (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.5                       2025-08-16                    curs_instr(3x)