curs_inchstr(3X)

💖 curs_inchstr — get a curses character string from a window 💖

okay bestie, welcome to curs_inchstr(3X), a genuine library calls moment. this is the one where you yoink a whole string of curses characters out of a window and shove it in your buffer. let's get into it 🫶

---

✨ NAME ✨

inchstr, inchnstr, winchstr, winchnstr, mvinchstr, mvinchnstr, mvwinchstr, mvwinchnstr — get a curses character string from a window

---

🌸 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);

---

🦋 DESCRIPTION 🦋

so winchstr grabs a curses character string out of a curses window win, and it starts right at the cursor and keeps going until it hits the end of the line, then drops the whole thing into chstr and caps it off with a null curses character. that's the vibe. 💅

winchnstr does the exact same thing but copies at most n curses characters out of win. and here's the fun part — a negative n means no limit at all, so winchnstr just acts like winchstr in that case. slay.

ncurses(3X) is where you go if you wanna know about the variants of these functions, iykyk.

---

👑 RETURN VALUE 👑

these cuties return OK when it works and ERR when it does not. 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”? they do the cursor movement first, 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. not me finding that out the hard way 😭

and now the serious one, bestie, listen up:

reading a line that overflows the array pointed to by chstr and its variants causes undefined results. fr fr, do not do this.

instead, use the n-infixed functions with a positive n argument no larger than the size of the buffer backing chstr. that's the safe route, take it. 🎀

---

🌈 EXTENSIONS 🌈

inchnstr, winchnstr, mvinchnstr, and mvwinchnstr's acceptance of negative n values is an ncurses extension. iconic behavior, but keep it in mind.

---

⭐ PORTABILITY ⭐

apps that use ncurses extensions should condition their use on the visibility of the NCURSES_VERSION preprocessor macro. yes, like that. 💅

• 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 it does not specify whether the string stored by these functions is null-terminated.
• 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.
• SVr4 describes a successful return value only as “an integer value other than ERR”. okay bestie, be vague about it then. 🙈

---

🧚 HISTORY 🧚

SVr3.1 (1987) introduced these functions. old money, honestly.

---

🔥 SEE ALSO 🔥

• curs_in_wchstr(3X) — describes comparable functions of the ncurses library in its wide-character configuration (ncursesw). 👀
• curses(3X)
• curs_inch(3X)
• curs_inwstr(3X)

---

that's the whole page, bestie — this was ncurses 6.6, dated 2025-10-20, and it ate, no cap 💖✨ go forth and read your windows responsibly 🎀