# curs_getstr

## NAME



           **getstr** , **getnstr** , **wgetstr** , **wgetnstr** , **mvgetstr** , **mvgetnstr** ,
           **mvwgetstr** , **mvwgetnstr** - accept character strings from **curses**
           terminal keyboard
    


## SYNOPSIS



           **#include <curses.h>**
    
           **int getstr(char ***_str_**);**
           **int getnstr(char ***_str_**, int** _n_**);**
           **int wgetstr(WINDOW ***_win_**, char ***_str_**);**
           **int wgetnstr(WINDOW ***_win_**, char ***_str_**, int** _n_**);**
    
           **int mvgetstr(int** _y_**, int** _x_**, char ***_str_**);**
           **int mvwgetstr(WINDOW ***_win_**, int** _y_**, int** _x_**, char ***_str_**);**
           **int mvgetnstr(int** _y_**, int** _x_**, char ***_str_**, int** _n_**);**
           **int mvwgetnstr(WINDOW ***_win_**, int** _y_**, int** _x_**, char ***_str_**, int** _n_**);**
    


## DESCRIPTION



           The  function  **getstr** is equivalent to a series of calls to **getch** ,
           until a newline or carriage return is  received  (the  terminating
           character  is not included in the returned string).  The resulting
           value is placed in the area pointed to by  the  character  pointer
           _str_ , followed by a NUL.
    
           The  **getnstr** function  reads from the _stdscr_ default window.  The
           other functions, such as **wgetnstr** , read from the window given as a
           parameter.
    
           **getnstr** reads at most _n_ characters,  thus  preventing  a  possible
           overflow  of  the input buffer.  Any attempt to enter more charac‐
           ters (other than the terminating newline or carriage return) caus‐
           es a beep.  Function keys also cause a beep and are ignored.
    
           The user's _erase_ and _kill_ characters are interpreted:
    
           •   The _erase_ character (e.g., **^H**) erases the character at the end
               of the buffer, moving the cursor to the left.
    
               If _keypad_ mode is on for the window, **KEY_LEFT** and **KEY_BACK‐**
               **SPACE** are both considered equivalent to the user's erase char‐
               acter.
    
           •   The _kill_ character (e.g., **^U**) erases the entire buffer, leav‐
               ing the cursor at the beginning of the buffer.
    
           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).
    


## RETURN VALUE



           All routines return the integer **ERR** upon failure and an **OK**(SVr4
           specifies only “an integer value other than **ERR** ”) upon successful
           completion.
    
           X/Open defines no error conditions.
    
           In this implementation, these functions return an error if the
           window pointer is null, or if its timeout expires without having
           any data.
    
           This implementation provides an extension as well.  If a **SIGWINCH**
           interrupts the function, it will return **KEY_RESIZE** rather than **OK**
           or **ERR**.
    
           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.
    


## NOTES



           Note that **getstr** , **mvgetstr** , and **mvwgetstr** may be macros.
    


## PORTABILITY



           These functions are described in the XSI Curses standard, Issue 4.
           They read single-byte characters only.  The standard does not de‐
           fine any error conditions.  This implementation returns **ERR** if the
           window pointer is null, or if the lower-level **wgetch**(3X) call re‐
           turns an **ERR**.
    
           SVr3 and early SVr4 curses implementations did not reject function
           keys; the SVr4.0 documentation claimed that “special keys” (such
           as function keys, “home” key, “clear” key, _etc_.) are “interpret‐
           ed”, without giving details.  It lied.  In fact, the “character”
           value appended to the string by those implementations was pre‐
           dictable but not useful (being, in fact, the low-order eight bits
           of the key's KEY_ value).
    
           The functions **getnstr** , **mvgetnstr** , and **mvwgetnstr** were present but
           not documented in SVr4.
    
           X/Open Curses, Issue 5 (2007) stated that these functions “read at
           most _n_ bytes” but did not state whether the terminating NUL is
           counted in that limit.  X/Open Curses, Issue 7 (2009) changed that
           to say they “read at most _n_ -1 bytes” to allow for the terminating
           NUL.  As of 2018, some implementations do, some do not count it:
    
           •   ncurses 6.1 and PDCurses do not count the NUL in the given
               limit, while
    
           •   Solaris SVr4 and NetBSD curses count the NUL as part of the
               limit.
    
           •   Solaris xcurses provides both: its wide-character **wget_nstr**
               reserves a NUL, but its **wgetnstr** does not count the NUL con‐
               sistently.
    
           In SVr4 curses, a negative value of _n_ tells **wgetnstr** to assume
           that the caller's buffer is large enough to hold the result, i.e.,
           to act like **wgetstr**.  X/Open Curses does not mention this (or any‐
           thing related to negative or zero values of _n_), however most im‐
           plementations use the feature, with different limits:
    
           •   Solaris SVr4 curses and PDCurses limit the result to 255
               bytes.  Other Unix systems than Solaris are likely to use the
               same limit.
    
           •   Solaris xcurses limits the result to **LINE_MAX** bytes.
    
           •   NetBSD 7 assumes no particular limit for the result from **wget‐**
               **str**.  However, it limits the **wgetnstr** parameter _n_ to ensure
               that it is greater than zero.
    
               A comment in NetBSD's source code states that this is speci‐
               fied in SUSv2.
    
           •   ncurses (before 6.2) assumes no particular limit for the re‐
               sult from **wgetstr** , and treats the _n_ parameter of **wgetnstr** like
               SVr4 curses.
    
           •   ncurses 6.2 uses **LINE_MAX** , or a larger (system-dependent) val‐
               ue which the **sysconf** function may provide.  If neither
               **LINE_MAX** or **sysconf** is available, ncurses uses the POSIX value
               for **LINE_MAX**(a 2048 byte limit).  In either case, it reserves
               a byte for the terminating NUL.
    
           Although **getnstr** is equivalent to a series of calls to **getch** , it
           also makes changes to the curses modes to allow simple editing of
           the input buffer:
    
           •   **getnstr** saves the current value of the **nl** , **echo** , **raw** and
               **cbreak** modes, and sets **nl** , **noecho** , **noraw** , and **cbreak**.
    
               **getnstr** handles the echoing of characters, rather than relying
               on the caller to set an appropriate mode.
    
           •   It also obtains the _erase_ and _kill_ characters from **erasechar**
               and **killchar** , respectively.
    
           •   On return, **getnstr** restores the modes to their previous val‐
               ues.
    
           Other implementations differ in their treatment of special charac‐
           ters:
    
           •   While they may set the _echo_ mode, other implementations do not
               modify the _raw_ mode, They may take the _cbreak_ mode set by the
               caller into account when deciding whether to handle echoing
               within **getnstr** or as a side-effect of the **getch** calls.
    
           •   The original ncurses (as _pcurses_ in 1986) set **noraw** and **cbreak**
               when accepting input for **getnstr**.  That may have been done to
               make function- and cursor-keys work; it is not necessary with
               ncurses.
    
               Since 1995, ncurses has provided signal handlers for INTR and
               QUIT (e.g., **^C** or **^\**).  With the **noraw** and **cbreak** settings,
               those may catch a signal and stop the program, where other im‐
               plementations allow one to enter those characters in the
               buffer.
    
           •   Starting in 2021 (ncurses 6.3), **getnstr** sets **raw** , rather than
               **noraw** and **cbreak** for better compatibility with SVr4-curses,
               e.g., allowing one to enter a **^C** into the buffer.
    


* * *