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.48 2023/09/30 21:38:11 tom Exp $
  31 .TH curs_getstr 3X 2023-09-30 "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 .SH NAME
  41 \fB\%getstr\fP,
  42 \fB\%getnstr\fP,
  43 \fB\%wgetstr\fP,
  44 \fB\%wgetnstr\fP,
  45 \fB\%mvgetstr\fP,
  46 \fB\%mvgetnstr\fP,
  47 \fB\%mvwgetstr\fP,
  48 \fB\%mvwgetnstr\fP \-
  49 accept character strings from \fIcurses\fR terminal keyboard
  50 .SH SYNOPSIS
  51 \fB#include <curses.h>\fP
  52 .sp
  53 \fBint getstr(char *\fIstr\fB);\fR
  54 .br
  55 \fBint getnstr(char *\fIstr\fB, int \fIn\fB);\fR
  56 .br
  57 \fBint wgetstr(WINDOW *\fIwin\fB, char *\fIstr\fB);\fR
  58 .br
  59 \fBint wgetnstr(WINDOW *\fIwin\fB, char *\fIstr\fB, int \fIn\fB);\fR
  60 .sp
  61 \fBint mvgetstr(int \fIy\fB, int \fIx\fB, char *\fIstr\fB);\fR
  62 .br
  63 \fBint mvwgetstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, char *\fIstr\fB);\fR
  64 .br
  65 \fBint mvgetnstr(int \fIy\fB, int \fIx\fB, char *\fIstr\fB, int \fIn\fB);\fR
  66 .br
  67 \fBint mvwgetnstr(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, char *\fIstr\fB, int \fIn\fB);\fR
  68 .SH DESCRIPTION
  69 The function
  70 \fBwgetnstr\fP
  71 is equivalent to a series of calls to
  72 \fBwgetch\fP(3X),
  73 until a newline or carriage return terminates the series:
  74 .bP
  75 The terminating character is not included in the returned string.
  76 .bP
  77 In all instances, the end of the string is terminated
  78 by a NUL.
  79 .bP
  80 The function stores the result in the area pointed to
  81 by the \fIstr\fP parameter.
  82 .bP
  83 The function reads at most \fIn\fP characters,
  84 thus preventing a possible overflow of the input buffer.
  85 .IP
  86 Any attempt to enter more characters
  87 (other than the terminating newline or carriage return)
  88 causes a beep.
  89 .IP
  90 Function keys also cause a beep and are ignored.
  91 .PP
  92 The user's \fIerase\fP and \fIkill\fP characters are interpreted:
  93 .bP
  94 The \fIerase\fP character (e.g., \fB^H\fP) erases the character
  95 at the end of the buffer, moving the cursor to the left.
  96 .IP
  97 If \fIkeypad\fP mode is on for the window,
  98 \fBKEY_LEFT\fP and \fBKEY_BACKSPACE\fP
  99 are both considered equivalent to the user's \fIerase\fP character.
 100 .bP
 101 The \fIkill\fP character (e.g., \fB^U\fP) erases the entire buffer,
 102 leaving the cursor at the beginning of the buffer.
 103 .PP
 104 Characters input are echoed only if \fBecho\fP is currently on.
 105 In that case,
 106 backspace is echoed as deletion of the previous character
 107 (typically a left motion).
 108 .PP
 109 The
 110 \fBgetnstr\fP,
 111 \fBmvgetnstr\fP,
 112 \fBmvwgetnstr\fP, and
 113 \fBwgetnstr\fP
 114 functions are identical
 115 to the
 116 \fBgetstr\fP,
 117 \fBmvgetstr\fP,
 118 \fBmvwgetstr\fP, and
 119 \fBwgetstr\fP
 120 functions, respectively,
 121 except that the
 122 \fB*n*\fP
 123 versions read at most
 124 \fIn\fP
 125 characters, letting the application prevent overflow of the
 126 input buffer.
 127 .SH NOTES
 128 Any of these functions other than
 129 \fBwgetnstr\fP
 130 may be macros.
 131 .PP
 132 Using
 133 \fBgetstr\fP,
 134 \fBmvgetstr\fP,
 135 \fBmvwgetstr\fP, or
 136 \fBwgetstr\fP
 137 to read a line that
 138 overflows the array pointed to by
 139 \fBstr\fP
 140 causes undefined
 141 results.
 142 The use of
 143 \fBgetnstr\fP,
 144 \fBmvgetnstr\fP,
 145 \fBmvwgetnstr\fP, or
 146 \fBwgetnstr\fP,
 147 respectively, is recommended.
 148 .SH RETURN VALUE
 149 All of these functions return the integer \fBOK\fP upon successful completion.
 150 (SVr4 specifies only \*(``an integer value other than \fBERR\fP\*('')
 151 If unsuccessful, they return \fBERR\fP.
 152 .PP
 153 X/Open defines no error conditions.
 154 .PP
 155 In this implementation,
 156 these functions return an error
 157 .bP
 158 if the window pointer is null,
 159 .bP
 160 if its timeout expires without having any data, or
 161 .bP
 162 if the associated call to
 163 \fBwgetch\fP
 164 failed.
 165 .PP
 166 This implementation provides an extension as well.
 167 If a \fBSIGWINCH\fP interrupts the function, it will return \fBKEY_RESIZE\fP
 168 rather than \fBOK\fP or \fBERR\fP.
 169 .PP
 170 Functions with a \*(``mv\*('' prefix first perform a cursor movement using
 171 \fBwmove\fP, and return an error if the position is outside the window,
 172 or if the window pointer is null.
 173 .SH PORTABILITY
 174 These functions are described in The Single Unix Specification, Version 2.
 175 No error conditions are defined.
 176 .PP
 177 This implementation returns \fBERR\fP if the window pointer is null,
 178 or if the lower-level \fBwgetch\fP(3X) call returns an \fBERR\fP.
 179 .PP
 180 SVr3 and early SVr4 curses implementations did not reject function keys;
 181 the SVr4.0 documentation claimed that \*(``special keys\*(''
 182 (such as function keys,
 183 \*(``home\*('' key,
 184 \*(``clear\*('' key,
 185 \fIetc\fP.) are \*(``interpreted\*('',
 186 without giving details.
 187 It lied.
 188 In fact, the \*(``character\*('' value appended to the
 189 string by those implementations was predictable but not useful
 190 (being, in fact, the low-order eight bits of the key's KEY_ value).
 191 .PP
 192 The functions \fBgetnstr\fP, \fBmvgetnstr\fP, and \fBmvwgetnstr\fP were
 193 present but not documented in SVr4.
 194 .PP
 195 X/Open Curses, Issue 5 (2007) stated that these functions
 196 \*(``read at most \fIn\fP bytes\*(''
 197 but did not state whether the terminating NUL is counted in that limit.
 198 X/Open Curses, Issue 7 (2009) changed that to say they
 199 \*(``read at most \fIn\fP\-1 bytes\*(''
 200 to allow for the terminating NUL.
 201 As of 2018, some implementations count it, some do not:
 202 .bP
 203 ncurses 6.1 and PDCurses do not count the NUL in the given limit, while
 204 .bP
 205 Solaris SVr4 and NetBSD curses count the NUL as part of the limit.
 206 .bP
 207 Solaris xcurses provides both:
 208 its wide-character \fBwget_nstr\fP reserves a NUL,
 209 but its \fBwgetnstr\fP does not count the NUL consistently.
 210 .PP
 211 In SVr4 curses,
 212 a negative value of \fIn\fP tells \fBwgetnstr\fP to assume that the
 213 caller's buffer is large enough to hold the result,
 214 i.e., to act like \fBwgetstr\fP.
 215 X/Open Curses does not mention this
 216 (or anything related to negative or zero values of \fIn\fP),
 217 however most implementations
 218 use the feature, with different limits:
 219 .bP
 220 Solaris SVr4 curses and PDCurses limit the result to 255 bytes.
 221 Other Unix systems than Solaris are likely to use the same limit.
 222 .bP
 223 Solaris xcurses limits the result to \fBLINE_MAX\fP bytes.
 224 .bP
 225 NetBSD 7 assumes no particular limit for the result from \fBwgetstr\fP.
 226 However, it limits the \fBwgetnstr\fP parameter \fIn\fP to ensure
 227 that it is greater than zero.
 228 .IP
 229 A comment in NetBSD's source code states that this is specified in SUSv2.
 230 .bP
 231 ncurses (before 6.2) assumes no particular limit for the result
 232 from \fBwgetstr\fP, and treats the \fIn\fP parameter of \fBwgetnstr\fP
 233 like SVr4 curses.
 234 .bP
 235 ncurses 6.2 uses \fBLINE_MAX\fP,
 236 or a larger (system-dependent) value
 237 which the \fBsysconf\fP function may provide.
 238 If neither \fBLINE_MAX\fP or \fBsysconf\fP is available,
 239 ncurses uses the POSIX value for \fBLINE_MAX\fP (a 2048 byte limit).
 240 In either case, it reserves a byte for the terminating NUL.
 241 .PP
 242 Although \fBgetnstr\fP is equivalent to a series of calls to \fBgetch\fP,
 243 it also makes changes to the curses modes to allow simple editing of
 244 the input buffer:
 245 .bP
 246 \fBgetnstr\fP saves the current value of the \fBnl\fP, \fBecho\fP,
 247 \fBraw\fP and \fBcbreak\fP modes, and sets
 248 \fBnl\fP,
 249 \fBnoecho\fP,
 250 \fBnoraw\fP, and
 251 \fBcbreak\fP.
 252 .IP
 253 \fBgetnstr\fP handles the echoing of characters,
 254 rather than relying on the caller to set an appropriate mode.
 255 .bP
 256 It also obtains the \fIerase\fP and \fIkill\fP characters
 257 from \fBerasechar\fP and \fBkillchar\fP, respectively.
 258 .bP
 259 On return, \fBgetnstr\fP restores the modes to their previous values.
 260 .PP
 261 Other implementations differ in their treatment of special characters:
 262 .bP
 263 While they may set the \fIecho\fP mode,
 264 other implementations do not modify the \fIraw\fP mode,
 265 They may take the \fIcbreak\fP
 266 mode set by the caller into account when deciding whether to handle
 267 echoing within \fBgetnstr\fP or as a side-effect of the \fBgetch\fP calls.
 268 .bP
 269 The original ncurses (as \fIpcurses\fP in 1986) set \fBnoraw\fP and \fBcbreak\fP
 270 when accepting input for \fBgetnstr\fP.
 271 That may have been done to make function- and cursor-keys work;
 272 it is not necessary with ncurses.
 273 .IP
 274 Since 1995, ncurses has provided signal handlers for INTR and QUIT
 275 (e.g., \fB^C\fP or \fB^\\\fP).
 276 With the \fBnoraw\fP and \fBcbreak\fP settings,
 277 those may catch a signal and stop the program,
 278 where other implementations allow one to enter those characters in the buffer.
 279 .bP
 280 Starting in 2021 (ncurses 6.3), \fBgetnstr\fP sets \fBraw\fP,
 281 rather than \fBnoraw\fP and \fBcbreak\fP for better compatibility with
 282 SVr4-curses, e.g., allowing one to enter a \fB^C\fP into the buffer.
 283 .SH SEE ALSO
 284 \fB\%curses\fP(3X),
 285 \fB\%curs_getch\fP(3X),
 286 \fB\%curs_termattrs\fP(3X),
 287 \fB\%curs_variables\fP(3X)