# curs_inwstr 3x 2025-03-01 ncurses 6.5 Library calls

    curs_inwstr(3x)                  Library calls                 curs_inwstr(3x)

## NAME

           inwstr,  winwstr,  mvinwstr,  mvwinwstr,  innwstr, winnwstr, mvinnwstr,
           mvwinnwstr - get a wide-character string from a curses window

## SYNOPSIS

           #include <curses.h>

           int inwstr(wchar_t * wstr);
           int winwstr(WINDOW * win, wchar_t * wstr);
           int mvinwstr(int y, int x, wchar_t * wstr);
           int mvwinwstr(WINDOW * win, int y, int x, wchar_t * wstr);

           int innwstr(wchar_t * wstr, int n);
           int winnwstr(WINDOW * win, wchar_t * wstr, int n);
           int mvinnwstr(int y, int x, wchar_t * wstr, int n);
           int mvwinnwstr(WINDOW * win, int y, int x, wchar_t * wstr,
                 int n);

## DESCRIPTION

           winwstr extracts a wide-character string  from  a  curses  window  win,
           starting  at the cursor and stopping at the end of the line, and stores
           it in wstr, terminating it with a wide null character and omitting  any
           attributes  and  color pair identifier that curses associates with each
           character.   winnwstr  does  the  same,  but  copies  at  most  n  wide
           characters  from  win.   A  negative  n implies no limit; winnwstr then
           works like  winwstr.   ncurses(3x)  describes  the  variants  of  these
           functions.

## RETURN VALUE

           On  successful  operation,  these  functions  return  the count of wide
           characters copied from win to wstr,  or  ERR  upon  failure.   innwstr,
           winnwstr,  mvinnwstr,  and mvwinnwstr return ERR if n is insufficiently
           large to store a complete wide character string.  (Recall that a curses
           complex  character  can contain multiple wide characters, some of which
           may be non-spacing.)

           In ncurses, these functions return ERR if

           o   the curses screen has not been initialized,

           o   (for functions taking a WINDOW pointer  argument)  win  is  a  null
               pointer, or

           o   wstr 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

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

           Reading a line that overflows the array pointed to by wstr with inwstr,
           winwstr,  mvinwstr,  or  mvwinwstr  causes  undefined  results.  Use of
           innwstr, winnwstr, mvinnwstr, and mvwinnwstr is recommended instead.

## EXTENSIONS

           innwstr, winnwstr, mvinnwstr, and mvwinnwstr'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.

           Notwithstanding  the foregoing, X/Open Curses Issues 4 and 7 both state
           that innwstr, winnwstr, mvinnwstr, and mvwinnwstr "fail  ...  [i]f  the
           array  is  not  large  enough  to  contain  any  complete  characters".
           Strictly interpreted, this means  that  a  caller  of  these  functions
           cannot use their return values to detect truncation of a wide-character
           string copied from more  than  one  character  cell  in  win.   ncurses
           reports any truncation with ERR.

           X/Open  Curses  specifies  inwstr,  winwstr, mvinwstr, and mvwinwstr as
           returning OK rather than a (wide) character count,  unlike  their  non-
           wide  counterparts  instr,  winstr,  mvinstr,  and  mvwinstr.   ncurses
           regards this inconsistency as an error in the standard.

## HISTORY

           The System V Interface Definition, Version 4 (1995), specified  winwstr
           and  winnwstr  (and the usual variants).  These were later additions to
           SVr4.x, not  appearing  in  the  first  SVr4  (1989).   Their  synopses
           described  each  function as taking an argument of type pointer-to-char
           instead of pointer-to-wchar_t, despite describing  them  as  "returning
           the  string  of  wchar_t  in str".  Presumably this was an error in the
           System V Interface Definition.

## SEE ALSO

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

           curses(3x), curs_in_wch(3x), curs_in_wchstr(3x)

    ncurses 6.5                       2025-03-01                   curs_inwstr(3x)