curs_instr(3x) Library calls curs_instr(3x)
instr, innstr, winstr, winnstr, mvinstr, mvinnstr, mvwinstr, mvwinnstr
- get a string from a curses window
#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);
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. An n
of -1 implies no limit; winnstr then works like winstr. ncurses(3x)
describes the variants of these functions.
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.
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.
innstr, winnstr, mvinnstr, and mvwinnstr's treatment of -1 as a valid
value of n is an ncurses extension.
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 documents no return values apart from OK and ERR for any of these
functions. SVr4 does not document whether n counts the null terminator
that these functions write to str.
SVr3.1 (1987) introduced these functions.
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 2024-06-08 curs_instr(3x)