1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
|
<!--
****************************************************************************
* Copyright 2018-2024,2025 Thomas E. Dickey *
* Copyright 1998-2010,2017 Free Software Foundation, Inc. *
* *
* Permission is hereby granted, free of charge, to any person obtaining a *
* copy of this software and associated documentation files (the *
* "Software"), to deal in the Software without restriction, including *
* without limitation the rights to use, copy, modify, merge, publish, *
* distribute, distribute with modifications, sublicense, and/or sell *
* copies of the Software, and to permit persons to whom the Software is *
* furnished to do so, subject to the following conditions: *
* *
* The above copyright notice and this permission notice shall be included *
* in all copies or substantial portions of the Software. *
* *
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
* IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
* DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
* OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
* THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
* *
* Except as contained in this notice, the name(s) of the above copyright *
* holders shall not be used in advertising or otherwise to promote the *
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
* @Id: curs_getstr.3x,v 1.94 2025/10/21 00:09:04 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
<TITLE>curs_getstr 3x 2025-10-20 ncurses 6.6 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
<H1 class="no-header">curs_getstr 3x 2025-10-20 ncurses 6.6 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
<STRONG>getstr</STRONG>, <STRONG>getnstr</STRONG>, <STRONG>wgetstr</STRONG>, <STRONG>wgetnstr</STRONG>, <STRONG>mvgetstr</STRONG>, <STRONG>mvgetnstr</STRONG>, <STRONG>mvwgetstr</STRONG>,
<STRONG>mvwgetnstr</STRONG> - read a character string from <EM>curses</EM> terminal keyboard
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
<STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
<STRONG>int</STRONG> <STRONG>getstr(char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>wgetstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>mvgetstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>mvwgetstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>getnstr(char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>wgetnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>mvgetnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>mvwgetnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
<STRONG>wgetstr</STRONG> populates a user-supplied string buffer <EM>str</EM> by repeatedly
calling <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> with the <EM>win</EM> argument until a line feed or carriage
return character is input. The function
<STRONG>o</STRONG> does not copy the terminating character to <EM>str</EM>;
<STRONG>o</STRONG> always terminates <EM>str</EM> with a null character;
<STRONG>o</STRONG> interprets the screen's erase and kill characters (see
<STRONG><A HREF="curs_termattrs.3x.html">erasechar(3x)</A></STRONG> and <STRONG><A HREF="curs_termattrs.3x.html">killchar(3x)</A></STRONG>);
<STRONG>o</STRONG> recognizes function keys only if the screen's keypad option is
enabled (see <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG>);
<STRONG>o</STRONG> treats the function keys <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> the same as the
erase character; and
<STRONG>o</STRONG> discards function key inputs other than those treated as the erase
or kill characters, calling <STRONG><A HREF="curs_beep.3x.html">beep(3x)</A></STRONG>.
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 <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG>), <STRONG>wgetstr</STRONG> updates
<EM>win</EM> with <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG>. Further,
<STRONG>o</STRONG> the erase character and its function key synonyms move the cursor
to the left (if not already where it was located when <STRONG>wgetstr</STRONG> was
called) and
<STRONG>o</STRONG> the kill character returns the cursor to where it was located when
<STRONG>wgetstr</STRONG> was called.
<STRONG>wgetnstr</STRONG> is similar, but reads at most <EM>n</EM> characters, aiding the
application to avoid overrunning the buffer to which <EM>str</EM> points.
<EM>curses</EM> ignores an attempt to input more than <EM>n</EM> characters (other than
the terminating line feed or carriage return), calling <STRONG><A HREF="curs_beep.3x.html">beep(3x)</A></STRONG>. If <EM>n</EM>
is negative, <STRONG>wgetn_wstr</STRONG> reads up to <EM>LINE</EM><STRONG>_</STRONG><EM>MAX</EM> characters (see
<STRONG>sysconf(3)</STRONG>).
<STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of these functions.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure.
In <EM>ncurses</EM>, these functions fail if
<STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized,
<STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null
pointer,
<STRONG>o</STRONG> <EM>str</EM> is a null pointer, or
<STRONG>o</STRONG> an internal <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> call fails.
Further, in <EM>ncurses</EM>, these functions return <STRONG>KEY_RESIZE</STRONG> if a <EM>SIGWINCH</EM>
event interrupts the function.
Functions prefixed with "mv" first perform cursor movement and fail if
the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
All of these functions except <STRONG>wgetnstr</STRONG> may be implemented as macros.
Reading input that overruns the buffer pointed to by <EM>str</EM> causes
undefined results. Use the <STRONG>n</STRONG>-infixed functions, and allocate
sufficient storage for <EM>str</EM> -- at least <EM>n</EM>+1 times <STRONG>sizeof(char)</STRONG>.
While these functions conceptually implement a series of calls to
<STRONG>wgetch</STRONG>, they also temporarily change properties of the <EM>curses</EM> screen to
permit simple editing of the input buffer. Each function saves the
screen's state, calls <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG>, and, if the screen was in canonical
("cooked") mode, <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG>. 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.
</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
<STRONG>getnstr</STRONG>, <STRONG>wgetnstr</STRONG>, <STRONG>mvgetnstr</STRONG>, and <STRONG>mvwgetnstr</STRONG>'s handing of negative <EM>n</EM>
values is an <EM>ncurses</EM> extension.
The return value <STRONG>KEY_RESIZE</STRONG> is an <EM>ncurses</EM> extension.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
Applications employing <EM>ncurses</EM> extensions should condition their use on
the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro.
X/Open Curses Issue 4 describes these functions. It specifies no error
conditions for them, but indicates that <EM>wgetnstr</EM> and its variants read
"the entire multi-byte sequence associated with a character" and "fail"
if <EM>n</EM> and <EM>str</EM> together do not describe a buffer "large enough to contain
any complete characters". In <EM>ncurses</EM>, however, <EM>wgetch</EM> reads only
single-byte characters, so this scenario does not arise.
SVr4 describes a successful return value only as "an integer value
other than <EM>ERR</EM>".
SVr3 and early SVr4 <EM>curses</EM> 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, <EM>etc.</EM>)
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 <EM>KEY</EM><STRONG>_</STRONG>
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 <EM>n</EM> 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 <EM>n</EM>-1 bytes" to
allow for the terminating null character. As of 2018, some
implementations count it, some do not.
<STRONG>o</STRONG> <EM>ncurses</EM> 6.1 and <EM>PDCurses</EM> do not count the null character toward the
limit, while Solaris and NetBSD <EM>curses</EM> do.
<STRONG>o</STRONG> Solaris <EM>xcurses</EM> offers both behaviors: its wide-character
<EM>wgetn</EM><STRONG>_</STRONG><EM>wstr</EM> reserves room for a wide null character, but its non-
wide <EM>wgetnstr</EM> does not consistently count a null character toward
the limit.
X/Open Curses does not specify what happens if the length <EM>n</EM> is
negative.
<STRONG>o</STRONG> <EM>ncurses</EM> 6.2 uses <EM>LINE</EM><STRONG>_</STRONG><EM>MAX</EM> or a larger (system-dependent) value
provided by <STRONG>sysconf(3)</STRONG>. If neither <EM>LINE</EM><STRONG>_</STRONG><EM>MAX</EM> nor <EM>sysconf</EM> is
available, <EM>ncurses</EM> uses the POSIX minimum value for <EM>LINE</EM><STRONG>_</STRONG><EM>MAX</EM>
(2048). In either case, it reserves a byte for the terminating
null character.
<STRONG>o</STRONG> In SVr4 <EM>curses</EM>, a negative <EM>n</EM> tells <EM>wgetnstr</EM> to assume that the
caller's buffer is large enough to hold the result; that is, the
function then acts like <EM>wgetstr</EM>. X/Open Curses does not mention
this behavior (or anything related to nonpositive <EM>n</EM> values),
however most <EM>curses</EM> libraries implement it. Most implementations
nevertheless enforce an upper limit on the count of bytes they
write to the destination buffer <EM>str</EM>.
<STRONG>o</STRONG> BSD <EM>curses</EM> lacked <EM>wgetnstr</EM>, and its <EM>wgetstr</EM> wrote to <EM>str</EM>
unboundedly, as did that in SVr2.
<STRONG>o</STRONG> <EM>PDCurses</EM>, and SVr3 and later, and Solaris <EM>curses</EM> limit both
functions to writing 256 bytes. Other System V-based platforms
likely use the same limit.
<STRONG>o</STRONG> Solaris <EM>xcurses</EM> limits the write to <EM>LINE</EM><STRONG>_</STRONG><EM>MAX</EM> bytes (see
<STRONG>sysconf(3)</STRONG>).
<STRONG>o</STRONG> NetBSD 7 <EM>curses</EM> imposes no particular limit on the length of the
write, but does validate <EM>n</EM> 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.
<STRONG>o</STRONG> 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 <EM>wgetnstr</EM> or to rely on it
as a side effect of calling <EM>wgetch</EM>.
<STRONG>o</STRONG> Originally, <EM>ncurses</EM>, like its progenitor <EM>pcurses</EM>, had its <EM>wgetnstr</EM>
call <EM>noraw</EM> and <EM>cbreak</EM> before accepting input. That may have been
done to make function keys work; it is not necessary with modern
<EM>ncurses</EM>.
Since 1995, <EM>ncurses</EM> has provided handlers for <EM>SIGINTR</EM> and <EM>SIGQUIT</EM>
events, which are typically generated at the keyboard with <STRONG>^C</STRONG> and
<STRONG>^\</STRONG> respectively. In cbreak mode, those handlers catch a signal and
stop the program, whereas other implementations write those
characters into the buffer.
<STRONG>o</STRONG> Starting with <EM>ncurses</EM> 6.3 (2021), <EM>wgetnstr</EM> 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 <EM>curses</EM>.
</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
4BSD (1980) introduced <EM>wgetstr</EM> along with its variants.
SVr3.1 (1987) added <EM>wgetnstr</EM>, but none of its variants.
X/Open Curses Issue 4 (1995) specified <EM>getnstr</EM>, <EM>mvgetnstr</EM>, and
<EM>mvwgetnstr</EM>.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library
in its wide-character configuration (<EM>ncursesw</EM>).
<STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>,
<STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>,
ncurses 6.6 2025-10-20 <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
<li><a href="#h2-HISTORY">HISTORY</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
</ul>
</div>
</BODY>
</HTML>
|
