1curs_getstr(3X)                                                curs_getstr(3X)
2
3
4

NAME

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

SYNOPSIS

10       #include <curses.h>
11
12       int getstr(char *str);
13       int getnstr(char *str, int n);
14       int wgetstr(WINDOW *win, char *str);
15       int wgetnstr(WINDOW *win, char *str, int n);
16
17       int mvgetstr(int y, int x, char *str);
18       int mvwgetstr(WINDOW *win, int y, int x, char *str);
19       int mvgetnstr(int y, int x, char *str, int n);
20       int mvwgetnstr(WINDOW *win, int y, int x, char *str, int n);
21

DESCRIPTION

23       The function getstr is equivalent to a series of calls to getch,  until
24       a  newline or carriage return is received (the terminating character is
25       not included in the returned string).  The resulting value is placed in
26       the area pointed to by the character pointer str, followed by a NUL.
27
28       The  getnstr  function reads from the stdscr default window.  The other
29       functions, such as wgetnstr, read from the window given as a parameter.
30
31       getnstr reads at most n characters, thus preventing a possible overflow
32       of  the input buffer.  Any attempt to enter more characters (other than
33       the terminating newline or carriage return) causes  a  beep.   Function
34       keys also cause a beep and are ignored.
35
36       The user's erase and kill characters are interpreted:
37
38       •   The  erase  character (e.g., ^H) erases the character at the end of
39           the buffer, moving the cursor to the left.
40
41           If keypad mode is on for the window, KEY_LEFT and KEY_BACKSPACE are
42           both considered equivalent to the user's erase character.
43
44       •   The kill character (e.g., ^U) erases the entire buffer, leaving the
45           cursor at the beginning of the buffer.
46
47       Characters input are echoed only if echo  is  currently  on.   In  that
48       case,  backspace is echoed as deletion of the previous character (typi‐
49       cally a left motion).
50

RETURN VALUE

52       All routines return the integer ERR upon failure and an OK (SVr4 speci‐
53       fies  only  “an  integer value other than ERR”) upon successful comple‐
54       tion.
55
56       X/Open defines no error conditions.
57
58       In this implementation, these functions return an error if  the  window
59       pointer is null, or if its timeout expires without having any data.
60
61       This  implementation  provides an extension as well.  If a SIGWINCH in‐
62       terrupts the function, it will return KEY_RESIZE rather than OK or ERR.
63
64       Functions with a “mv” prefix first  perform  a  cursor  movement  using
65       wmove, and return an error if the position is outside the window, or if
66       the window pointer is null.
67

NOTES

69       Note that getstr, mvgetstr, and mvwgetstr may be macros.
70

PORTABILITY

72       These functions are described in the  XSI  Curses  standard,  Issue  4.
73       They  read  single-byte  characters only.  The standard does not define
74       any error conditions.  This implementation returns ERR  if  the  window
75       pointer is null, or if the lower-level wgetch(3X) call returns an ERR.
76
77       SVr3  and  early  SVr4  curses  implementations did not reject function
78       keys; the SVr4.0 documentation claimed that  “special  keys”  (such  as
79       function  keys, “home” key, “clear” key, etc.) are “interpreted”, with‐
80       out giving details.  It lied.  In fact, the “character” value  appended
81       to  the  string by those implementations was predictable but not useful
82       (being, in fact, the low-order eight bits of the key's KEY_ value).
83
84       The functions getnstr, mvgetnstr, and mvwgetnstr were present  but  not
85       documented in SVr4.
86
87       X/Open Curses, Issue 5 (2007) stated that these functions “read at most
88       n bytes” but did not state whether the terminating NUL  is  counted  in
89       that  limit.   X/Open  Curses,  Issue 7 (2009) changed that to say they
90       “read at most n-1 bytes” to allow for the terminating NUL.  As of 2018,
91       some implementations do, some do not count it:
92
93       •   ncurses  6.1  and PDCurses do not count the NUL in the given limit,
94           while
95
96       •   Solaris SVr4 and NetBSD curses count the NUL as part of the limit.
97
98       •   Solaris xcurses provides both:  its  wide-character  wget_nstr  re‐
99           serves a NUL, but its wgetnstr does not count the NUL consistently.
100
101       In SVr4 curses, a negative value of n tells wgetnstr to assume that the
102       caller's buffer is large enough to hold the result, i.e., to  act  like
103       wgetstr.   X/Open  Curses does not mention this (or anything related to
104       negative or zero values of n), however  most  implementations  use  the
105       feature, with different limits:
106
107       •   Solaris  SVr4  curses  and  PDCurses limit the result to 255 bytes.
108           Other Unix systems than Solaris are likely to use the same limit.
109
110       •   Solaris xcurses limits the result to LINE_MAX bytes.
111
112       •   NetBSD 7 assumes no particular limit for the result  from  wgetstr.
113           However,  it  limits  the wgetnstr parameter n to ensure that it is
114           greater than zero.
115
116           A comment in NetBSD's source code states that this is specified  in
117           SUSv2.
118
119       •   ncurses  (before  6.2)  assumes  no particular limit for the result
120           from wgetstr, and treats the n  parameter  of  wgetnstr  like  SVr4
121           curses.
122
123       •   ncurses  6.2  uses  LINE_MAX,  or a larger (system-dependent) value
124           which the sysconf function may provide.   If  neither  LINE_MAX  or
125           sysconf  is available, ncurses uses the POSIX value for LINE_MAX (a
126           2048 byte limit).  In either case, it reserves a byte for the  ter‐
127           minating NUL.
128
129       Although  getnstr  is equivalent to a series of calls to getch, it also
130       makes changes to the curses modes to allow simple editing of the  input
131       buffer:
132
133getnstr  saves  the  current  value of the nl, echo, raw and cbreak
134           modes, and sets nl, noecho, noraw, and cbreak.
135
136           getnstr handles the echoing of characters, rather than  relying  on
137           the caller to set an appropriate mode.
138
139       •   It  also  obtains  the erase and kill characters from erasechar and
140           killchar, respectively.
141
142       •   On return, getnstr restores the modes to their previous values.
143
144       Other implementations differ in their treatment of special characters:
145
146       •   While they may set the echo mode, other implementations do not mod‐
147           ify  the  raw mode, They may take the cbreak mode set by the caller
148           into account when deciding whether to handle echoing within getnstr
149           or as a side-effect of the getch calls.
150
151       •   The original ncurses (as pcurses in 1986) set noraw and cbreak when
152           accepting input for getnstr.  That may have been done to make func‐
153           tion- and cursor-keys work; it is not necessary with ncurses.
154
155           Since  1995, ncurses has provided signal handlers for INTR and QUIT
156           (e.g., ^C or ^\).  With the noraw and cbreak  settings,  those  may
157           catch  a  signal  and stop the program, where other implementations
158           allow one to enter those characters in the buffer.
159
160       •   Starting in 2021 (ncurses 6.3), getnstr sets raw, rather than noraw
161           and  cbreak for better compatibility with SVr4-curses, e.g., allow‐
162           ing one to enter a ^C into the buffer.
163

SEE ALSO

165       curses(3X), curs_getch(3X), curs_termattrs(3X), curs_variables(3X).
166
167
168
169                                                               curs_getstr(3X)
Impressum