https://invisible-island.net/ncurses/man/


curs_getstr 3x 2025-07-05 ncurses 6.5 Library calls

curs_getstr(3x)                  Library calls                 curs_getstr(3x)




NAME

       getstr,  getnstr,  wgetstr,  wgetnstr,  mvgetstr, mvgetnstr, mvwgetstr,
       mvwgetnstr - read a character string from curses terminal keyboard


SYNOPSIS

       #include <curses.h>

       int getstr(char * str);
       int wgetstr(WINDOW * win, char * str);
       int mvgetstr(int y, int x, char * str);
       int mvwgetstr(WINDOW * win, int y, int x, char * str);

       int getnstr(char * str, int n);
       int wgetnstr(WINDOW * win, char * str, int n);
       int mvgetnstr(int y, int x, char * str, int n);
       int mvwgetnstr(WINDOW * win, int y, int x, char * str,
             int n);


DESCRIPTION

       wgetstr populates a  user-supplied  string  buffer  str  by  repeatedly
       calling  wgetch(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 str;

       o   always terminates str with a null character;

       o   interprets  the   screen's   erase   and   kill   characters   (see
           erasechar(3x) and killchar(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
           or kill characters, calling beep(3x).

       If any characters have been written to  the  input  buffer,  the  erase
       character  replaces the character at the current position in the buffer
       with a null character, then decrements the position by  one;  the  kill
       character  does  the  same repeatedly, backtracking to the beginning of
       the buffer.

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

       o   the  erase  character and its function key synonyms move the cursor
           to the left (if not already where it was located when  wgetstr  was
           called) and

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

       wgetnstr is similar,  but  reads  at  most  n  characters,  aiding  the
       application  to  avoid  overrunning  the  buffer  to  which str points.
       curses ignores an attempt to input more than n characters  (other  than
       the  terminating line feed or carriage return), calling beep(3x).  If n
       is  negative,  wgetn_wstr  reads  up  to   LINE_MAX   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 wgetch(3x) call fails.

       Further, in ncurses, these functions return KEY_RESIZE  if  a  SIGWINCH
       event interrupts the function.

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

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

       While these functions conceptually  implement  a  series  of  calls  to
       wgetch, 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.


EXTENSIONS

       getnstr,  wgetnstr,  mvgetnstr,  and mvwgetnstr's handing of negative n
       values is an ncurses extension.

       The return value KEY_RESIZE 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, but indicates that wgetnstr and its variants  read
       "the entire multi-byte sequence associated with a character" and "fail"
       if n and str together do not describe a buffer "large enough to contain
       any  complete  characters".   In  ncurses,  however,  wgetch reads only
       single-byte characters, so this scenario does not arise.

       SVr4 describes a successful return value  only  as  "an  integer  value
       other than ERR".

       SVr3  and  early  SVr4  curses  implementations did not reject function
       keys; the SVr4 documentation asserted that, like the screen's erase and
       kill characters, they were

              interpreted, as well as any special keys (such as function keys,
              "home" key, "clear" key, etc.)

       without further detail.  It lied.  The "character"  value  appended  to
       the  string  by those implementations was predictable but not useful --
       being, in fact, the  low-order  eight  bits  of  the  key  code's  KEY_
       constant  value.   (The  same  language,  unchanged except for styling,
       survived into X/Open Curses Issue 4,  Version 2  but  disappeared  from
       Issue 7.)

       A draft of X/Open Curses Issue 5 (which never saw final release) stated
       that these functions "read at most n bytes" but did not  state  whether
       the  terminating  null  character  counted  toward  that limit.  X/Open
       Curses Issue 7 changed that to say they "read at  most  n-1  bytes"  to
       allow   for   the   terminating  null  character.   As  of  2018,  some
       implementations count it, some do not.

       o   ncurses 6.1 and PDCurses do not count the null character toward the
           limit, while Solaris and NetBSD curses do.

       o   Solaris   xcurses   offers   both   behaviors:  its  wide-character
           wgetn_wstr reserves room for a wide null character,  but  its  non-
           wide  wgetnstr  does not consistently count a null character toward
           the limit.

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

       o   ncurses  6.2  uses  LINE_MAX  or  a larger (system-dependent) value
           provided  by  sysconf(3).   If  neither  LINE_MAX  nor  sysconf  is
           available,  ncurses  uses  the  POSIX  minimum  value  for LINE_MAX
           (2048).  In either case, it reserves a  byte  for  the  terminating
           null character.

       o   In  SVr4  curses,  a  negative  n tells wgetnstr to assume that the
           caller's buffer is large enough to hold the result;  that  is,  the
           function  then  acts  like wgetstr.  X/Open Curses does not mention
           this behavior  (or  anything  related  to  nonpositive  n  values),
           however  most  curses libraries implement it.  Most implementations
           nevertheless enforce an upper limit on  the  count  of  bytes  they
           write to the destination buffer str.

       o   BSD   curses   lacked  wgetnstr,  and  its  wgetstr  wrote  to  str
           unboundedly, as did that in SVr2.

       o   PDCurses, and  SVr3  and  later,  and  Solaris  curses  limit  both
           functions  to  writing  256  bytes.  Other System V-based platforms
           likely use the same limit.

       o   Solaris  xcurses  limits  the  write   to   LINE_MAX   bytes   (see
           sysconf(3)).

       o   NetBSD  7  curses  imposes no particular limit on the length of the
           write, but does validate n to ensure that it is greater than  zero.
           A  comment  in  NetBSD's  source  code asserts that SUSv2 specifies
           this.

       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 wgetnstr or to rely on it
           as a side effect of calling wgetch.

       o   Originally,  ncurses, like its progenitor pcurses, had its wgetnstr
           call noraw and cbreak before accepting input.  That may  have  been
           done  to  make  function keys work; it is not necessary with modern
           ncurses.

           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), wgetnstr 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 better compatibility with SVr4 curses.


HISTORY

       4BSD (1980) introduced wgetstr along with its variants.

       SVr3.1 (1987) added wgetnstr, but none of its variants.

       X/Open   Curses   Issue 4  (1995)  specified  getnstr,  mvgetnstr,  and
       mvwgetnstr.


SEE ALSO

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

       curses(3x),     curs_addch(3x),     curs_getch(3x),    curs_inopts(3x),
       curs_termattrs(3x),



ncurses 6.5                       2025-07-05                   curs_getstr(3x)