| .\"*************************************************************************** |
| .\" Copyright 2018-2020,2021 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.33 2021/05/22 21:36:35 tom Exp $ |
| .TH curs_getstr 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 |
| \fBgetstr\fR, |
| \fBgetnstr\fR, |
| \fBwgetstr\fR, |
| \fBwgetnstr\fR, |
| \fBmvgetstr\fR, |
| \fBmvgetnstr\fR, |
| \fBmvwgetstr\fR, |
| \fBmvwgetnstr\fR \- accept character strings from \fBcurses\fR terminal keyboard |
| .ad |
| .hy |
| .SH SYNOPSIS |
| \fB#include <curses.h>\fR |
| .sp |
| \fBint getstr(char *\fP\fIstr\fP\fB);\fR |
| .br |
| \fBint getnstr(char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR |
| .br |
| \fBint wgetstr(WINDOW *\fP\fIwin\fP\fB, char *\fP\fIstr\fP\fB);\fR |
| .br |
| \fBint wgetnstr(WINDOW *\fP\fIwin\fP\fB, char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR |
| .sp |
| \fBint mvgetstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB);\fR |
| .br |
| \fBint mvwgetstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB);\fR |
| .br |
| \fBint mvgetnstr(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR |
| .br |
| \fBint mvwgetnstr(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, char *\fP\fIstr\fP\fB, int \fP\fIn\fP\fB);\fR |
| .br |
| .SH DESCRIPTION |
| The function \fBgetstr\fR is equivalent to a series of calls to \fBgetch\fR, |
| until a newline or carriage return is received (the terminating character is |
| not included in the returned string). |
| .\" X/Open says also until EOf |
| .\" X/Open says then an EOS is added to the result |
| .\" X/Open doesn't mention n<0 |
| The resulting value is placed in the |
| area pointed to by the character pointer \fIstr\fR, |
| followed by a NUL. |
| .PP |
| The \fBgetnstr\fR function reads |
| from the \fIstdscr\fR default window. |
| The other functions, such as \fBwgetnstr\fP, |
| read from the window given as a parameter. |
| .PP |
| \fBgetnstr\fR reads at most \fIn\fR characters, thus preventing a possible |
| overflow of the input buffer. |
| Any attempt to enter more characters (other |
| than the terminating newline or carriage return) causes a beep. |
| Function |
| keys also cause a beep and are ignored. |
| .PP |
| The user's \fIerase\fP and \fIkill\fP characters are interpreted: |
| .bP |
| The \fIerase\fP character (e.g., \fB^H\fP) erases the character |
| at the end of the buffer, moving the cursor to the left. |
| .IP |
| If \fIkeypad\fP mode is on for the window, |
| \fBKEY_LEFT\fR and \fBKEY_BACKSPACE\fR |
| are both considered equivalent to the user's erase character. |
| .bP |
| The \fIkill\fP character (e.g., \fB^U\fP) erases the entire buffer, |
| leaving the cursor at the beginning of the buffer. |
| .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). |
| .SH RETURN VALUE |
| All routines return the integer \fBERR\fR upon failure and an \fBOK\fR (SVr4 |
| specifies only \*(``an integer value other than \fBERR\fR\*('') upon successful |
| completion. |
| .PP |
| X/Open defines no error conditions. |
| .PP |
| In this implementation, |
| these functions return an error |
| if the window pointer is null, or |
| if its timeout expires without having any data. |
| .PP |
| This implementation provides an extension as well. |
| If a \fBSIGWINCH\fP interrupts the function, it will return \fBKEY_RESIZE\fP |
| rather than \fBOK\fP or \fBERR\fP. |
| .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 NOTES |
| Note that \fBgetstr\fR, \fBmvgetstr\fR, and \fBmvwgetstr\fR may be macros. |
| .SH PORTABILITY |
| These functions are described in the XSI Curses standard, Issue 4. |
| They read single-byte characters only. |
| The standard does not define any error conditions. |
| This implementation returns \fBERR\fP if the window pointer is null, |
| or if the lower-level \fBwgetch\fR(3X) call returns an \fBERR\fP. |
| .PP |
| SVr3 and early SVr4 curses implementations did not reject function keys; |
| the SVr4.0 documentation claimed that \*(``special keys\*('' |
| (such as function keys, |
| \*(``home\*('' key, |
| \*(``clear\*('' key, |
| \fIetc\fR.) are \*(``interpreted\*('', |
| without giving details. |
| It lied. |
| In fact, 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's KEY_ value). |
| .PP |
| The functions \fBgetnstr\fR, \fBmvgetnstr\fR, and \fBmvwgetnstr\fR were |
| present but not documented in SVr4. |
| .PP |
| X/Open Curses, Issue 5 (2007) stated that these functions |
| \*(``read at most \fIn\fP bytes\*('' |
| but did not state whether the terminating NUL is counted in that limit. |
| X/Open Curses, Issue 7 (2009) changed that to say they |
| \*(``read at most \fIn\fP\-1 bytes\*('' |
| to allow for the terminating NUL. |
| As of 2018, some implementations do, some do not count it: |
| .bP |
| ncurses 6.1 and PDCurses do not count the NUL in the given limit, while |
| .bP |
| Solaris SVr4 and NetBSD curses count the NUL as part of the limit. |
| .bP |
| Solaris xcurses provides both: |
| its wide-character \fBwget_nstr\fP reserves a NUL, |
| but its \fBwgetnstr\fP does not count the NUL consistently. |
| .PP |
| In SVr4 curses, |
| a negative value of \fIn\fP tells \fBwgetnstr\fP to assume that the |
| caller's buffer is large enough to hold the result, |
| i.e., to act like \fBwgetstr\fP. |
| X/Open Curses does not mention this |
| (or anything related to negative or zero values of \fIn\fP), |
| however most implementations |
| use the feature, with different limits: |
| .bP |
| Solaris SVr4 curses and PDCurses limit the result to 255 bytes. |
| Other Unix systems than Solaris are likely to use the same limit. |
| .bP |
| Solaris xcurses limits the result to \fBLINE_MAX\fP bytes. |
| .bP |
| NetBSD 7 assumes no particular limit for the result from \fBwgetstr\fP. |
| However, it limits the \fBwgetnstr\fP parameter \fIn\fP to ensure |
| that it is greater than zero. |
| .IP |
| A comment in NetBSD's source code states that this is specified in SUSv2. |
| .bP |
| ncurses (before 6.2) assumes no particular limit for the result |
| from \fBwgetstr\fP, and treats the \fIn\fP parameter of \fBwgetnstr\fP |
| like SVr4 curses. |
| .bP |
| ncurses 6.2 uses \fBLINE_MAX\fP, |
| or a larger (system-dependent) value |
| which the \fBsysconf\fP function may provide. |
| If neither \fBLINE_MAX\fP or \fBsysconf\fP is available, |
| ncurses uses the POSIX value for \fBLINE_MAX\fP (a 2048 byte limit). |
| In either case, it reserves a byte for the terminating NUL. |
| .PP |
| Although \fBgetnstr\fP is equivalent to a series of calls to \fBgetch\fP, |
| it also makes changes to the curses modes to allow simple editing of |
| the input buffer: |
| .bP |
| \fBgetnstr\fP saves the current value of the \fBnl\fP, \fBecho\fP, |
| \fBraw\fP and \fBcbreak\fP modes, and sets |
| \fBnl\fP, |
| \fBnoecho\fP, |
| \fBnoraw\fP, and |
| \fBcbreak\fP. |
| .IP |
| \fBgetnstr\fP handles the echoing of characters, |
| rather than relying on the caller to set an appropriate mode. |
| .bP |
| It also obtains the \fIerase\fP and \fIkill\fP characters |
| from \fBerasechar\fP and \fBkillchar\fP, respectively. |
| .bP |
| On return, \fBgetnstr\fP restores the modes to their previous values. |
| .PP |
| Other implementations differ in their treatment of special characters: |
| .bP |
| While they may set the \fIecho\fP mode, |
| other implementations do not modify the \fIraw\fP mode, |
| They may take the \fIcbreak\fP |
| mode set by the caller into account when deciding whether to handle |
| echoing within \fBgetnstr\fP or as a side-effect of the \fBgetch\fP calls. |
| .bP |
| The original ncurses (as pcurses in 1986) set \fBnoraw\fP and \fBcbreak\fP |
| when accepting input for \fBgetnstr\fP. |
| That may have been done to make function- and cursor-keys work; |
| it is not necessary with ncurses. |
| .IP |
| Since 1995, ncurses has provided signal handlers for INTR and QUIT |
| (e.g., \fB^C\fP or \fB^\\\fP). |
| With the \fBnoraw\fP and \fBcbreak\fP settings, |
| those may catch a signal and stop the program, |
| where other implementations allow one to enter those characters in the buffer. |
| .bP |
| Starting in 2021 (ncurses 6.3), \fBgetnstr\fP sets \fBraw\fP, |
| rather than \fBnoraw\fP and \fBcbreak\fP for better compatibility with |
| SVr4-curses, e.g., allowing one to enter a \fB^C\fP into the buffer. |
| .SH SEE ALSO |
| \fBcurses\fR(3X), |
| \fBcurs_getch\fR(3X), |
| \fBcurs_termattrs\fR(3X), |
| \fBcurs_variables\fR(3X). |