# curs_inwstr 3x 2025-10-20 ncurses 6.6 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  (not  including  the  wide  null
           terminator),  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  and  its
           variants   causes   undefined  results.   Instead,  use  the  n-infixed
           functions with a positive n argument no larger than  the  size  of  the
           buffer backing wstr.

## 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.6                       2025-10-20                   curs_inwstr(3x)