ins_wstr(3NCURSES) Library calls ins_wstr(3NCURSES)
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
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
wins_wstr inserts a wide-character string wstr before the character at
the cursor in window win as if by calling wins_wch(3NCURSES) for each
wchar_t in wstr. No line wrapping is performed. Characters to the
right of the cursor are shifted right; those at the right edge of the
window may be lost. wins_wstr stops inserting if it would have to wrap
to the next line to write the next wchar_t in wstr. The cursor position
does not change (after moving to (y, x), if specified). wins_nwstr does
the same, but inserts at most n characters, or as many as possible (up
to the end of the line) if n is negative. ncurses(3NCURSES) describes
the variants of these functions.
RETURN VALUE
These functions return OK on success and ERR on failure.
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.
Functions prefixed with “mv” first perform cursor movement and fail if
the position (y, x) is outside the window boundaries.
NOTES
All of these functions except wins_nwstr may be implemented as macros.
EXTENSIONS
ins_nwstr, wins_nwstr, mvins_nwstr, and mvwins_nwstr's acceptance of
negative n values is an ncurses extension.
PORTABILITY
Applications employing ncurses extensions should condition their use on
the visibility of the NCURSES_VERSION preprocessor macro.
X/Open Curses Issue 4 describes these functions. It specifies no error
conditions for them.
X/Open Curses does not specify what happens if a non-spacing character
follows a control character.
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 func-
tions such as waddwstr, and differs from the SVr4 curses and Solaris
xcurses implementations. Nevertheless, Issue 7 retains the language.
HISTORY
X/Open Curses Issue 4 (1995) initially specified these functions. 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, not appearing in the first SVr4 (1989). They dif-
fer from X/Open's later wins_wstr and wins_nwstr in that their wstr pa-
rameters are not const-qualified.
SEE ALSO
insstr(3NCURSES) describes comparable functions of the ncurses library
in its non-wide-character configuration.
ncurses(3NCURSES), ins_wch(3NCURSES), in_wch(3NCURSES)
ncurses 6.5 2025-02-01 ins_wstr(3NCURSES)
Generated by dwww version 1.16 on Sat Oct 3 05:20:22 CEST 2026.