NAME

in_wchstr, in_wchnstr, win_wchstr, win_wchnstr, mvin_wchstr, mvin_wchnstr, mvwin_wchstr, mvwin_wchnstr - get a curses complex character string from a window

SYNOPSIS

#include <ncurses/curses.h>

int in_wchstr(cchar_t * wchstr);
int win_wchstr(WINDOW * win, cchar_t * wchstr);
int mvin_wchstr(int y, int x, cchar_t * wchstr);
int mvwin_wchstr(WINDOW * win, int y, int x, cchar_t * wchstr);

int in_wchnstr(cchar_t * wchstr, int n);
int win_wchnstr(WINDOW * win, cchar_t * wchstr, int n);
int mvin_wchnstr(int y, int x, cchar_t * wchstr, int n);
int mvwin_wchnstr(WINDOW * win, int y, int x, cchar_t * wchstr, int n)

DESCRIPTION

win_wchstr extracts a curses complex character string from a curses window win, starting at the cursor and stopping at the end of the line, and stores it in wchstr, terminating it with a wide null curses character. win_wchnstr does the same, but copies at most n curses complex characters from win. A negative n implies no limit; win_wchnstr then works like win_wchstr. ncurses(3X) describes the variants of these functions.

RETURN VALUE

These functions return OK on success and ERR on failure.

In ncurses, these functions fail if

the curses screen has not been initialized,
(for functions taking a WINDOW pointer argument) win is a null pointer, or
wchstr 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 win_wchnstr may be implemented as macros.

Reading a line that overflows the array pointed to by wchstr 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 wchstr.

PORTABILITY

X/Open Curses Issue 4 describes these functions. It specifies no error conditions for them.

HISTORY

X/Open Curses Issue 4 (1995) initially specified these functions. The System V Interface Definition Version 4 of the same year specified a function named winwchstr (and the usual variants). This was a later addition to SVr4.x, not appearing in the first SVr4 (1989). It differed from X/Open's later win_wchstr in that it took an argument of type pointer-to-chtype instead of pointer-to-cchar_t.