| 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><curses.h></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> |