# curs_insstr 3x 2024-04-20 ncurses 6.5 Library calls

    curs_insstr(3x)                  Library calls                 curs_insstr(3x)

## NAME

           insstr,  insnstr,  winsstr,  winsnstr,  mvinsstr, mvinsnstr, mvwinsstr,
           mvwinsnstr - insert a string in a curses window

## SYNOPSIS

           #include <curses.h>
           int insstr(const char *str);
           int insnstr(const char *str, int n);
           int winsstr(WINDOW *win, const char *str);
           int winsnstr(WINDOW *win, const char *str, int n);

           int mvinsstr(int y, int x, const char *str);
           int mvinsnstr(int y, int x, const char *str, int n);
           int mvwinsstr(WINDOW *win, int y, int x, const char *str);
           int mvwinsnstr(WINDOW *win, int y, int x, const char *str, int n);

## DESCRIPTION

           These routines insert a character string (as many  characters  as  will
           fit  on  the line) before the character under the cursor, as if calling
           winsch(3x).  All characters to the right  of  the  cursor  are  shifted
           right,  with  the  possibility  of the rightmost characters on the line
           being lost.  No wrapping is performed.

           The cursor  position  does  not  change  (after  moving  to  y,  x,  if
           specified).

           The functions with n as the last argument insert a leading substring of
           at most n characters.  If n is less than zero,  the  entire  string  is
           inserted (stopping on a NUL character).

           Special characters are handled as in waddch(3x).

## RETURN VALUE

           All functions return the integer ERR upon failure and OK on success.

           X/Open   Curses   does   not   specify   any  error  conditions.   This
           implementation returns an error

           o   if the win parameter is null or

           o   if the str parameter is null or

           o   the winsch(3x) function returns an error.

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

## NOTES

           All but winsnstr may be macros.

## PORTABILITY

           These  functions  are  described  in X/Open Curses, Issue 4, which adds
           const qualifiers to the arguments.

           The Single Unix  Specification,  Version  2  states  that  insnstr  and
           winsnstr  perform  wrapping.  This is probably an error, since it makes
           this group of  functions  inconsistent.   Also,  no  implementation  of
           curses documents this inconsistency.

           X/Open  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,  and  differs  from  the  SVr4 and X/Open implementations on
           Solaris.

## SEE ALSO

           curses(3x), curs_inch(3x), curs_ins_wstr(3x), curs_util(3x)

    ncurses 6.5                       2024-04-20                   curs_insstr(3x)