curs_addchstr(3X)

💖 curs_addchstr — bestie's guide to yeeting a whole character string into a window 💖

okay so this is a Library calls page (manual section 3X, iykyk) and it's all about one iconic little family of functions: addchstr, waddchstr, mvaddchstr, mvwaddchstr, addchnstr, waddchnstr, mvaddchnstr, mvwaddchnstr — they add a curses character string to a window. that's the whole vibe. 🌈

---

✨ NAME ✨

addchstr, waddchstr, mvaddchstr, mvwaddchstr, addchnstr, waddchnstr, mvaddchnstr, mvwaddchnstr — add a curses character string to a window 🫶

---

✨ SYNOPSIS ✨

#include <curses.h>

int addchstr(const chtype * chstr);
int waddchstr(WINDOW * win, const chtype * chstr);
int mvaddchstr(int y, int x, const chtype * chstr);
int mvwaddchstr(WINDOW * win, int y, int x,
      const chtype * chstr);

int addchnstr(const chtype * chstr, int n);
int waddchnstr(WINDOW * win, const chtype * chstr, int n);
int mvaddchnstr(int y, int x, const chtype * chstr, int n);
int mvwaddchnstr(WINDOW * win, int y, int x,
      const chtype * chstr, int n);

---

✨ DESCRIPTION ✨

so waddchstr copies the string of curses characters chstr to the window win. a null curses character terminates the string, like the end of a sentence but for curses. 🎀

waddchnstr does the exact same thing, but it copies at most n characters — or as many as possible if n is -1. queen behaviour honestly.

ncurses(3X) describes the variants of these functions, if you wanna go deeper down the rabbit hole. 🐇

the way that these functions do not call waddch(3X) internally means they're faster than waddstr(3X) and waddnstr(3X). speed demon energy. 🔥

on the other hand — and bestie listen, this is the trade-off — they:

• do not treat the backspace, carriage return, or line feed characters specially;
• do not represent unprintable characters with unctrl(3X);
• do not update the cursor position to follow the last character written; and
• truncate the string at the window's right margin, rather than wrapping it to the next line and potentially scrolling.

so like, fast but feral. they're not gonna hold your hand through any of the fancy formatting. 💅

---

✨ RETURN VALUE ✨

these functions return OK on success and ERR on failure. slay or flop, no in-between. 😭

in ncurses, these functions fail if

• the curses screen has not been initialized,
• chstr is a null pointer, or
• (for functions taking a WINDOW pointer argument) win 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. stay in your lane or get an ERR, fr fr. 🚧

---

✨ NOTES ✨

all of these functions except waddchnstr may be implemented as macros. yes, that means waddchnstr is the odd one out. main character behaviour, honestly. 👑

---

✨ PORTABILITY ✨

X/Open Curses Issue 4 describes these functions. it specifies no error conditions for them. 🙈

SVr4 describes a successful return value only as "an integer value other than ERR". so like… vague. mysterious. iconic. ✨

---

✨ HISTORY ✨

SVr3.1 (1987) introduced these functions. vintage but still eating. 💜

---

✨ SEE ALSO ✨

• curs_add_wchstr(3X) describes comparable functions of the ncurses library in its wide-character configuration (ncursesw).
• curses(3X)
• curs_addch(3X)
• curs_addstr(3X)

---

and that's the whole page, bestie!! 🦋 this little gem came out of ncurses 6.6, dated 2025-08-16 — go forth and copy your character strings with confidence, no cap. 💖✨🎀