# curs_get_wstr

## NAME



           **get_wstr** , **getn_wstr** , **wget_wstr** , **wgetn_wstr** , **mvget_wstr** ,
           **mvgetn_wstr** , **mvwget_wstr** , **mvwgetn_wstr** - get an array of wide
           characters from a curses terminal keyboard
    


## SYNOPSIS



           **#include <curses.h>**
    
           **int get_wstr(wint_t ***_wstr_**);**
           **int getn_wstr(wint_t ***_wstr_**, int** _n_**);**
           **int wget_wstr(WINDOW ***_win_**, wint_t ***_wstr_**);**
           **int wgetn_wstr(WINDOW ***_win_**, wint_t ***_wstr_**, int** _n_**);**
    
           **int mvget_wstr(int** _y_**, int** _x_**, wint_t ***_wstr_**);**
           **int mvgetn_wstr(int** _y_**, int** _x_**, wint_t ***_wstr_**, int** _n_**);**
           **int mvwget_wstr(WINDOW ***_win_**, int** _y_**, int** _x_**, wint_t ***_wstr_**);**
           **int mvwgetn_wstr(WINDOW ***_win_**, int** _y_**, int** _x_**, wint_t ***_wstr_**, int** _n_**);**
    


## DESCRIPTION



           The  effect  of  **get_wstr** is  as  though  a  series  of  calls to
           **get_wch**(3X) were made, until a newline, other end-of-line, or end-
           of-file condition is processed.  An end-of-file condition is  rep‐
           resented  by  **WEOF** , as defined in **< wchar.h>**.  The newline and end-
           of-line conditions are represented by the **\n  wchar_t** value.   In
           all  instances,  the  end  of  the  string is terminated by a null
           **wchar_t**.  The routine places resulting values in the area  pointed
           to by _wstr_.
    
           The  user's  erase and kill characters are interpreted.  If keypad
           mode is on for the window, **KEY_LEFT** and  **KEY_BACKSPACE** are  both
           considered equivalent to the user's kill character.
    
           Characters input are echoed only if **echo** is currently on.  In that
           case,  backspace  is  echoed as deletion of the previous character
           (typically a left motion).
    
           The effect of **wget_wstr** is as though a series of calls to **wget_wch**
           were made.
    
           The effect of **mvget_wstr** is as though a call to **move** and  then  a
           series of calls to **get_wch** were made.
    
           The  effect of **mvwget_wstr** is as though a call to **wmove** and then a
           series of calls to **wget_wch** were made.
    
           The **getn_wstr** , **mvgetn_wstr** , **mvwgetn_wstr** , and **wgetn_wstr** functions
           are  identical  to  the  **get_wstr** ,  **mvget_wstr** ,  **mvwget_wstr** ,  and
           **wget_wstr** functions,  respectively, except that the ***n_*** versions
           read at most _n_ characters, letting the application  prevent  over‐
           flow of the input buffer.
    


## NOTES



           Using  **get_wstr** ,  **mvget_wstr** ,  **mvwget_wstr** , or **wget_wstr** to read a
           line that overflows the array pointed to by **wstr** causes  undefined
           results.   The  use  of  **getn_wstr** ,  **mvgetn_wstr** , **mvwgetn_wstr** , or
           **wgetn_wstr** , respectively, is recommended.
    
           These functions cannot return **KEY_** values because there is no  way
           to distinguish a **KEY_** value from a valid **wchar_t** value.
    
           All of these routines except **wgetn_wstr** may be macros.
    


## RETURN VALUE



           All of these functions return **OK** upon successful completion.  Oth‐
           erwise, they return **ERR**.
    
           Functions using a window parameter return an error if it is null.
    
                  **wgetn_wstr**
                       returns an error if the associated call to **wget_wch**
                       failed.
    
           Functions with a “mv” prefix first perform a cursor movement using
           **wmove** , and return an error if the position is outside the window,
           or if the window pointer is null.
    


## PORTABILITY



           These functions are described in The Single Unix Specification,
           Version 2.  No error conditions are defined.  This implementation
           returns **ERR** if the window pointer is null, or if the lower-level
           **wget_wch** call returns an **ERR**.  In the latter case, an **ERR** return
           without other data is treated as an end-of-file condition, and the
           returned array contains a **WEOF** followed by a null **wchar_t**.
    
           X/Open curses documented these functions to pass an array of
           **wchar_t** in 1997, but that was an error because of this part of the
           description:
    
                  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.
    
           The latter function _get_wch_ can return a negative value, while
           **wchar_t** is a unsigned type.  All of the vendors implement this us‐
           ing **wint_t** , following the standard.
    
           X/Open Curses, Issue 7 (2009) is unclear regarding whether the
           terminating _null_ **wchar_t** value is counted in the length parameter
           _n_.  X/Open Curses, Issue 7 revised the corresponding description
           of **wgetnstr** to address this issue.  The unrevised description of
           **wget_nwstr** can be interpreted either way.  This implementation
           counts the terminator in the length.
    
           X/Open Curses does not specify what happens if the length _n_ is
           negative.
    
           •   For analogy with **wgetnstr** , ncurses 6.2 uses a limit (based on
               **LINE_MAX**).
    
           •   Some other implementations (such as Solaris xcurses) do the
               same, while others (PDCurses) do not allow this.
    
           •   NetBSD 7 curses imitates ncurses 6.1 in this regard, treating
               a **-1** as an indefinite number of characters.
    


* * *