# curs_inwstr 3x 2025-01-18 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.   They  return  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   win is NULL or

           o   wstr is NULL.

           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 str 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-01-18                   curs_inwstr(3x)