***************************************************************************
Copyright 2018-2024,2025 Thomas E. Dickey *
Copyright 1998-2010,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_inchstr.3x,v 1.65 2025/10/21 00:05:02 tom Exp $
.\} .\} . .. \%inchstr, \%inchnstr, \%winchstr, \%winchnstr, \%mvinchstr, \%mvinchnstr, \%mvwinchstr, \%mvwinchnstr - get a curses character string from a window

#include <curses.h>

int inchstr(chtype * chstr);
int inchnstr(chtype * chstr, int n);
int winchstr(WINDOW * win, chtype * chstr);
int winchnstr(WINDOW * win, chtype * chstr, int n);

int mvinchstr(int y, int x, chtype * chstr);
int mvinchnstr(int y, int x, chtype * chstr, int n);
int mvwinchstr(WINDOW * win, int y, int x, chtype * chstr);
int mvwinchnstr(WINDOW * win, int y, int x, chtype * chstr, int n);

\%winchstr extracts a curses character string from a curses window win "," starting at the cursor and stopping at the end of the line, and stores it in chstr "," terminating it with a null curses character. \%winchnstr does the same, but copies at most n curses characters from win "." A negative n implies no limit; \%winchnstr then works like \%winchstr "." \%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 chstr 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 \%winchnstr may be implemented as macros.

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

\%inchnstr "," \%winchnstr "," \%mvinchnstr "," and \%mvwinchnstr "'s" acceptance of negative n values is an \%ncurses extension. 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. It characterizes the strings stored by these functions as containing \*(``at most n elements\*('' from a window, X/Open Issue 4, Version 2, p. 113, PDF p. 133
Issue 7 doesn't change this wording at all.
but does not specify whether the string stored by these functions is null-terminated.

SVr4 does not document whether it null-terminates the curses character string it stores in chstr "," and does not document whether a trailing null curses character counts toward the length limit n "."

SVr4 describes a successful return value only as \*(``an integer value other than ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 503

SVr3.1 (1987) introduced these functions. \%curs_in_wchstr(3X) describes comparable functions of the \%ncurses library in its wide-character configuration \%( ncursesw ).

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