curs_inwstr(3x) Library calls curs_inwstr(3x)
inwstr, innwstr, winwstr, winnwstr, mvinwstr, mvinnwstr, mvwinwstr,
mvwinnwstr - get a wide-character string from a curses window
#include <curses.h>
int inwstr(wchar_t * wstr);
int winwstr(WINDOW * win, wchar_t * wstr);
int mvinwstr(int y, int x, wchar_t * wstr);
int mvwinwstr(WINDOW * win, int y, int x, wchar_t * wstr);
int innwstr(wchar_t * wstr, int n);
int winnwstr(WINDOW * win, wchar_t * wstr, int n);
int mvinnwstr(int y, int x, wchar_t * wstr, int n);
int mvwinnwstr(WINDOW * win, int y, int x, wchar_t * wstr, int n);
winwstr extracts a wide-character string from a curses window win,
starting at the cursor and stopping at the end of the line, and stores
it in wstr, terminating it with a wide null character and omitting any
attributes and color pair identifier that curses associates with each
character. winnwstr does the same, but copies at most n characters
from win. An n of -1 implies no limit; winnwstr then works like
winwstr. ncurses(3x) describes the variants of these functions.
On successful operation, these functions return the count of wide
characters copied from win to wstr. They return ERR upon failure.
innwstr, winnwstr, mvinnwstr, and mvwinnwstr return ERR if n is
insufficiently large to store a complete wide character string.
(Recall that a curses complex character can contain multiple wide
characters, some of which may be non-spacing.)
In ncurses, these functions return ERR if
o win is NULL or
o wstr 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 winnwstr may be implemented as macros.
Reading a line that overflows the array pointed to by str with inwstr,
winwstr, mvinwstr, or mvwinwstr causes undefined results. Use of
innwstr, winnwstr, mvinnwstr, and mvwinnwstr is recommended instead.
innwstr, winnwstr, mvinnwstr, and mvwinnwstr'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.
Notwithstanding the foregoing, X/Open Curses Issues 4 and 7 both state
that innwstr, winnwstr, mvinnwstr, and mvwinnwstr "fail ... [i]f the
array is not large enough to contain any complete characters".
Strictly interpreted, this means that a caller of these functions
cannot use their return values to detect truncation of a wide-character
string copied from more than one character cell in win. ncurses
reports any truncation with ERR.
X/Open Curses specifies inwstr, winwstr, mvinwstr, and mvwinwstr as
returning OK rather than a (wide) character count, unlike their non-
wide counterparts instr, winstr, mvinstr, and mvwinstr. ncurses
regards this inconsistency as an error in the standard.
curs_instr(3x) describes comparable functions of the ncurses library in
its non-wide-character configuration.
curses(3x), curs_in_wch(3x), curs_in_wchstr(3x)
ncurses 6.5 2024-06-08 curs_inwstr(3x)