Debian Codegraph @

doc/html/man/curs_get_wstr.3x.html

raw
1 <!--
2 ****************************************************************************
3 * Copyright 2018-2024,2025 Thomas E. Dickey *
4 * Copyright 2002-2012,2017 Free Software Foundation, Inc. *
5 * *
6 * Permission is hereby granted, free of charge, to any person obtaining a *
7 * copy of this software and associated documentation files (the *
8 * "Software"), to deal in the Software without restriction, including *
9 * without limitation the rights to use, copy, modify, merge, publish, *
10 * distribute, distribute with modifications, sublicense, and/or sell *
11 * copies of the Software, and to permit persons to whom the Software is *
12 * furnished to do so, subject to the following conditions: *
13 * *
14 * The above copyright notice and this permission notice shall be included *
15 * in all copies or substantial portions of the Software. *
16 * *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 * *
25 * Except as contained in this notice, the name(s) of the above copyright *
26 * holders shall not be used in advertising or otherwise to promote the *
27 * sale, use or other dealings in this Software without prior written *
28 * authorization. *
29 ****************************************************************************
30 * @Id: curs_get_wstr.3x,v 1.79 2025/10/21 00:08:50 tom Exp @
31 -->
32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
33 <HTML>
34 <HEAD>
35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
36 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
37 <TITLE>curs_get_wstr 3x 2025-10-20 ncurses 6.6 Library calls</TITLE>
38 <link rel="author" href="mailto:[email protected]">
39
40 </HEAD>
41 <BODY>
42 <H1 class="no-header">curs_get_wstr 3x 2025-10-20 ncurses 6.6 Library calls</H1>
43 <PRE>
44 <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
45
46
47 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
48 <STRONG>get_wstr</STRONG>, <STRONG>getn_wstr</STRONG>, <STRONG>wget_wstr</STRONG>, <STRONG>wgetn_wstr</STRONG>, <STRONG>mvget_wstr</STRONG>, <STRONG>mvgetn_wstr</STRONG>,
49 <STRONG>mvwget_wstr</STRONG>, <STRONG>mvwgetn_wstr</STRONG> - read a wide-character string from a <EM>curses</EM>
50 terminal keyboard
51
52
53 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
54 <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
55
56 <STRONG>int</STRONG> <STRONG>get_wstr(wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG>
57 <STRONG>int</STRONG> <STRONG>wget_wstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG>
58 <STRONG>int</STRONG> <STRONG>mvget_wstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG>
59 <STRONG>int</STRONG> <STRONG>mvwget_wstr(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>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG>
60
61 <STRONG>int</STRONG> <STRONG>getn_wstr(wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG>
62 <STRONG>int</STRONG> <STRONG>wgetn_wstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG>
63 <STRONG>int</STRONG> <STRONG>mvgetn_wstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG>
64 <STRONG>int</STRONG> <STRONG>mvwgetn_wstr(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>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG>
65
66
67 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
68 <STRONG>wget_wstr</STRONG> populates a user-supplied wide-character string buffer <EM>wstr</EM>
69 by repeatedly calling <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG> with the <EM>win</EM> argument until a line
70 feed or carriage return character is input. The function
71
72 <STRONG>o</STRONG> does not copy the terminating character to <EM>wstr</EM>;
73
74 <STRONG>o</STRONG> populates <EM>wstr</EM> with <EM>WEOF</EM> (as defined in <EM>wchar.h</EM>) if an end-of-file
75 condition occurs on the input;
76
77 <STRONG>o</STRONG> always terminates the string with a null wide character (after any
78 <EM>WEOF</EM>);
79
80 <STRONG>o</STRONG> interprets the screen's wide erase and wide kill characters (see
81 <STRONG><A HREF="curs_termattrs.3x.html">erasewchar(3x)</A></STRONG> and <STRONG><A HREF="curs_termattrs.3x.html">killwchar(3x)</A></STRONG>);
82
83 <STRONG>o</STRONG> recognizes function keys only if the screen's keypad option is
84 enabled (see <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG>);
85
86 <STRONG>o</STRONG> treats the function keys <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> the same as the
87 wide erase character; and
88
89 <STRONG>o</STRONG> discards function key inputs other than those treated as the wide
90 erase or wide kill characters, calling <STRONG><A HREF="curs_beep.3x.html">beep(3x)</A></STRONG>.
91
92 The wide erase character replaces the character at the end of the
93 buffer with a null wide character, while the wide kill character does
94 the same for the entire buffer.
95
96 If the screen's echo option is enabled (see <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG>), <STRONG>wget_wstr</STRONG>
97 updates <EM>win</EM> with <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>. Further,
98
99 <STRONG>o</STRONG> the wide erase character and its function key synonyms move the
100 cursor to the left, and
101
102 <STRONG>o</STRONG> the wide kill character returns the cursor to where it was located
103 when <STRONG>wget_wstr</STRONG> was called.
104
105 <STRONG>wgetn_wstr</STRONG> is similar, but reads at most <EM>n</EM> wide characters, aiding the
106 application to avoid overrunning the buffer to which <EM>wstr</EM> points.
107 <EM>curses</EM> ignores an attempt to input more than <EM>n</EM> wide characters (other
108 than the terminating line feed or carriage return), calling <STRONG><A HREF="curs_beep.3x.html">beep(3x)</A></STRONG>.
109 If <EM>n</EM> is negative, <STRONG>wgetn_wstr</STRONG> reads up to <EM>LINE</EM><STRONG>_</STRONG><EM>MAX</EM> wide characters (see
110 <STRONG>sysconf(3)</STRONG>).
111
112 <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of these functions.
113
114
115 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
116 These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure.
117
118 In <EM>ncurses</EM>, these functions fail if
119
120 <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized,
121
122 <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null
123 pointer,
124
125 <STRONG>o</STRONG> <EM>wstr</EM> is a null pointer, or
126
127 <STRONG>o</STRONG> an internal <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG> call fails.
128
129 Functions prefixed with "mv" first perform cursor movement and fail if
130 the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
131
132
133 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
134 All of these functions except <STRONG>wgetn_wstr</STRONG> may be implemented as macros.
135
136 Reading input that overruns the buffer pointed to by <EM>wstr</EM> causes
137 undefined results. Use the <STRONG>n</STRONG>-infixed functions, and allocate
138 sufficient storage for <EM>wstr</EM> -- at least <EM>n</EM>+1 times <STRONG>sizeof(wchar_t)</STRONG>.
139
140 These functions cannot store a <STRONG>KEY_</STRONG> value in <EM>wstr</EM> because there is no
141 way to distinguish it from a valid <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> value.
142
143 While these functions conceptually implement a series of calls to
144 <STRONG>wget_wch</STRONG>, they also temporarily change properties of the <EM>curses</EM> screen
145 to permit simple editing of the input buffer. Each function saves the
146 screen's state, calls <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG>, and, if the screen was in canonical
147 ("cooked") mode, <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG>. Before returning, it restores the saved
148 screen state. Other implementations differ in detail, affecting which
149 control characters they can accept in the buffer; see section
150 "PORTABILITY" below.
151
152 Unlike <STRONG><A HREF="curs_getstr.3x.html">getstr(3x)</A></STRONG> and related functions of <EM>ncurses</EM>'s non-wide API,
153 these functions do not return <STRONG>KEY_RESIZE</STRONG> if a <EM>SIGWINCH</EM> event interrupts
154 the function.
155
156
157 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
158 <STRONG>getn_wstr</STRONG>, <STRONG>wgetn_wstr</STRONG>, <STRONG>mvgetn_wstr</STRONG>, and <STRONG>mvwgetn_wstr</STRONG>'s handing of
159 negative <EM>n</EM> values is an <EM>ncurses</EM> extension.
160
161
162 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
163 Applications employing <EM>ncurses</EM> extensions should condition their use on
164 the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro.
165
166 X/Open Curses Issue 4 describes these functions. It specifies no error
167 conditions for them.
168
169 Issue 4 documented these functions as passing an array of <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>, but
170 that was an error, conflicting with the following language in the
171 standard.
172
173 The effect of <EM>get</EM><STRONG>_</STRONG><EM>wstr</EM>() is as though a series of calls to
174 <EM>get</EM><STRONG>_</STRONG><EM>wch</EM>() were made, until a newline character, end-of-line
175 character, or end-of-file character is processed.
176
177 <EM>get</EM><STRONG>_</STRONG><EM>wch</EM> can return a negative value (<EM>WEOF</EM>), but <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> is a unsigned
178 type. All of the vendors implement these functions using <EM>wint</EM><STRONG>_</STRONG><EM>t</EM>,
179 following the Issue 7 standard.
180
181 X/Open Curses Issue 7 is unclear whether the terminating null wide
182 character counts toward the length parameter <EM>n</EM>. A similar issue
183 affected <EM>wgetnstr</EM> in Issue 4, Version 2; Issue 7 revised that
184 function's description to address the issue, but not that of
185 <EM>wget</EM><STRONG>_</STRONG><EM>nwstr</EM>, leaving it ambiguous. <EM>ncurses</EM> counts the terminator in the
186 length.
187
188 X/Open Curses does not specify what happens if the length <EM>n</EM> is
189 negative.
190
191 <STRONG>o</STRONG> For consistency with <EM>wgetnstr</EM>, <EM>ncurses</EM> 6.2 uses a limit based on
192 <EM>LINE</EM><STRONG>_</STRONG><EM>MAX</EM>.
193
194 <STRONG>o</STRONG> Some other implementations (such as Solaris <EM>xcurses</EM>) do the same,
195 while others (<EM>PDCurses</EM>) do not permit a negative <EM>n</EM>.
196
197 <STRONG>o</STRONG> NetBSD 7 <EM>curses</EM> imitates <EM>ncurses</EM> 6.1 and earlier, treating a
198 negative <EM>n</EM> as an unbounded count of wide characters.
199
200 Implementations vary in their handling of input control characters.
201
202 <STRONG>o</STRONG> While they may enable the screen's echo option, some do not take it
203 out of raw mode, and may take cbreak mode into account when
204 deciding whether to handle echoing within <EM>wgetn</EM><STRONG>_</STRONG><EM>wstr</EM> or to rely on
205 it as a side effect of calling <EM>wget</EM><STRONG>_</STRONG><EM>wch</EM>.
206
207 Since 1995, <EM>ncurses</EM> has provided handlers for <EM>SIGINTR</EM> and <EM>SIGQUIT</EM>
208 events, which are typically generated at the keyboard with <STRONG>^C</STRONG> and
209 <STRONG>^\</STRONG> respectively. In cbreak mode, those handlers catch a signal and
210 stop the program, whereas other implementations write those
211 characters into the buffer.
212
213 <STRONG>o</STRONG> Starting with <EM>ncurses</EM> 6.3 (2021), <EM>wgetn</EM><STRONG>_</STRONG><EM>wstr</EM> preserves raw mode if
214 the screen was already in that state, allowing one to enter the
215 characters the terminal interprets as interrupt and quit events
216 into the buffer, for consistency with SVr4 <EM>curses</EM>'s <EM>wgetnstr</EM>.
217
218
219 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
220 X/Open Curses Issue 4 (1995) initially specified these functions. The
221 System V Interface Definition Version 4 of the same year specified
222 functions named <EM>wgetwstr</EM> and <EM>wgetnwstr</EM> (and the usual variants). These
223 were later additions to SVr4.<EM>x</EM>, not appearing in the first SVr4 (1989).
224 Except in name, their declarations did not differ from X/Open's later
225 <EM>wget</EM><STRONG>_</STRONG><EM>wstr</EM> and <EM>wgetn</EM><STRONG>_</STRONG><EM>wstr</EM> until X/Open Curses Issue 7 (2009) eventually
226 changed the type of the buffer argument to a pointer to <EM>wint</EM><STRONG>_</STRONG><EM>t</EM>.
227
228
229 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
230 <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library
231 in its non-wide-character configuration.
232
233 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>
234
235 ncurses 6.6 2025-10-20 <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
236 </PRE>
237 <div class="nav">
238 <ul>
239 <li><a href="#h2-NAME">NAME</a></li>
240 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
241 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
242 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
243 <li><a href="#h2-NOTES">NOTES</a></li>
244 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
245 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
246 <li><a href="#h2-HISTORY">HISTORY</a></li>
247 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
248 </ul>
249 </div>
250 </BODY>
251 </HTML>