curs\_add\_wchstr(3X) Library calls curs\_add\_wchstr(3X)

# [NAME](#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

# [SYNOPSIS](#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](#DESCRIPTION)

**wadd\_wchstr** copies the string of complex characters *wchstr* to the window *win*. A null complex character terminates the string. If a complex character does not completely fit at the end of the line, *curses* fills its remaining cells with the window's background character; see [**bkgrnd**(3X)](/man/os/ncurses/bkgrnd.3X). **wadd\_wchnstr** does the same, but copies at most *n* characters, or as many as possible if *n* is **-1**. [**ncurses**(3X)](/man/os/ncurses/ncurses.3X) describes the variants of these functions.

Because these functions do not call [**wadd\_wch**(3X)](/man/os/ncurses/wadd_wch.3X) internally, they are faster than [**waddwstr**(3X)](/man/os/ncurses/waddwstr.3X) and [**waddnwstr**(3X)](/man/os/ncurses/waddnwstr.3X). On the other hand, they

- do not treat the backspace, carriage return, or line feed characters specially;
- do not represent unprintable characters with [**wunctrl**(3X)](/man/os/ncurses/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.

# [RETURN VALUE](#RETURN_VALUE)

These functions return **OK** on success and **ERR** on failure.

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.

Functions prefixed with “mv” first perform cursor movement and fail if the position (*y*, *x*) is outside the window boundaries.

# [NOTES](#NOTES)

All of these functions except **wadd\_wchnstr** may be implemented as macros.

# [PORTABILITY](#PORTABILITY)

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

# [HISTORY](#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). 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*.

# [SEE ALSO](#SEE_ALSO)

[**curs\_addchstr**(3X)](/man/os/ncurses/curs_addchstr.3X) describes comparable functions of the *ncurses* library in its non-wide-character configuration.

[**curses**(3X)](/man/os/ncurses/curses.3X), [**curs\_addwstr**(3X)](/man/os/ncurses/curs_addwstr.3X), [**curs\_add\_wch**(3X)](/man/os/ncurses/curs_add_wch.3X)

2025-10-20 ncurses 6.6

---

Document: add_wchnstr(3x) from ncurses 6.6.20261031-r0 (Chainguard OS)
Source: https://github.com/ThomasDickey/ncurses-snapshots