|
HTML rendering created 2026-01-16 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | EXTENSIONS | PORTABILITY | HISTORY | SEE ALSO | COLOPHON |
|
|
|
curs_get_wstr(3X) Library calls curs_get_wstr(3X)
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
#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);
wget_wstr populates a user-supplied wide-character string buffer
wstr by repeatedly calling wget_wch(3X) 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 wide erase and wide kill characters
(see erasewchar(3X) and killwchar(3X));
• recognizes function keys only if the screen's keypad option is
enabled (see keypad(3X));
• treats the function keys KEY_LEFT and KEY_BACKSPACE the same
as the wide erase character; and
• discards function key inputs other than those treated as the
wide erase or wide kill characters, calling beep(3X).
The wide erase character replaces the character at the end of the
buffer with a null wide character, while the wide kill character
does the same for the entire buffer.
If the screen's echo option is enabled (see echo(3X)), wget_wstr
updates win with wadd_wch(3X). Further,
• the wide erase character and its function key synonyms move
the cursor to the left, and
• the wide 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. curses ignores an attempt to input more than n wide
characters (other than the terminating line feed or carriage
return), calling beep(3X). If n is negative, wgetn_wstr reads up
to LINE_MAX wide characters (see sysconf(3)).
ncurses(3X) describes the variants of these functions.
These functions return OK on success and ERR on failure.
In ncurses, these functions fail if
• the curses screen has not been initialized,
• (for functions taking a WINDOW pointer argument) win is a null
pointer,
• wstr is a null pointer, or
• an internal wget_wch(3X) call fails.
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 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(3X), and, if the
screen was in canonical (“cooked”) mode, cbreak(3X). 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(3X) and related functions of ncurses's non-wide API,
these functions do not return KEY_RESIZE if a SIGWINCH event
interrupts the function.
getn_wstr, wgetn_wstr, mvgetn_wstr, and mvwgetn_wstr's handing 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.
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.
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.
curs_getstr(3X) describes comparable functions of the ncurses
library in its non-wide-character configuration.
curses(3X), curs_get_wch(3X)
This page is part of the ncurses (new curses) project.
Information about the project can be found at
⟨https://invisible-island.net/ncurses/ncurses.html⟩. If you have a
bug report for this manual page, send it to bug-ncurses@gnu.org.
This page was obtained from the tarball ncurses-6.6.tar.gz fetched
from ⟨https://ftp.gnu.org/gnu/ncurses/⟩ on 2026-01-16. If you
discover any rendering problems in this HTML version of the page,
or you believe there is a better or more up-to-date source for the
page, or you have corrections or improvements to the information
in this COLOPHON (which is not part of the original manual page),
send a mail to man-pages@man7.org
ncurses @NCURSES_MAJOR@.@NCU... 2025-10-20 curs_get_wstr(3X)
|
HTML rendering created 2026-01-16 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|