***************************************************************************
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_instr.3x,v 1.82 2025/10/21 00:04:35 tom Exp $
.\} .\} . .. \%instr, \%winstr, \%mvinstr, \%mvwinstr, \%innstr, \%winnstr, \%mvinnstr, \%mvwinnstr - get a string from a curses window

#include <curses.h>

int instr(char * str);
int winstr(WINDOW * win, char * str);
int mvinstr(int y, int x, char * str);
int mvwinstr(WINDOW * win, int y, int x, char * str);

int innstr(char * str, int n);
int winnstr(WINDOW * win, char * str, int n);
int mvinnstr(int y, int x, char * str, int n);
int mvwinnstr(WINDOW * win, int y, int x, char * str, int n);

\%winstr extracts a string from a curses window win "," starting at the cursor and stopping at the end of the line, and stores it in str "," terminating it with a null character and omitting any attributes and color pair identifier that curses associates with each character. \%winnstr does the same, but copies at most n characters from win "." A negative n implies no limit; \%winnstr then works like \%winstr "." \%ncurses(3X) describes the variants of these functions. These functions return the count of characters copied from win to str (not including the null terminator), or ERR upon 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 str 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 \%winnstr may be implemented as macros.

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

\%innstr "," \%winnstr "," \%mvinnstr "," and \%mvwinnstr "'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.

X/Open Curses Issues 4 and 7 both state that \%instr "," \%winstr "," \%mvinstr "," and \%mvwinstr return OK rather than a character count. X/Open Issue 4, Version 2, p. 117, PDF p. 137
Issue 7 makes the same claim.
This is likely an erratum. .bP SVr3.1 and SVr4 implemented \%winstr as a wrapper around \%winnstr "," returning the latter's return value. X/Open Curses's specification thus may have been an editorial solecism copied from System V's documentation (see below) by X/Open, rather than an intentional change. .bP \%ncurses retains compatibility with System V curses behavior.

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

SVr4 does not document whether n counts the null terminator that these functions write to str "."

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

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