- These routines return a string of wchar_t wide characters in wstr,
- starting at the current cursor position in the named window.
-
- The four functions with n as the last argument return a leading
- substring at most n characters long (exclusive of the trailing NUL).
- Transfer stops at the end of the current line, or when n characters
- have been stored at the location referenced by wstr.
-
- If the size n is not large enough to store a complete complex
- character, an error is generated.
+ 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.
- All routines return ERR upon failure. Upon successful completion, the
- *inwstr routines return OK, and the *innwstr routines return the number
- of characters read into the string.
+ 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.)
- X/Open defines no error conditions. This implementation returns an
- error
+ In ncurses, these functions return ERR if
- o if the win parameter is null or
+ owin is NULL or
- o if the wstr parameter is null, or
+ owstr is NULL.
- o if no characters could be read.
-
- Functions with a "mv" prefix first perform a cursor movement using
- wmove, and return an error if the position is outside the window, or if
- the window pointer is null.
+ Functions prefixed with "mv" first perform cursor movement and fail if
+ the position (y, x) is outside the window boundaries.
- All routines except winnwstr may be macros.
+ 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.
- Each cell in the window holds a complex character (a spacing character
- and zero or more non-spacing characters) together with attributes and
- color. These functions store only the wide characters, ignoring
- attributes and color. Use in_wchstr to return the complex characters
- from a window.
- Reading a line that overflows the array pointed to by wstr with inwstr,
- mvinwstr, mvwinwstr or winwstr causes undefined results. Therefore,
- the use of innwstr, mvinnwstr, mvwinnwstr, or winnwstr is recommended.
+
- These functions are described in the XSI Curses standard, Issue 4.
+ 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.