getstr(3NCURSES)

💖 getstr(3NCURSES) — the group chat where curses reads your keyboard ✨

okay bestie so this is a Library calls page from the ncurses manual, and it's all about the lil family of functions that let your program read a whole string off the terminal keyboard: getstr, getnstr, wgetstr, wgetnstr, mvgetstr, mvgetnstr, mvwgetstr, mvwgetnstr. no cap, that's eight of them. 👑

---

🌸 NAME 🌸

getstr, getnstr, wgetstr, wgetnstr, mvgetstr, mvgetnstr, mvwgetstr, mvwgetnstr — read a character string from curses terminal keyboard 💅

---

✨ SYNOPSIS ✨

#include <curses.h>

int getstr(char * str);
int wgetstr(WINDOW * win, char * str);
int mvgetstr(int y, int x, char * str);
int mvwgetstr(WINDOW * win, int y, int x, char * str);

int getnstr(char * str, int n);
int wgetnstr(WINDOW * win, char * str, int n);
int mvgetnstr(int y, int x, char * str, int n);
int mvwgetnstr(WINDOW * win, int y, int x, char * str, int n);

---

🦋 DESCRIPTION 🦋

wgetstr fills up a string buffer that you supply — that's str — by calling wgetch(3NCURSES) over and over with the win argument until it sees a line feed or carriage return character. that's the vibe check that ends the party. 🎀

and here's what it does, bullet by bullet, no skipping:

• it does not copy the terminating character into str;
• it always terminates str with a null character;
• it interprets the screen's erase and kill characters (peep erasechar(3NCURSES) and killchar(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 erase character; and
• it discards function key inputs other than the ones treated as the erase or kill characters, and calls beep(3NCURSES) at them. rude but fair 😭

if any characters have already been written into the input buffer, the erase character replaces the character at the current position in the buffer with a null character, and then decrements the position by one. the kill character does the same thing, over and over, backtracking all the way to the beginning of the buffer. slay.

if the screen's echo option is enabled (see echo(3NCURSES)), wgetstr updates win with waddch(3NCURSES). plus:

• the erase character and its function key synonyms move the cursor to the left (only if it's not already where it was when wgetstr was called), and
• the kill character returns the cursor to where it was when wgetstr was called.

wgetnstr is the same situation but it reads at most n characters, which helps your app not overrun the buffer that str points at. curses ignores any attempt to input more than n characters (other than the terminating line feed or carriage return) and calls beep(3NCURSES) about it. if n is negative, wgetn_wstr reads up to LINE_MAX characters (see sysconf(3)). 🫶

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

---

🔥 RETURN VALUE 🔥

these functions return OK on success and ERR on failure. that's it, that's the whole range of emotions.

in ncurses, these functions fail if:

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

also, in ncurses, these functions return KEY_RESIZE if a SIGWINCH event interrupts the function. 💀

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

---

👑 NOTES 👑

all of these functions except wgetnstr may be implemented as macros. iykyk.

reading input that overruns the buffer pointed to by str causes undefined results. use the n-infixed functions, and allocate sufficient storage for str — at least n+1 times sizeof(char). bestie, please. do the math. 🥺

while these functions conceptually implement a series of calls to wgetch, 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, which affects which control characters they can accept in the buffer — see the PORTABILITY section below. 🌈

---

🧚 EXTENSIONS 🧚

getnstr, wgetnstr, mvgetnstr, and mvwgetnstr's handling of negative n values is an ncurses extension.

the return value KEY_RESIZE is an ncurses extension too.

---

🌟 PORTABILITY 🌟

apps that use 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, but it does indicate that wgetnstr and its variants read “the entire multi-byte sequence associated with a character” and “fail” if n and str together do not describe a buffer “large enough to contain any complete characters”. in ncurses, though, wgetch reads only single-byte characters, so this scenario doesn't come up.

SVr4 describes a successful return value only as “an integer value other than ERR”. 😭

SVr3 and early SVr4 curses implementations did not reject function keys; the SVr4 documentation asserted that, like the screen's erase and kill characters, they were

interpreted, as well as any special keys (such as function keys,
“home” key, “clear” key, etc.)

without further detail. it lied. the “character” value appended to the string by those implementations was predictable but not useful — being, in fact, the low-order eight bits of the key code's KEY_ constant value. (the same language, unchanged except for styling, survived into X/Open Curses Issue 4, Version 2 but disappeared from Issue 7.)

a draft of X/Open Curses Issue 5 (which never saw final release) stated that these functions “read at most n bytes” but did not state whether the terminating null character counted toward that limit. X/Open Curses Issue 7 changed that to say they “read at most n-1 bytes” to allow for the terminating null character. as of 2018, some implementations count it, some do not. classic.

• ncurses 6.1 and PDCurses do not count the null character toward the limit, while Solaris and NetBSD curses do.
• Solaris xcurses offers both behaviors: its wide-character wgetn_wstr reserves room for a wide null character, but its non-wide wgetnstr does not consistently count a null character toward the limit.

X/Open Curses does not specify what happens if the length n is negative.

• ncurses 6.2 uses LINE_MAX or a larger (system-dependent) value provided by sysconf(3). if neither LINE_MAX nor sysconf is available, ncurses uses the POSIX minimum value for LINE_MAX (2048). in either case, it reserves a byte for the terminating null character.
• in SVr4 curses, a negative n tells wgetnstr to assume that the caller's buffer is large enough to hold the result; that is, the function then acts like wgetstr. X/Open Curses does not mention this behavior (or anything related to nonpositive n values), however most curses libraries implement it. most implementations nevertheless enforce an upper limit on the count of bytes they write to the destination buffer str.
• BSD curses lacked wgetnstr, and its wgetstr wrote to str unboundedly, as did that in SVr2. 🙈
• PDCurses, and SVr3 and later, and Solaris curses limit both functions to writing 256 bytes. other System V-based platforms likely use the same limit.
• Solaris xcurses limits the write to LINE_MAX bytes (see sysconf(3)).
• NetBSD 7 curses imposes no particular limit on the length of the write, but does validate n to ensure that it is greater than zero. a comment in NetBSD's source code asserts that SUSv2 specifies this.

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 wgetnstr or to rely on it as a side effect of calling wgetch.
• originally, ncurses, like its progenitor pcurses, had its wgetnstr call noraw and cbreak before accepting input. that may have been done to make function keys work; it is not necessary with modern ncurses.

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), wgetnstr 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 better compatibility with SVr4 curses.

---

🎀 HISTORY 🎀

4BSD (1980) introduced wgetstr along with its variants. 💖

SVr3.1 (1987) added wgetnstr, but none of its variants.

X/Open Curses Issue 4 (1995) specified getnstr, mvgetnstr, and mvwgetnstr.

---

🌸 SEE ALSO 🌸

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

ncurses(3NCURSES), addch(3NCURSES), getch(3NCURSES), inopts(3NCURSES), termattrs(3NCURSES)

---

okay that's the whole page, bestie, and it's giving thorough. 🫶 this was ncurses 6.6, dated 2025-10-20 — and yeah, the manual page is literally named getstr(3NCURSES) in the "Library calls" section, which is such a main character move. go read some strings, periodt. 💅✨