# curs_insstr 3x 2023-11-25 ncurses 6.4 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  does  not  define  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 with a "mv" prefix first  perform  a  cursor  movement  using
           wmove(3x),  and  return an error if the position is outside the window,
           or if the window pointer is null.

## NOTES

           All but winsnstr may be macros.

## PORTABILITY

           These functions are described in the  XSI  Curses  standard,  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.4                       2023-11-25                   curs_insstr(3x)