man7.org > Linux > man-pages

Linux/UNIX system programming training

curs_ins_wstr(3x) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | EXTENSIONS | PORTABILITY | HISTORY | SEE ALSO | COLOPHON 

curs_ins_wstr(3X)             Library calls             curs_ins_wstr(3X)

NAME         top

       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         top

       #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         top

       wins_wstr inserts a wide-character string wstr before the
       character at the cursor in window win as if by calling
       wins_wch(3X) 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 wide characters, or as many
       as possible (up to the end of the line) if n is negative.
       ncurses(3X) describes the variants of these functions.

RETURN VALUE         top

       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(3X) call returns ERR.

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

NOTES         top

       All of these functions except wins_nwstr may be implemented as
       macros.

EXTENSIONS         top

       ins_nwstr, wins_nwstr, mvins_nwstr, and mvwins_nwstr's acceptance
       of negative n values is an ncurses extension.

PORTABILITY         top

       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 functions such as waddwstr, and differs from the SVr4
       curses and Solaris xcurses implementations.  Nevertheless, Issue 7
       retains the language.

HISTORY         top

       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 differ from X/Open's later wins_wstr and
       wins_nwstr in that their wstr parameters are not const-qualified.

SEE ALSO         top

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

       curses(3X), curs_ins_wch(3X), curs_in_wch(3X)

COLOPHON         top

       This page is part of the ncurses (new curses) project.
       Information about the project can be found at 
       ⟨https://invisible-island.net/ncurses/ncurses.html⟩.  If you have a
       bug report for this manual page, send it to bug-ncurses@gnu.org.
       This page was obtained from the tarball ncurses-6.6.tar.gz fetched
       from ⟨https://ftp.gnu.org/gnu/ncurses/⟩ on 2026-01-16.  If you
       discover any rendering problems in this HTML version of the page,
       or you believe there is a better or more up-to-date source for the
       page, or you have corrections or improvements to the information
       in this COLOPHON (which is not part of the original manual page),
       send a mail to man-pages@man7.org

ncurses @NCURSES_MAJOR@.@NCU... 2025-03-01              curs_ins_wstr(3X)

HTML rendering created 2026-01-16 by Michael Kerrisk, author of The Linux Programming Interface.

For details of in-depth Linux/UNIX system programming training courses that I teach, look here.

Hosting by jambit GmbH.

Cover of TLPI