curs_add_wchstr(3X)

✨ curs_add_wchstr — Library calls ✨

okay bestie, so this is the ncurses page all about yeeting a whole string of complex characters into a window. yes, the wide/wide-ish character ones. no cap, it's a whole family of eight functions and we're doing ALL of them 💖

---

🌸 NAME 🌸

add_wchstr, wadd_wchstr, mvadd_wchstr, mvwadd_wchstr, add_wchnstr, wadd_wchnstr, mvadd_wchnstr, mvwadd_wchnstr — add a curses complex character string to a window

it's giving "eight names, one destiny" fr fr 🫶

---

✨ SYNOPSIS ✨

#include <curses.h>

int add_wchstr(const cchar_t * wchstr);
int wadd_wchstr(WINDOW *  win, const cchar_t * wchstr);
int mvadd_wchstr(int y, int x, const cchar_t * wchstr);
int mvwadd_wchstr(WINDOW * win, int y, int x, const cchar_t * wchstr);

int add_wchnstr(const cchar_t * wchstr, int n);
int wadd_wchnstr(WINDOW *  win, const cchar_t * wchstr, int n);
int mvadd_wchnstr(int y, int x, const cchar_t * wchstr, int n);
int mvwadd_wchnstr(WINDOW * win, int y, int x,
      const cchar_t * wchstr, int n);

---

💅 DESCRIPTION 💅

so wadd_wchstr copies the string of complex characters wchstr to the window win. a null complex character is what ends the string — that's the terminator, periodt. and if a complex character doesn't completely fit at the end of the line, curses fills its leftover cells with the window's background character; go peek at bkgrnd(3X) for the lore on that.

wadd_wchnstr does the exact same thing, except it copies at most n characters — or as many as it possibly can if n is -1. and ncurses(3X) is where you go to read up on all the variants of these functions.

now here's the tea, bestie 🍓: because these functions do not call wadd_wch(3X) internally, they are faster than waddwstr(3X) and waddnwstr(3X). iconic speedrun behaviour. but on the other hand — and this is the trade-off, so listen up — they

• do not treat the backspace, carriage return, or line feed characters specially;
• do not represent unprintable characters with wunctrl(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.

translation: fast and feral. no fancy character handling, no cursor babysitting, no wrap-around. it just goes and then it stops. 💀

---

🌈 RETURN VALUE 🌈

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

in ncurses, these functions fail if

• the curses screen has not been initialized,
• wchstr is a null pointer, or
• (for functions taking a WINDOW pointer argument) win 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. so yeah, don't be out here moving the cursor to the void 🙈

---

🎀 NOTES 🎀

all of these functions except wadd_wchnstr may be implemented as macros. so like, don't get weird with them, okay? iykyk.

---

🦋 PORTABILITY 🦋

X/Open Curses Issue 4 describes these functions. and it specifies no error conditions for them. wild, but okay 👑

---

⭐ HISTORY ⭐

X/Open Curses Issue 4 (1995) initially specified these functions. the System V Interface Definition Version 4 of the same year specified functions named waddwchstr and waddwchnstr (and the usual variants). these were later additions to SVr4.x, not appearing in the first SVr4 (1989) — so like, they showed up fashionably late to the party. 🧚

and here's the plot twist: they differed from X/Open's later wadd_wchstr and wadd_wchnstr in that they each took an argument of type wchar_t instead of cchar_t. the way that one little type change is the whole difference… 😭

---

👑 SEE ALSO 👑

curs_addchstr(3X) describes comparable functions of the ncurses library in its non-wide-character configuration.

curses(3X), curs_addwstr(3X), curs_add_wch(3X)

---

and that's the whole page, bestie 💖 go forth and write your complex character strings. this was ncurses 6.6, dated 2025-10-20 — mwah, slay, you're welcome 🎀✨