inchstr(3NCURSES)

💖 inchstr, inchnstr, winchstr, winchnstr, mvinchstr, mvinchnstr, mvwinchstr, mvwinchnstr — a.k.a. the get a curses character string from a window girlies 💖

okay so bestie, we're deep in the 3NCURSES manual, library calls section, and this is the one where you grab a whole lil curses character string out of a window. eight functions, one vibe. let's get into it 🦋

---

✨ NAME ✨

inchstr, inchnstr, winchstr, winchnstr, mvinchstr, mvinchnstr, mvwinchstr, mvwinchnstr — get a curses character string from a window. that's the whole job, and they do it flawlessly 💅

---

🌸 SYNOPSIS 🌸

#include <curses.h>

int inchstr(chtype * chstr);
int inchnstr(chtype * chstr, int n);
int winchstr(WINDOW * win, chtype * chstr);
int winchnstr(WINDOW * win, chtype * chstr, int n);

int mvinchstr(int y, int x, chtype * chstr);
int mvinchnstr(int y, int x, chtype * chstr, int n);
int mvwinchstr(WINDOW * win, int y, int x, chtype * chstr);
int mvwinchnstr(WINDOW * win, int y, int x, chtype * chstr, int n);

like, eight whole signatures, all cute, all yours 🎀

---

🫶 DESCRIPTION 🫶

so winchstr extracts a curses character string from a curses window win, starting at the cursor and stopping at the end of the line, and stores it in chstr, terminating it with a null curses character. iconic behavior honestly.

winchnstr does the same thing, but copies at most n curses characters from win. and here's the plot twist: a negative n implies no limit — winchnstr then works like winchstr. no cap. 🫣

ncurses(3NCURSES) describes the variants of these functions, so if you're nosy (same) go read that one too.

---

💀 RETURN VALUE 💀

these functions return OK on success and ERR on failure. simple as that, periodt.

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, or
• chstr is a null pointer.

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

---

🌈 NOTES 🌈

all of these functions except winchnstr may be implemented as macros. so like, don't be weird about taking their address or whatever, iykyk.

🚨 okay this one matters, bestie: reading a line that overflows the array pointed to by chstr 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 chstr. pls pls pls do this, we are not trying to summon demons today 🔥

---

🧚 EXTENSIONS 🧚

inchnstr, winchnstr, mvinchnstr, and mvwinchnstr's acceptance of negative n values is an ncurses extension. so like, it's a glow-up that's ours specifically 💅

---

🦋 PORTABILITY 🦋

applications employing ncurses extensions should condition their use on the visibility of the NCURSES_VERSION preprocessor macro. translation: vibe check your environment first, girlie.

X/Open Curses Issue 4 describes these functions. it specifies no error conditions for them. it characterizes the strings stored by these functions as containing “at most n elements” from a window, but does not specify whether the string stored by these functions is null-terminated. the ambiguity is giving mystery novel 🔍

SVr4 does not document whether it null-terminates the curses character string it stores in chstr, and does not document whether a trailing null curses character counts toward the length limit n. so many unanswered questions, honestly same.

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

---

👑 HISTORY 👑

SVr3.1 (1987) introduced these functions. so they've been serving looks since the 80s, no big deal 💖

---

🔥 SEE ALSO 🔥

in_wchstr(3NCURSES) describes comparable functions of the ncurses library in its wide-character configuration (ncursesw). that's the wide-character girlies, they're slaying over there too.

ncurses(3NCURSES), inch(3NCURSES), inwstr(3NCURSES) — go read them, bestie, knowledge is free and it's so cute 🎀

---

and that's the whole page fr fr 💜 this was ncurses 6.6, dated 2025-10-20, straight from the inchstr(3NCURSES) page — mwah, go forth and read your character strings responsibly, ily, bye 👑🌸