# curs_get_wstr 3x 2025-10-20 ncurses 6.5 Library calls

    curs_get_wstr(3x)                Library calls               curs_get_wstr(3x)

## NAME

           get_wstr,  getn_wstr,  wget_wstr,  wgetn_wstr, mvget_wstr, mvgetn_wstr,
           mvwget_wstr, mvwgetn_wstr - read a wide-character string from a  curses
           terminal keyboard

## SYNOPSIS

           #include <curses.h>

           int get_wstr(wint_t * wstr);
           int wget_wstr(WINDOW * win, wint_t * wstr);
           int mvget_wstr(int y, int x, wint_t * wstr);
           int mvwget_wstr(WINDOW * win, int y, int x, wint_t * wstr);

           int getn_wstr(wint_t * wstr, int n);
           int wgetn_wstr(WINDOW * win, wint_t * wstr, int n);
           int mvgetn_wstr(int y, int x, wint_t * wstr, int n);
           int mvwgetn_wstr(WINDOW * win, int y, int x, wint_t * wstr, int n);

## DESCRIPTION

           wget_wstr  populates  a user-supplied wide-character string buffer wstr
           by repeatedly calling wget_wch(3x) with the win argument until  a  line
           feed or carriage return character is input.  The function

           o   does not copy the terminating character to wstr;

           o   populates  wstr with WEOF (as defined in wchar.h) if an end-of-file
               condition occurs on the input;

           o   always terminates the string with a null wide character (after  any
               WEOF);

           o   interprets  the  screen's  wide erase and wide kill characters (see
               erasewchar(3x) and killwchar(3x));

           o   recognizes function keys only if  the  screen's  keypad  option  is
               enabled (see keypad(3x));

           o   treats the function keys KEY_LEFT and KEY_BACKSPACE the same as the
               wide erase character; and

           o   discards  function  key inputs other than those treated as the wide
               erase or wide kill characters, calling beep(3x).

           The wide erase character replaces the  character  at  the  end  of  the
           buffer  with  a null wide character, while the wide kill character does
           the same for the entire buffer.

           If the screen's  echo  option  is  enabled  (see  echo(3x)),  wget_wstr
           updates win with wadd_wch(3x).  Further,

           o   the  wide  erase  character  and its function key synonyms move the
               cursor to the left, and

           o   the wide kill character returns the cursor to where it was  located
               when wget_wstr was called.

           wgetn_wstr  is similar, but reads at most n wide characters, aiding the
           application to avoid overrunning  the  buffer  to  which  wstr  points.
           curses  ignores  an attempt to input more than n wide characters (other
           than the terminating line feed or carriage return),  calling  beep(3x).
           If  n is negative, wgetn_wstr reads up to LINE_MAX wide characters (see
           sysconf(3)).

           ncurses(3x) describes the variants of these functions.

## RETURN VALUE

           These functions return OK on success and ERR on failure.

           In ncurses, these functions fail if

           o   the curses screen has not been initialized,

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

           o   wstr is a null pointer, or

           o   an internal wget_wch(3x) call fails.

           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 wgetn_wstr may be implemented as macros.

           Reading input that overruns  the  buffer  pointed  to  by  wstr  causes
           undefined   results.    Use   the  n-infixed  functions,  and  allocate
           sufficient storage for wstr -- at least n+1 times sizeof(wchar_t).

           These functions cannot store a KEY_ value in wstr because there  is  no
           way to distinguish it from a valid wchar_t value.

           While  these  functions  conceptually  implement  a  series of calls to
           wget_wch, they also temporarily change properties of the curses  screen
           to  permit simple editing of the input buffer.  Each function saves the
           screen's state, calls nl(3x), and,  if  the  screen  was  in  canonical
           ("cooked")  mode,  cbreak(3x).  Before returning, it restores the saved
           screen state.  Other implementations differ in detail, affecting  which
           control   characters  they  can  accept  in  the  buffer;  see  section
           "PORTABILITY" below.

           Unlike getstr(3x) and related  functions  of  ncurses's  non-wide  API,
           these functions do not return KEY_RESIZE if a SIGWINCH event interrupts
           the function.

## EXTENSIONS

           getn_wstr,  wgetn_wstr,  mvgetn_wstr,  and  mvwgetn_wstr's  handing  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.

           Issue 4 documented these functions as passing an array of wchar_t,  but
           that  was  an  error,  conflicting  with  the following language in the
           standard.

                  The effect of get_wstr() is as  though  a  series  of  calls  to
                  get_wch()  were  made,  until  a  newline character, end-of-line
                  character, or end-of-file character is processed.

           get_wch can return a negative value (WEOF), but wchar_t is  a  unsigned
           type.   All  of  the  vendors  implement  these functions using wint_t,
           following the Issue 7 standard.

           X/Open Curses Issue 7 is unclear  whether  the  terminating  null  wide
           character  counts  toward  the  length  parameter  n.   A similar issue
           affected  wgetnstr  in  Issue 4,  Version 2;   Issue 7   revised   that
           function's   description   to  address  the  issue,  but  not  that  of
           wget_nwstr, leaving it ambiguous.  ncurses counts the terminator in the
           length.

           X/Open Curses does  not  specify  what  happens  if  the  length  n  is
           negative.

           o   For  consistency  with  wgetnstr, ncurses 6.2 uses a limit based on
               LINE_MAX.

           o   Some other implementations (such as Solaris xcurses) do  the  same,
               while others (PDCurses) do not permit a negative n.

           o   NetBSD 7  curses  imitates  ncurses  6.1  and  earlier,  treating a
               negative n as an unbounded count of wide characters.

           Implementations vary in their handling of input control characters.

           o   While they may enable the screen's echo option, some do not take it
               out of raw mode,  and  may  take  cbreak  mode  into  account  when
               deciding  whether to handle echoing within wgetn_wstr or to rely on
               it as a side effect of calling wget_wch.

               Since 1995, ncurses has provided handlers for SIGINTR  and  SIGQUIT
               events,  which  are typically generated at the keyboard with ^C and
               ^\ respectively.  In cbreak mode, those handlers catch a signal and
               stop  the  program,  whereas  other  implementations  write   those
               characters into the buffer.

           o   Starting  with ncurses 6.3 (2021), wgetn_wstr preserves raw mode if
               the screen was already in that state, allowing  one  to  enter  the
               characters  the  terminal  interprets  as interrupt and quit events
               into the buffer, for consistency with SVr4 curses's wgetnstr.

## HISTORY

           X/Open Curses Issue 4 (1995) initially specified these functions.   The
           System V  Interface  Definition  Version 4  of  the same year specified
           functions named wgetwstr and wgetnwstr (and the usual variants).  These
           were later additions to SVr4.x, not appearing in the first SVr4 (1989).
           Except in name, their declarations did not differ from  X/Open's  later
           wget_wstr  and wgetn_wstr until X/Open Curses Issue 7 (2009) eventually
           changed the type of the buffer argument to a pointer to wint_t.

## SEE ALSO

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

           curses(3x), curs_get_wch(3x)

    ncurses 6.5                       2025-10-20                 curs_get_wstr(3x)