diff options
Diffstat (limited to 'man/curs_get_wstr.3x')
| -rw-r--r-- | man/curs_get_wstr.3x | 178 |
1 files changed, 178 insertions, 0 deletions
diff --git a/man/curs_get_wstr.3x b/man/curs_get_wstr.3x new file mode 100644 index 000000000000..4286c78b0d2a --- /dev/null +++ b/man/curs_get_wstr.3x @@ -0,0 +1,178 @@ +.\"*************************************************************************** +.\" Copyright (c) 2002-2005,2006 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.6 2006/02/25 21:49:19 tom Exp $ +.TH curs_get_wstr 3X "" +.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 +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 VALUES +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 +.SH PORTABILITY +These functions are described in The Single Unix Specification, Version 2. +No error conditions are defined. +This implementation returns ERR if the window pointer is null, +or if the lower-level \fBwget_wch\fR call returns an ERR. +In the latter case, +an ERR 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 documents these functions to pass an array of \fBwchar_t\fR, +but all of the vendors implement this using \fBwint_t\fR. +.SH SEE ALSO +Functions: +\fBcurses\fR(3X), +\fBcurs_get_wch\fR(3X), +\fBcurs_getstr\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: |