# curs_get_wstr 3x 2025-04-05 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   str 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-04-05                 curs_get_wstr(3x)