# curs_get_wstr 3x 2025-02-15 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   erase   and   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
               erase character; and

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

           The  erase  character  replaces  the character at the end of the buffer
           with a null wide character, while the 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 erase character and its function key synonyms move  the  cursor
               to the left, and

           o   the  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.  An
           attempt  to  input  more  than  n  wide  characters  (other  than   the
           terminating line feed or carriage return) is ignored with a beep.  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, they return ERR if

           o   win is NULL, or

           o   if 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-02-15                 curs_get_wstr(3x)