Provided by: ncurses-doc_6.5+20250216-2_all 
NAME
get_wstr, getn_wstr, wget_wstr, wgetn_wstr, mvget_wstr, mvgetn_wstr, mvwget_wstr, mvwgetn_wstr - read a
wide-character string from a curses terminal keyboard
SYNOPSIS
#include <curses.h>
int get_wstr(wint_t * wstr);
int wget_wstr(WINDOW * win, wint_t * wstr);
int mvget_wstr(int y, int x, wint_t * wstr);
int mvwget_wstr(WINDOW * win, int y, int x, wint_t * wstr);
int getn_wstr(wint_t * wstr, int n);
int wgetn_wstr(WINDOW * win, wint_t * wstr, int n);
int mvgetn_wstr(int y, int x, wint_t * wstr, int n);
int mvwgetn_wstr(WINDOW * win, int y, int x, wint_t * wstr,
int n);
DESCRIPTION
wget_wstr populates a user-supplied wide-character string buffer wstr by repeatedly calling
wget_wch(3NCURSES) with the win argument until a line feed or carriage return character is input. The
function
• does not copy the terminating character to wstr;
• populates wstr with WEOF (as defined in wchar.h) if an end-of-file condition occurs on the input;
• always terminates the string with a null wide character (after any WEOF);
• interprets the screen's erase and kill characters (see erasewchar(3NCURSES) and killwchar(3NCURSES));
• recognizes function keys only if the screen's keypad option is enabled (see keypad(3NCURSES));
• treats the function keys KEY_LEFT and KEY_BACKSPACE the same as the erase character; and
• discards function key inputs other than those treated as the erase character, calling beep(3NCURSES).
The erase character replaces the character at the end of the buffer with a null wide character, while the
kill character does the same for the entire buffer.
If the screen's echo option is enabled (see echo(3NCURSES)), wget_wstr updates win with
wadd_wch(3NCURSES). Further,
• the erase character and its function key synonyms move the cursor to the left, and
• the kill character returns the cursor to where it was located when wget_wstr was called.
wgetn_wstr is similar, but reads at most n wide characters, aiding the application to avoid overrunning
the buffer to which wstr points. An attempt to input more than n wide characters (other than the
terminating line feed or carriage return) is ignored with a beep. If n is negative, wgetn_wstr reads up
to LINE_MAX wide characters (see sysconf(3)).
ncurses(3NCURSES) describes the variants of these functions.
RETURN VALUE
These functions return OK on success and ERR on failure.
In ncurses, they return ERR if
• win is NULL, or
• if an internal wget_wch(3NCURSES) call fails.
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 wgetn_wstr may be implemented as macros.
Reading input that overruns the buffer pointed to by wstr causes undefined results. Use the n-infixed
functions, and allocate sufficient storage for wstr — at least n+1 times sizeof(wchar_t).
These functions cannot store a KEY_ value in wstr because there is no way to distinguish it from a valid
wchar_t value.
While these functions conceptually implement a series of calls to wget_wch, they also temporarily change
properties of the curses screen to permit simple editing of the input buffer. Each function saves the
screen's state, calls nl(3NCURSES), and, if the screen was in canonical (“cooked”) mode,
cbreak(3NCURSES). Before returning, it restores the saved screen state. Other implementations differ in
detail, affecting which control characters they can accept in the buffer; see section “PORTABILITY”
below.
Unlike getstr(3NCURSES) and related functions of ncurses's non-wide API, these functions do not return
KEY_RESIZE if a SIGWINCH event interrupts the function.
EXTENSIONS
getn_wstr, wgetn_wstr, mvgetn_wstr, and mvwgetn_wstr's handing of negative n values 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.
Issue 4 documented these functions as passing an array of wchar_t, but that was an error, conflicting
with the following language in the standard.
The effect of get_wstr() is as though a series of calls to get_wch() were made, until a newline
character, end-of-line character, or end-of-file character is processed.
get_wch can return a negative value (WEOF), but wchar_t is a unsigned type. All of the vendors implement
these functions using wint_t, following the Issue 7 standard.
X/Open Curses Issue 7 is unclear whether the terminating null wide character counts toward the length
parameter n. A similar issue affected wgetnstr in Issue 4, Version 2; Issue 7 revised that function's
description to address the issue, but not that of wget_nwstr, leaving it ambiguous. ncurses counts the
terminator in the length.
X/Open Curses does not specify what happens if the length n is negative.
• For consistency with wgetnstr, ncurses 6.2 uses a limit based on LINE_MAX.
• Some other implementations (such as Solaris xcurses) do the same, while others (PDCurses) do not
permit a negative n.
• NetBSD 7 curses imitates ncurses 6.1 and earlier, treating a negative n as an unbounded count of wide
characters.
Implementations vary in their handling of input control characters.
• While they may enable the screen's echo option, some do not take it out of raw mode, and may take
cbreak mode into account when deciding whether to handle echoing within wgetn_wstr or to rely on it
as a side effect of calling wget_wch.
Since 1995, ncurses has provided handlers for SIGINTR and SIGQUIT events, which are typically
generated at the keyboard with ^C and ^\ respectively. In cbreak mode, those handlers catch a signal
and stop the program, whereas other implementations write those characters into the buffer.
• Starting with ncurses 6.3 (2021), wgetn_wstr preserves raw mode if the screen was already in that
state, allowing one to enter the characters the terminal interprets as interrupt and quit events into
the buffer, for consistency with SVr4 curses's wgetnstr.
HISTORY
X/Open Curses Issue 4 (1995) initially specified these functions. The System V Interface Definition
Version 4 of the same year specified functions named wgetwstr and wgetnwstr (and the usual variants).
These were later additions to SVr4.x, not appearing in the first SVr4 (1989). Except in name, their
declarations did not differ from X/Open's later wget_wstr and wgetn_wstr until X/Open Curses Issue 7
(2009) eventually changed the type of the buffer argument to a pointer to wint_t.
SEE ALSO
getstr(3NCURSES) describes comparable functions of the ncurses library in its non-wide-character
configuration.
ncurses(3NCURSES), get_wch(3NCURSES)
ncurses 6.5 2025-02-15 get_wstr(3NCURSES)