get_wstr(3NCURSES)

💖 get_wstr — the wide-char string reader (get_wstr, from the 3NCURSES manual) 💖

okay bestie, sit down, hydrate, because today we're learning about the little curses fam that grabs a whole wide-character string off your terminal keyboard. yes, a string, not just one char. the group chat is: get_wstr, getn_wstr, wget_wstr, wgetn_wstr, mvget_wstr, mvgetn_wstr, mvwget_wstr, and mvwgetn_wstr. iconic lineup honestly. 🫶

---

✨ 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 🦋

so wget_wstr is the main character here. what it does is it fills up a wide-character string buffer that you supply — that's wstr — and it does that by calling wget_wch(3NCURSES) over and over again with the win argument, looping until it gets hit with a line feed or a carriage return character. like, it just keeps going until you press enter, bestie. 🎀

here's the tea on what this function does:

• it does not copy the terminating character into wstr
• it populates wstr with WEOF (as defined in wchar.h) if an end-of-file condition happens on the input
• it always terminates the string with a null wide character (and yes, that's after any WEOF)
• it interprets the screen's wide erase and wide kill characters (peep erasewchar(3NCURSES) and killwchar(3NCURSES))
• it only recognizes function keys if the screen's keypad option is enabled (see keypad(3NCURSES))
• it treats the function keys KEY_LEFT and KEY_BACKSPACE the same as the wide erase character, and
• it discards function key inputs that aren't treated as the wide erase or wide kill characters, and calls beep(3NCURSES) while doing it 😭

the wide erase character does its thing by replacing the character at the end of the buffer with a null wide character, and the wide kill character does that exact same thing but for the entire buffer. gone. deleted. periodt. 💀

and if the screen's echo option is enabled (see echo(3NCURSES)), then wget_wstr updates win using wadd_wch(3NCURSES). also, and this part matters:

• the wide erase character and its function key synonyms move the cursor to the left, and
• the wide kill character brings the cursor right back to wherever it was sitting when wget_wstr was first called ✨

now meet wgetn_wstr — same vibe, but it reads at most n wide characters, which is lowkey a lifesaver because it helps your application avoid overrunning the buffer that wstr points to. curses will straight up ignore any attempt to input more than n wide characters (the terminating line feed or carriage return doesn't count toward that), and it calls beep(3NCURSES) about it. 🙈 and if n is negative, wgetn_wstr reads up to LINE_MAX wide characters (see sysconf(3)).

ncurses(3NCURSES) describes the variants of these functions, iykyk.

---

💜 RETURN VALUE 💜

these functions return OK when everything's good and ERR when it's not. slay.

in ncurses, they fail if:

• the curses screen has not been initialized,
• (for the functions that take a WINDOW pointer argument) win is a null pointer,
• wstr is a null pointer, or
• an internal wget_wch(3NCURSES) call fails.

and the ones prefixed with mv first perform cursor movement, and they fail if the position (y, x) is outside the window boundaries. 🚫

---

🎀 NOTES 🎀

heads up bestie: all of these functions except wgetn_wstr may be implemented as macros. no cap.

reading input that overruns the buffer pointed to by wstr causes undefined results. that is not a vibe. use the n-infixed functions, and allocate enough storage for wstr — at least n+1 times sizeof(wchar_t). 🫶

these functions cannot store a KEY_ value in wstr, because there's genuinely no way to tell it apart from a valid wchar_t value. just how it is. 🤷

so even though these functions conceptually just do a series of calls to wget_wch, they also temporarily change properties of the curses screen so you can do simple editing of the input buffer. every one of them saves the screen's state, calls nl(3NCURSES), and — if the screen was in canonical ("cooked") mode — calls cbreak(3NCURSES). then before returning, it puts the saved screen state right back. other implementations differ in the details, which affects which control characters they can accept into the buffer; check the "PORTABILITY" section below. 👀

and unlike getstr(3NCURSES) and its related non-wide-API ncurses functions, these ones do not return KEY_RESIZE if a SIGWINCH event interrupts the function. not the same girl, don't compare them. 💅

---

🌈 EXTENSIONS 🌈

getn_wstr, wgetn_wstr, mvgetn_wstr, and mvwgetn_wstr's handling of negative n values is an ncurses extension. ⭐

---

👑 PORTABILITY 👑

if you're an application using ncurses extensions, you should condition their use on the visibility of the NCURSES_VERSION preprocessor macro. (yes, that's the move. do it.)

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 — it conflicted 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 an 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 (like 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 also 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 you 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 — they didn't appear 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. glow-up fr fr. ✨

---

🍓 SEE ALSO 🍓

getstr(3NCURSES) describes comparable functions of the ncurses library in its non-wide-character configuration.

ncurses(3NCURSES), get_wch(3NCURSES)

---

okay that's the whole page, you ate that 💖 this was ncurses 6.6, dated 2025-10-20, and that's the get_wstr(3NCURSES) manual page — go forth and read them wide chars, bestie. 👑🌸💜