man/curs_getstr.3x

   1 .\"***************************************************************************
   2 .\" Copyright 2018-2022,2023 Thomas E. Dickey                                *
   3 .\" Copyright 1998-2010,2017 Free Software Foundation, Inc.                  *
   4 .\"                                                                          *
   5 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
   6 .\" copy of this software and associated documentation files (the            *
   7 .\" "Software"), to deal in the Software without restriction, including      *
   8 .\" without limitation the rights to use, copy, modify, merge, publish,      *
   9 .\" distribute, distribute with modifications, sublicense, and/or sell       *
  10 .\" copies of the Software, and to permit persons to whom the Software is    *
  11 .\" furnished to do so, subject to the following conditions:                 *
  12 .\"                                                                          *
  13 .\" The above copyright notice and this permission notice shall be included  *
  14 .\" in all copies or substantial portions of the Software.                   *
  15 .\"                                                                          *
  16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  23 .\"                                                                          *
  24 .\" Except as contained in this notice, the name(s) of the above copyright   *
  25 .\" holders shall not be used in advertising or otherwise to promote the     *
  26 .\" sale, use or other dealings in this Software without prior written       *
  27 .\" authorization.                                                           *
  28 .\"***************************************************************************
  29 .\"
  30 .\" $Id: curs_getstr.3x,v 1.40 2023/07/01 15:43:20 tom Exp $
  31 .TH curs_getstr 3X 2023-07-01 "ncurses 6.4" "Library calls"
  32 .ie \n(.g .ds `` \(lq
  33 .el       .ds `` ``
  34 .ie \n(.g .ds '' \(rq
  35 .el       .ds '' ''
  36 .de bP
  37 .ie n  .IP \(bu 4
  38 .el    .IP \(bu 2
  39 ..
  40 .na
  41 .hy 0
  42 .SH NAME
  43 \fBgetstr\fP,
  44 \fBgetnstr\fP,
  45 \fBwgetstr\fP,
  46 \fBwgetnstr\fP,
  47 \fBmvgetstr\fP,
  48 \fBmvgetnstr\fP,
  49 \fBmvwgetstr\fP,
  50 \fBmvwgetnstr\fP \- accept character strings from \fBcurses\fP terminal keyboard
  51 .ad
  52 .hy
  53 .SH SYNOPSIS
  54 \fB#include <curses.h>\fP
  55 .sp
  56 \fBint getstr(char *\fIstr\fB);\fR
  57 .br
  58 \fBint getnstr(char *\fIstr\fB, int \fIn\fB);\fR
  59 .br
  60 \fBint wgetstr(WINDOW *\fIwin\fB, char *\fIstr\fB);\fR
  61 .br
  62 \fBint wgetnstr(WINDOW *\fIwin\fB, char *\fIstr\fB, int \fIn\fB);\fR
  63 .sp
  64 \fBint mvgetstr(int \fIy\fB, int \fIx\fB, char *\fIstr\fB);\fR
  65 .br
  66 \fBint mvwgetstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, char *\fIstr\fB);\fR
  67 .br
  68 \fBint mvgetnstr(int \fIy\fB, int \fIx\fB, char *\fIstr\fB, int \fIn\fB);\fR
  69 .br
  70 \fBint mvwgetnstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, char *\fIstr\fB, int \fIn\fB);\fR
  71 .SH DESCRIPTION
  72 The function \fBgetstr\fP is equivalent to a series of calls to \fBgetch\fP,
  73 until a newline or carriage return is received (the terminating character is
  74 not included in the returned string).
  75 .\" X/Open says also until EOf
  76 .\" X/Open says then an EOS is added to the result
  77 .\" X/Open doesn't mention n<0
  78 The resulting value is placed in the
  79 area pointed to by the character pointer \fIstr\fP,
  80 followed by a NUL.
  81 .PP
  82 The \fBgetnstr\fP function reads
  83 from the \fIstdscr\fP default window.
  84 The other functions, such as \fBwgetnstr\fP,
  85 read from the window given as a parameter.
  86 .PP
  87 \fBgetnstr\fP reads at most \fIn\fP characters, thus preventing a possible
  88 overflow of the input buffer.
  89 Any attempt to enter more characters (other
  90 than the terminating newline or carriage return) causes a beep.
  91 Function
  92 keys also cause a beep and are ignored.
  93 .PP
  94 The user's \fIerase\fP and \fIkill\fP characters are interpreted:
  95 .bP
  96 The \fIerase\fP character (e.g., \fB^H\fP) erases the character
  97 at the end of the buffer, moving the cursor to the left.
  98 .IP
  99 If \fIkeypad\fP mode is on for the window,
 100 \fBKEY_LEFT\fP and \fBKEY_BACKSPACE\fP
 101 are both considered equivalent to the user's erase character.
 102 .bP
 103 The \fIkill\fP character (e.g., \fB^U\fP) erases the entire buffer,
 104 leaving the cursor at the beginning of the buffer.
 105 .PP
 106 Characters input are echoed only if \fBecho\fP is currently on.
 107 In that case,
 108 backspace is echoed as deletion of the previous character (typically a left
 109 motion).
 110 .SH RETURN VALUE
 111 All routines return the integer \fBERR\fP upon failure and an \fBOK\fP (SVr4
 112 specifies only \*(``an integer value other than \fBERR\fP\*('') upon successful
 113 completion.
 114 .PP
 115 X/Open defines no error conditions.
 116 .PP
 117 In this implementation,
 118 these functions return an error
 119 if the window pointer is null, or
 120 if its timeout expires without having any data.
 121 .PP
 122 This implementation provides an extension as well.
 123 If a \fBSIGWINCH\fP interrupts the function, it will return \fBKEY_RESIZE\fP
 124 rather than \fBOK\fP or \fBERR\fP.
 125 .PP
 126 Functions with a \*(``mv\*('' prefix first perform a cursor movement using
 127 \fBwmove\fP, and return an error if the position is outside the window,
 128 or if the window pointer is null.
 129 .SH NOTES
 130 Note that \fBgetstr\fP, \fBmvgetstr\fP, and \fBmvwgetstr\fP may be macros.
 131 .SH PORTABILITY
 132 These functions are described in the XSI Curses standard, Issue 4.
 133 They read single-byte characters only.
 134 The standard does not define any error conditions.
 135 This implementation returns \fBERR\fP if the window pointer is null,
 136 or if the lower-level \fBwgetch\fP(3X) call returns an \fBERR\fP.
 137 .PP
 138 SVr3 and early SVr4 curses implementations did not reject function keys;
 139 the SVr4.0 documentation claimed that \*(``special keys\*(''
 140 (such as function keys,
 141 \*(``home\*('' key,
 142 \*(``clear\*('' key,
 143 \fIetc\fP.) are \*(``interpreted\*('',
 144 without giving details.
 145 It lied.
 146 In fact, the \*(``character\*('' value appended to the
 147 string by those implementations was predictable but not useful
 148 (being, in fact, the low-order eight bits of the key's KEY_ value).
 149 .PP
 150 The functions \fBgetnstr\fP, \fBmvgetnstr\fP, and \fBmvwgetnstr\fP were
 151 present but not documented in SVr4.
 152 .PP
 153 X/Open Curses, Issue 5 (2007) stated that these functions
 154 \*(``read at most \fIn\fP bytes\*(''
 155 but did not state whether the terminating NUL is counted in that limit.
 156 X/Open Curses, Issue 7 (2009) changed that to say they
 157 \*(``read at most \fIn\fP\-1 bytes\*(''
 158 to allow for the terminating NUL.
 159 As of 2018, some implementations do, some do not count it:
 160 .bP
 161 ncurses 6.1 and PDCurses do not count the NUL in the given limit, while
 162 .bP
 163 Solaris SVr4 and NetBSD curses count the NUL as part of the limit.
 164 .bP
 165 Solaris xcurses provides both:
 166 its wide-character \fBwget_nstr\fP reserves a NUL,
 167 but its \fBwgetnstr\fP does not count the NUL consistently.
 168 .PP
 169 In SVr4 curses,
 170 a negative value of \fIn\fP tells \fBwgetnstr\fP to assume that the
 171 caller's buffer is large enough to hold the result,
 172 i.e., to act like \fBwgetstr\fP.
 173 X/Open Curses does not mention this
 174 (or anything related to negative or zero values of \fIn\fP),
 175 however most implementations
 176 use the feature, with different limits:
 177 .bP
 178 Solaris SVr4 curses and PDCurses limit the result to 255 bytes.
 179 Other Unix systems than Solaris are likely to use the same limit.
 180 .bP
 181 Solaris xcurses limits the result to \fBLINE_MAX\fP bytes.
 182 .bP
 183 NetBSD 7 assumes no particular limit for the result from \fBwgetstr\fP.
 184 However, it limits the \fBwgetnstr\fP parameter \fIn\fP to ensure
 185 that it is greater than zero.
 186 .IP
 187 A comment in NetBSD's source code states that this is specified in SUSv2.
 188 .bP
 189 ncurses (before 6.2) assumes no particular limit for the result
 190 from \fBwgetstr\fP, and treats the \fIn\fP parameter of \fBwgetnstr\fP
 191 like SVr4 curses.
 192 .bP
 193 ncurses 6.2 uses \fBLINE_MAX\fP,
 194 or a larger (system-dependent) value
 195 which the \fBsysconf\fP function may provide.
 196 If neither \fBLINE_MAX\fP or \fBsysconf\fP is available,
 197 ncurses uses the POSIX value for \fBLINE_MAX\fP (a 2048 byte limit).
 198 In either case, it reserves a byte for the terminating NUL.
 199 .PP
 200 Although \fBgetnstr\fP is equivalent to a series of calls to \fBgetch\fP,
 201 it also makes changes to the curses modes to allow simple editing of
 202 the input buffer:
 203 .bP
 204 \fBgetnstr\fP saves the current value of the \fBnl\fP, \fBecho\fP,
 205 \fBraw\fP and \fBcbreak\fP modes, and sets
 206 \fBnl\fP,
 207 \fBnoecho\fP,
 208 \fBnoraw\fP, and
 209 \fBcbreak\fP.
 210 .IP
 211 \fBgetnstr\fP handles the echoing of characters,
 212 rather than relying on the caller to set an appropriate mode.
 213 .bP
 214 It also obtains the \fIerase\fP and \fIkill\fP characters
 215 from \fBerasechar\fP and \fBkillchar\fP, respectively.
 216 .bP
 217 On return, \fBgetnstr\fP restores the modes to their previous values.
 218 .PP
 219 Other implementations differ in their treatment of special characters:
 220 .bP
 221 While they may set the \fIecho\fP mode,
 222 other implementations do not modify the \fIraw\fP mode,
 223 They may take the \fIcbreak\fP
 224 mode set by the caller into account when deciding whether to handle
 225 echoing within \fBgetnstr\fP or as a side-effect of the \fBgetch\fP calls.
 226 .bP
 227 The original ncurses (as \fIpcurses\fP in 1986) set \fBnoraw\fP and \fBcbreak\fP
 228 when accepting input for \fBgetnstr\fP.
 229 That may have been done to make function- and cursor-keys work;
 230 it is not necessary with ncurses.
 231 .IP
 232 Since 1995, ncurses has provided signal handlers for INTR and QUIT
 233 (e.g., \fB^C\fP or \fB^\\\fP).
 234 With the \fBnoraw\fP and \fBcbreak\fP settings,
 235 those may catch a signal and stop the program,
 236 where other implementations allow one to enter those characters in the buffer.
 237 .bP
 238 Starting in 2021 (ncurses 6.3), \fBgetnstr\fP sets \fBraw\fP,
 239 rather than \fBnoraw\fP and \fBcbreak\fP for better compatibility with
 240 SVr4-curses, e.g., allowing one to enter a \fB^C\fP into the buffer.
 241 .SH SEE ALSO
 242 \fBcurses\fP(3X),
 243 \fBcurs_getch\fP(3X),
 244 \fBcurs_termattrs\fP(3X),
 245 \fBcurs_variables\fP(3X).