curs_in_wchstr(3X)

💅 curs_in_wchstr — bestie edition ✨

okay so this is a page from the curses library manual (section 3X, "library calls"), and it's all about scooping a whole complex character string out of a window. yes, complex characters. no, not like emotionally complicated (tho honestly same). grab a snack 🍓, we're doing this.

---

🌸 NAME 🌸

in_wchstr, in_wchnstr, win_wchstr, win_wchnstr, mvin_wchstr, mvin_wchnstr, mvwin_wchstr, mvwin_wchnstr — get a curses complex character string from a window 🫶

---

✨ SYNOPSIS ✨

#include <curses.h>

int in_wchstr(cchar_t * wchstr);
int win_wchstr(WINDOW * win, cchar_t * wchstr);
int mvin_wchstr(int y, int x, cchar_t * wchstr);
int mvwin_wchstr(WINDOW * win, int y, int x, cchar_t * wchstr);

int in_wchnstr(cchar_t * wchstr, int n);
int win_wchnstr(WINDOW * win, cchar_t * wchstr, int n);
int mvin_wchnstr(int y, int x, cchar_t * wchstr, int n);
int mvwin_wchnstr(WINDOW * win, int y, int x, cchar_t * wchstr, int n)

not me pointing out that last line has no semicolon in the original — it's giving "the compiler will tell you bestie" 💀

---

💖 DESCRIPTION 💖

win_wchstr snatches a curses complex character string out of a curses window win, starting right at the cursor and going until the end of the line, then tucks it into wchstr and slaps a wide null curses character on the end to terminate it. iconic behavior, truly.

win_wchnstr does the exact same thing, except it copies at most n curses complex characters from win. and listen — if n is negative, that means no limit at all, so win_wchnstr just vibes like win_wchstr.

oh and ncurses(3X) describes the variants of these functions, if you want the extended lore. iykyk 📖

---

👑 RETURN VALUE 👑

These functions return OK when it works and ERR when it doesn't. 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
• wchstr is a null pointer

Functions prefixed with "mv" first perform cursor movement, and they fail if the position (y, x) is outside the window boundaries. like, stay in your lane pls 🚧

---

🦋 NOTES 🦋

All of these functions except win_wchnstr may be implemented as macros. surprise mechanics, love that for us 💀

BIG WARNING ENERGY: reading a line that overflows the array pointed to by wchstr and its variants causes undefined results. not "oopsie" undefined, like genuinely undefined. instead, use the n-infixed functions with a positive n argument no larger than the size of the buffer backing wchstr. protect your buffer bestie, it's the main character 💅

---

🌈 PORTABILITY 🌈

X/Open Curses Issue 4 describes these functions. it specifies no error conditions for them. so like, they exist, and that's the whole statement. 🎀

---

⭐ HISTORY ⭐

X/Open Curses Issue 4 (1995) initially specified these functions.

the System V Interface Definition Version 4 of the same year specified a function named winwchstr (and the usual variants). this was a later addition to SVr4.x — it did not appear in the first SVr4 (1989).

and the tea ☕: it differed from X/Open's later win_wchstr in that it took an argument of type pointer-to-chtype instead of pointer-to-cchar_t. glow-up era fr fr ✨

---

🧚 SEE ALSO 🧚

• curs_inchstr(3X) describes comparable functions of the ncurses library in its non-wide-character configuration.
• curses(3X)
• curs_inwstr(3X)
• curs_in_wch(3X)

---

and that's the whole page, bestie!! 🫶 this was ncurses 6.6, dated 2025-10-20, and the page you just read is curs_in_wchstr(3X). go forth and read your complex character strings responsibly — with the n versions, with a buffer that can actually hold them, mwah 💖🎀🌸