| .\"*************************************************************************** |
| .\" Copyright 2018-2019,2020 Thomas E. Dickey * |
| .\" Copyright 2002-2012,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_get_wstr.3x,v 1.20 2020/02/02 23:34:34 tom Exp $ |
| .TH curs_get_wstr 3X "" |
| .ie \n(.g .ds `` \(lq |
| .el .ds `` `` |
| .ie \n(.g .ds '' \(rq |
| .el .ds '' '' |
| .de bP |
| .ie n .IP \(bu 4 |
| .el .IP \(bu 2 |
| .. |
| .na |
| .hy 0 |
| .SH NAME |
| \fBget_wstr\fR, |
| \fBgetn_wstr\fR, |
| \fBwget_wstr\fR, |
| \fBwgetn_wstr\fR, |
| \fBmvget_wstr\fR, |
| \fBmvgetn_wstr\fR, |
| \fBmvwget_wstr\fR, |
| \fBmvwgetn_wstr\fR \- get an array of wide characters from a curses terminal keyboard |
| .ad |
| .hy |
| .SH SYNOPSIS |
| .nf |
| \fB#include <curses.h>\fR |
| .sp |
| \fBint get_wstr(wint_t *\fR\fIwstr\fR\fB);\fR |
| .br |
| \fBint getn_wstr(wint_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR |
| .br |
| \fBint wget_wstr(WINDOW *\fR\fIwin\fR\fB, wint_t *\fR\fIwstr\fR\fB);\fR |
| .br |
| \fBint wgetn_wstr(WINDOW *\fR\fIwin\fR\fB, wint_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR |
| .br |
| \fBint mvget_wstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwstr\fR\fB);\fR |
| .br |
| \fBint mvgetn_wstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR |
| .br |
| \fBint mvwget_wstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwstr\fR\fB);\fR |
| .br |
| \fBint mvwgetn_wstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR |
| .fi |
| .SH DESCRIPTION |
| The effect of |
| \fBget_wstr\fR |
| is as though a series of calls |
| to |
| \fBget_wch\fR(3X) |
| were made, until a newline, other end-of-line, |
| or end-of-file condition is processed. |
| An end-of-file condition is represented by \fBWEOF\fR, |
| as defined in \fB<wchar.h>\fR. |
| The newline and end-of-line conditions are represented |
| by the \fB\\n\fR \fBwchar_t\fR value. |
| In all instances, the end of the string is terminated by a null \fBwchar_t\fR. |
| The routine places resulting values in the area pointed to by \fIwstr\fR. |
| .PP |
| The user's erase and kill characters are interpreted. |
| If keypad |
| mode is on for the window, \fBKEY_LEFT\fR and \fBKEY_BACKSPACE\fR |
| are both considered equivalent to the user's kill character. |
| .PP |
| Characters input are echoed only if \fBecho\fR is currently on. |
| In that case, |
| backspace is echoed as deletion of the previous character (typically a left |
| motion). |
| .PP |
| The effect of |
| \fBwget_wstr\fR |
| is as though a series of |
| calls to |
| \fBwget_wch\fR |
| were made. |
| .PP |
| The effect of |
| \fBmvget_wstr\fR |
| is as though a call to |
| \fBmove\fR |
| and then a series of calls to |
| \fBget_wch\fR |
| were |
| made. |
| .PP |
| The effect of |
| \fBmvwget_wstr\fR |
| is as though a call to |
| \fBwmove\fR |
| and then a series of calls to |
| \fBwget_wch\fR |
| were made. |
| .PP |
| The |
| \fBgetn_wstr\fR, |
| \fBmvgetn_wstr\fR, |
| \fBmvwgetn_wstr\fR, and |
| \fBwgetn_wstr\fR |
| functions are identical |
| to the |
| \fBget_wstr\fR, |
| \fBmvget_wstr\fR, |
| \fBmvwget_wstr\fR, and |
| \fBwget_wstr\fR |
| functions, respectively, |
| except that the |
| \fB*n_*\fR |
| versions read at most |
| \fIn\fR |
| characters, letting the application prevent overflow of the |
| input buffer. |
| .SH NOTES |
| Using |
| \fBget_wstr\fR, |
| \fBmvget_wstr\fR, |
| \fBmvwget_wstr\fR, or |
| \fBwget_wstr\fR |
| to read a line that |
| overflows the array pointed to by |
| \fBwstr\fR |
| causes undefined |
| results. |
| The use of |
| \fBgetn_wstr\fR, |
| \fBmvgetn_wstr\fR, |
| \fBmvwgetn_wstr\fR, or |
| \fBwgetn_wstr\fR, respectively, is recommended. |
| .PP |
| These functions cannot return \fBKEY_\fR values because there |
| is no way to distinguish a \fBKEY_\fR value from a valid \fBwchar_t\fR value. |
| .PP |
| All of these routines except \fBwgetn_wstr\fR may be macros. |
| .SH RETURN VALUE |
| All of these functions return \fBOK\fR upon successful completion. |
| Otherwise, they return \fBERR\fR. |
| .PP |
| Functions using a window parameter return an error if it is null. |
| .RS |
| .TP 5 |
| \fBwgetn_wstr\fP |
| returns an error if the associated call to \fBwget_wch\fP failed. |
| .RE |
| .PP |
| Functions with a \*(``mv\*('' prefix first perform a cursor movement using |
| \fBwmove\fP, and return an error if the position is outside the window, |
| or if the window pointer is null. |
| .SH PORTABILITY |
| These functions are described in The Single Unix Specification, Version 2. |
| No error conditions are defined. |
| This implementation returns \fBERR\fP if the window pointer is null, |
| or if the lower-level \fBwget_wch\fR call returns an \fBERR\fP. |
| In the latter case, |
| an \fBERR\fP return without other data is treated as an end-of-file condition, |
| and the returned array contains a \fBWEOF\fR followed by a null \fBwchar_t\fR. |
| .PP |
| X/Open curses documented these functions to pass an array of \fBwchar_t\fR |
| in 1997, but that was an error because of this part of the description: |
| .RS |
| .PP |
| The effect of \fIget_wstr()\fP is as though a series of calls to |
| \fIget_wch()\fP were made, until a newline character, end-of-line character, or |
| end-of-file character is processed. |
| .RE |
| .PP |
| The latter function \fIget_wch()\fP can return a negative value, |
| while \fBwchar_t\fP is a unsigned type. |
| All of the vendors implement this using \fBwint_t\fR, following the standard. |
| .PP |
| X/Open Curses, Issue 7 (2009) is unclear regarding whether |
| the terminating \fInull \fP\fBwchar_t\fP |
| value is counted in the length parameter \fIn\fP. |
| X/Open Curses, Issue 7 revised the corresponding description |
| of \fBwgetnstr\fP to address this issue. |
| The unrevised description of \fBwget_nwstr\fP can be interpreted either way. |
| This implementation counts the terminator in the length. |
| .PP |
| X/Open Curses does not specify what happens if the length \fIn\fP is negative. |
| .bP |
| For analogy with \fBwgetnstr\fP, |
| ncurses 6.2 uses a limit (based on \fBLINE_MAX\fP). |
| .bP |
| Some other implementations (such as Solaris xcurses) do the same, |
| while others (PDCurses) do not allow this. |
| .bP |
| NetBSD 7 curses imitates ncurses 6.1 in this regard, |
| treating a \fB\-1\fP as an indefinite number of characters. |
| .SH SEE ALSO |
| Functions: |
| \fBcurses\fR(3X), |
| \fBcurs_get_wch\fR(3X), |
| \fBcurs_getstr\fR(3X). |