***************************************************************************
Copyright 2018-2024,2025 Thomas E. Dickey *
Copyright 2002-2012,2017 Free Software Foundation, Inc. *
*
Permission is hereby granted, free of charge, to any person obtaining a *
copy of this software and associated documentation files (the *
"Software"), to deal in the Software without restriction, including *
without limitation the rights to use, copy, modify, merge, publish, *
distribute, distribute with modifications, sublicense, and/or sell *
copies of the Software, and to permit persons to whom the Software is *
furnished to do so, subject to the following conditions: *
*
The above copyright notice and this permission notice shall be included *
in all copies or substantial portions of the Software. *
*
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
*
Except as contained in this notice, the name(s) of the above copyright *
holders shall not be used in advertising or otherwise to promote the *
sale, use or other dealings in this Software without prior written *
authorization. *
***************************************************************************

$Id: curs_in_wchstr.3x,v 1.56 2025/10/21 00:03:06 tom Exp $
.\} .\} . .. \%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

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

\%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. These functions return OK on success and ERR on failure.

In \%ncurses "," these functions fail if .bP the curses screen has not been initialized, .bP (for functions taking a \%WINDOW pointer argument) win is a null pointer, or .bP 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.

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 "."

X/Open Curses Issue 4 describes these functions. It specifies no error conditions for them. 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). SVID 4, vol 3., p. 515
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 "." \%curs_inchstr(3X) describes comparable functions of the \%ncurses library in its non-wide-character configuration.

\%curses(3X), \%curs_inwstr(3X), \%curs_in_wch(3X)