addchstr(3NCURSES)

💖 addchstr — the ncurses page where we yeet a whole string of curses chars into a window 💖

okay bestie, welcome to the 3NCURSES corner of the manual, this one's all about addchstr and its lil friend group. sit down, hydrate, let's go 🫶

---

✨ NAME ✨

so basically the whole squad is:

• addchstr, waddchstr, mvaddchstr, mvwaddchstr
• addchnstr, waddchnstr, mvaddchnstr, mvwaddchnstr

and their collective job? adding a curses character string to a window. that's it. that's the gig. 💅

---

✨ 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 ✨

okay so here's the tea 🍓

waddchstr copies the string of curses characters chstr into the window win. a null curses character is what ends the string — that's your terminator, periodt.

waddchnstr does literally the same thing, except it copies at most n characters, or as many as it possibly can if n is -1. iconic behaviour honestly.

and if you're like "wait, what are all these other variants" — ncurses(3NCURSES) describes the variants of these functions. go read that, iykyk 💜

🦋 the speed situation

because these functions do not call waddch(3NCURSES) internally, they are faster than waddstr(3NCURSES) and waddnstr(3NCURSES). slay, right?

but — and this is the important part, no cap — on the other hand, they:

• do not treat the backspace, carriage return, or line feed characters specially;
• do not represent unprintable characters with unctrl(3NCURSES);
• 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. it does not move your cursor for you, it does not prettify your unprintables, and it will absolutely just cut your string off at the edge of the window instead of wrapping. know that before you commit. 💀

---

✨ RETURN VALUE ✨

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

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.

and functions 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 waddchnstr may be implemented as macros. so like… don't be out here taking their address, bestie. 😭

---

✨ PORTABILITY ✨

X/Open Curses Issue 4 describes these functions. it specifies no error conditions for them. (we're just out here vibing with undefined failure modes, love that for us 🌈)

SVr4 describes a successful return value only as “an integer value other than ERR”. so. that's the bar. that's the whole bar. ✨

---

✨ HISTORY ✨

SVr3.1 (1987) introduced these functions. vintage. retro. a true original. 👑

---

✨ SEE ALSO ✨

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

also go say hi to:

• ncurses(3NCURSES)
• addch(3NCURSES)
• addstr(3NCURSES)

---

okay that's the whole page, you ate that 🎀 this was ncurses 6.6, dated 2025-08-16, and honestly? she's still serving. mwah. 💖✨🦋🌸