FreeBSD Manual Pages
curs_inwstr(3X) Library calls curs_inwstr(3X) NAME inwstr, winwstr, mvinwstr, mvwinwstr, innwstr, winnwstr, mvinnwstr, mvwinnwstr - get a wide-character string from a curses window SYNOPSIS #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); DESCRIPTION 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 wide characters from win. A negative n implies no limit; winnwstr then works like winwstr. ncurses(3X) describes the variants of these functions. RETURN VALUE On successful operation, these functions return the count of wide charac- ters copied from win to wstr (not including the wide null terminator), or 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 charac- ters, some of which may be non-spacing.) In ncurses, these functions return ERR if * the curses screen has not been initialized, * (for functions taking a WINDOW pointer argument) win is a null pointer, or * wstr 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 winnwstr may be implemented as macros. Reading a line that overflows the array pointed to by wstr and its variants causes undefined results. Instead, use the n-infixed functions with a pos- itive n argument no larger than the size of the buffer backing wstr. EXTENSIONS innwstr, winnwstr, mvinnwstr, and mvwinnwstr'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. 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 inter- preted, 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 return- ing OK rather than a (wide) character count, unlike their non-wide counter- parts instr, winstr, mvinstr, and mvwinstr. ncurses regards this inconsis- tency as an error in the standard. HISTORY The System V Interface Definition, Version 4 (1995), specified winwstr and winnwstr (and the usual variants). These were later additions to SVr4.x, not appearing in the first SVr4 (1989). Their synopses described each function as taking an argument of type pointer-to-char instead of pointer- to-wchar_t, despite describing them as "returning the string of wchar_t in str". Presumably this was an error in the System V Interface Definition. SEE ALSO 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.6 2025-10-20 curs_inwstr(3X)
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | EXTENSIONS | PORTABILITY | HISTORY | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=curs_inwstr&sektion=3&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>