# curs_inwstr.3x - Man Page

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(inty, intx, wchar_t *wstr); int mvwinwstr(WINDOW *win, inty, intx, wchar_t *wstr); int innwstr(wchar_t *wstr, intn); int winnwstr(WINDOW *win, wchar_t *wstr, intn); int mvinnwstr(inty, intx, wchar_t *wstr, intn); int mvwinnwstr(WINDOW *win, inty, intx, wchar_t *wstr, intn);

## 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* characters from *win*. An *n* of **-1** 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 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

*win*is**NULL**or*wstr*is**NULL**.

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 *str* with **inwstr**, **winwstr**, **mvinwstr**, or **mvwinwstr** causes undefined results. Use of **innwstr**, **winnwstr**, **mvinnwstr**, and **mvwinnwstr** is recommended instead.

## Extensions

**innwstr**, **winnwstr**, **mvinnwstr**, and **mvwinnwstr**'s treatment of **-1** as a valid value of *n* 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 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.

## 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)

## Referenced By

The man pages innwstr.3x(3), inwstr.3x(3), mvinnwstr.3x(3), mvinwstr.3x(3), mvwinnwstr.3x(3), mvwinwstr.3x(3), winnwstr.3x(3) and winwstr.3x(3) are aliases of curs_inwstr.3x(3).