ins_wstr(3NCURSES)

💖 ins_wstr — insert a wide-character string in a curses window 💖

okay bestie, pull up a chair because we're talking about ins_wstr and its whole friend group from the 3NCURSES library-calls corner of the manual. this is the one where you slide a wide-character string into a window like it's a new fit and everyone else has to scooch over. let's get into it 🦋

---

✨ NAME ✨

ins_wstr, wins_wstr, mvins_wstr, mvwins_wstr, ins_nwstr, wins_nwstr, mvins_nwstr, mvwins_nwstr — insert a wide-character string in a curses window. that's the whole vibe. eight little icons, one job 👑

---

🌸 SYNOPSIS 🌸

#include <curses.h>

int ins_wstr(const wchar_t * wstr);
int wins_wstr(WINDOW * win, const wchar_t * wstr);
int mvins_wstr(int y, int x, const wchar_t * wstr);
int mvwins_wstr(WINDOW * win, int y, int x,
      const wchar_t * wstr);

int ins_nwstr(const wchar_t * wstr, int n);
int wins_nwstr(WINDOW * win, const wchar_t * wstr, int n);
int mvins_nwstr(int y, int x, const wchar_t * wstr, int n);
int mvwins_nwstr(WINDOW * win, int y, int x,
      const wchar_t * wstr, int n);

---

💅 DESCRIPTION 💅

so wins_wstr takes your wide-character string wstr and inserts it into window win before whatever character the cursor is sitting on rn. it does this as if it were calling wins_wch(3NCURSES) for each and every wchar_t in wstr. one by one, no shortcuts, no cap.

and here's the tea: no line wrapping is performed. ever. the characters that were hanging out to the right of the cursor get shifted right to make room, and the ones at the very right edge of the window may be lost. gone. deleted. it's giving eviction notice 😭

wins_wstr also stops inserting if it would have to wrap to the next line just to write the next wchar_t in wstr. so it just... stops. no wrapping, we said what we said.

the cursor position does not change — well, after moving to (y, x) if you specified one. so if you're using an mv-flavored version, the move happens, then the cursor parks itself and stays put.

wins_nwstr is the same situation but with a limit: it inserts at most n wide characters, or as many as possible (up to the end of the line) if n is negative. pick your limit, bestie.

also, ncurses(3NCURSES) describes the variants of these functions if you want the full family lore ✨

---

🎀 RETURN VALUE 🎀

these functions return OK when they ate and left no crumbs, and ERR when it didn't work out.

in ncurses, they return ERR if:

• win is NULL,
• wstr is NULL,
• the first wide character in wstr is a non-spacing character, or
• an internal wins_wch(3NCURSES) call returns ERR.

and the ones prefixed with mv? they first perform cursor movement, and they fail if the position (y, x) is outside the window boundaries. stay in your lane or get ERR'd, periodt 🚫

---

🌈 NOTES 🌈

all of these functions except wins_nwstr may be implemented as macros. so don't be weird about taking their address, iykyk 👀

---

👑 EXTENSIONS 👑

ins_nwstr, wins_nwstr, mvins_nwstr, and mvwins_nwstr's acceptance of negative n values is an ncurses extension. not standard, just our little bonus feature 💜

---

🧚 PORTABILITY 🧚

if your app is out here employing ncurses extensions, you should condition their use on the visibility of the NCURSES_VERSION preprocessor macro. guard your code, bestie 🫶

X/Open Curses Issue 4 describes these functions. it specifies no error conditions for them. (yes, zero. nothing. iconic in a chaotic way 💀)

X/Open Curses does not specify what happens if a non-spacing character follows a control character. undefined behaviour territory, we don't go there 🙈

Issue 4 states that the entire string is inserted if n is less than 1. this is probably an error, because it is inconsistent with other functions such as waddwstr, and it differs from the SVr4 curses and Solaris xcurses implementations. nevertheless, Issue 7 retains the language. so it's still sitting there in the spec, being wrong, and we just have to live with it 😭

---

⭐ HISTORY ⭐

X/Open Curses Issue 4 (1995) initially specified these functions. then the System V Interface Definition Version 4 (1995) specified functions named winswstr and winsnwstr (and the usual variants). these were later additions to SVr4.x — they did not appear in the first SVr4 (1989). they differ from X/Open's later wins_wstr and wins_nwstr in that their wstr parameters are not const-qualified. the more you know 🌈

---

🍓 SEE ALSO 🍓

insstr(3NCURSES) describes comparable functions of the ncurses library in its non-wide-character configuration. (the narrow-character bestie version 💅)

ncurses(3NCURSES), ins_wch(3NCURSES), in_wch(3NCURSES)

---

and that's the whole page, bestie 🎀 this was ncurses 6.6, dated 2025-03-01, and honestly? it ate. go insert some wide characters, stay inside your window boundaries, and don't let the right edge steal your string 💖✨