doc/html/man/curs_getstr.3x.html

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2023,2024 Thomas E. Dickey                                *
   4   * Copyright 1998-2010,2017 Free Software Foundation, Inc.                  *
   5   *                                                                          *
   6   * Permission is hereby granted, free of charge, to any person obtaining a  *
   7   * copy of this software and associated documentation files (the            *
   8   * "Software"), to deal in the Software without restriction, including      *
   9   * without limitation the rights to use, copy, modify, merge, publish,      *
  10   * distribute, distribute with modifications, sublicense, and/or sell       *
  11   * copies of the Software, and to permit persons to whom the Software is    *
  12   * furnished to do so, subject to the following conditions:                 *
  13   *                                                                          *
  14   * The above copyright notice and this permission notice shall be included  *
  15   * in all copies or substantial portions of the Software.                   *
  16   *                                                                          *
  17   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  18   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  19   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  20   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  21   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  22   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  23   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  24   *                                                                          *
  25   * Except as contained in this notice, the name(s) of the above copyright   *
  26   * holders shall not be used in advertising or otherwise to promote the     *
  27   * sale, use or other dealings in this Software without prior written       *
  28   * authorization.                                                           *
  29   ****************************************************************************
  30   * @Id: curs_getstr.3x,v 1.67 2024/06/22 22:20:56 tom Exp @
  31 -->
  32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  33 <HTML>
  34 <HEAD>
  35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  36 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  37 <TITLE>curs_getstr 3x 2024-06-22 ncurses 6.5 Library calls</TITLE>
  38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  39
  40 </HEAD>
  41 <BODY>
  42 <H1 class="no-header">curs_getstr 3x 2024-06-22 ncurses 6.5 Library calls</H1>
  43 <PRE>
  44 <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>                  Library calls                 <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
  45
  46
  47
  48
  49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  50        <STRONG>getstr</STRONG>,  <STRONG>getnstr</STRONG>,  <STRONG>wgetstr</STRONG>,  <STRONG>wgetnstr</STRONG>,  <STRONG>mvgetstr</STRONG>, <STRONG>mvgetnstr</STRONG>, <STRONG>mvwgetstr</STRONG>,
  51        <STRONG>mvwgetnstr</STRONG> - accept character strings from <EM>curses</EM> terminal keyboard
  52
  53
  54 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  55        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  56
  57        <STRONG>int</STRONG> <STRONG>getstr(char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG>
  58        <STRONG>int</STRONG> <STRONG>wgetstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG>
  59        <STRONG>int</STRONG> <STRONG>mvgetstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG>
  60        <STRONG>int</STRONG> <STRONG>mvwgetstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG>
  61
  62        <STRONG>int</STRONG> <STRONG>getnstr(char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG>
  63        <STRONG>int</STRONG> <STRONG>wgetnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG>
  64        <STRONG>int</STRONG> <STRONG>mvgetnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG>
  65        <STRONG>int</STRONG> <STRONG>mvwgetnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG>
  66
  67
  68 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  69        <STRONG>wgetstr</STRONG> populates a  user-supplied  string  buffer  <EM>str</EM>  by  repeatedly
  70        calling  <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> with the <EM>win</EM> argument until a line feed or carriage
  71        return character is input.  The function
  72
  73        <STRONG>o</STRONG>   does not copy the terminating character to <EM>str</EM>;
  74
  75        <STRONG>o</STRONG>   always terminates <EM>str</EM> with a null character;
  76
  77        <STRONG>o</STRONG>   interprets  the   screen's   erase   and   kill   characters   (see
  78            <STRONG><A HREF="curs_termattrs.3x.html">erasechar(3x)</A></STRONG> and <STRONG><A HREF="curs_termattrs.3x.html">killchar(3x)</A></STRONG>);
  79
  80        <STRONG>o</STRONG>   recognizes  function  keys  only  if  the screen's keypad option is
  81            enabled (see <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG>);
  82
  83        <STRONG>o</STRONG>   treats the function keys <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> the same as the
  84            erase character; and
  85
  86        <STRONG>o</STRONG>   discards  function key inputs other than those treated as the erase
  87            character, calling <STRONG><A HREF="curs_beep.3x.html">beep(3x)</A></STRONG>.
  88
  89        The erase character replaces the character at the  end  of  the  buffer
  90        with  a  null character, while the kill character does the same for the
  91        entire buffer.
  92
  93        If the screen's echo option is enabled (see <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG>), <STRONG>wgetstr</STRONG>  updates
  94        <EM>win</EM> with <STRONG><A HREF="curs_addch.3x.html">wechochar(3x)</A></STRONG>.  Further,
  95
  96        <STRONG>o</STRONG>   the  erase  character and its function key synonyms move the cursor
  97            to the left, and
  98
  99        <STRONG>o</STRONG>   the kill character returns the cursor to where it was located  when
 100            <STRONG>wgetstr</STRONG> was called.
 101
 102        <STRONG>wgetnstr</STRONG>  is  similar,  but  reads  at  most  <EM>n</EM>  characters, aiding the
 103        application to avoid overrunning the buffer to which  <EM>str</EM>  points.   An
 104        attempt  to  input  more  than <EM>n</EM> characters (other than the terminating
 105        line feed or carriage return) is ignored with a beep.
 106
 107        <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of these functions.
 108
 109
 110 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 111        These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure.
 112
 113        In <EM>ncurses</EM>, they return <STRONG>ERR</STRONG> if
 114
 115        <STRONG>o</STRONG>   <EM>win</EM> is <STRONG>NULL</STRONG>, or
 116
 117        <STRONG>o</STRONG>   if an internal <STRONG>wgetch</STRONG> call fails.
 118
 119        Further, in <EM>ncurses</EM>, these functions return <STRONG>KEY_RESIZE</STRONG>  if  a  <STRONG>SIGWINCH</STRONG>
 120        event interrupts the function.
 121
 122        Functions  prefixed with "mv" first perform cursor movement and fail if
 123        the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
 124
 125
 126 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 127        All of these functions except <STRONG>wgetnstr</STRONG> may be implemented as macros.
 128
 129        Use of <STRONG>getstr</STRONG>, <STRONG>mvgetstr</STRONG>, <STRONG>mvwgetstr</STRONG>,  or  <STRONG>wgetstr</STRONG>  to  read  input  that
 130        overruns  the  buffer  pointed to by <EM>str</EM> causes undefined results.  Use
 131        their <STRONG>n</STRONG>-infixed counterpart functions instead.
 132
 133        While <STRONG>wgetnstr</STRONG> is conceptually a series of calls  to  <STRONG>wgetch</STRONG>,  it  also
 134        temporarily  changes  properties  of the <EM>curses</EM> screen to permit simple
 135        editing of the input buffer.  It saves  the  screen's  state  and  then
 136        calls  <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG>  and,  if  the  screen  was  in  normal  ("cooked") mode,
 137        <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG>.  Before returning, it  restores  the  saved  screen  state.
 138        Other   implementations  differ  in  detail,  affecting  which  control
 139        characters they can accept in the  buffer;  see  section  "PORTABILITY"
 140        below.
 141
 142
 143 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 144        The return value <STRONG>KEY_RESIZE</STRONG> is an <EM>ncurses</EM> extension.
 145
 146
 147 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 148        Applications employing <EM>ncurses</EM> extensions should condition their use on
 149        the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro.
 150
 151        X/Open Curses Issue 4 describes these functions.  It specifies no error
 152        conditions  for them, but indicates that <EM>wgetnstr</EM> and its variants read
 153        "the entire multi-byte sequence associated with a character" and "fail"
 154        if <EM>n</EM> and <EM>str</EM> together do not describe a buffer "large enough to contain
 155        any complete characters".   In  <EM>ncurses</EM>,  however,  <EM>wgetch</EM>  reads  only
 156        single-byte characters, so this scenario does not arise.
 157
 158        SVr4  <EM>curses</EM>  describes  a  successful return value only as "an integer
 159        value other than <STRONG>ERR</STRONG>".
 160
 161        SVr3 and early SVr4 <EM>curses</EM>  implementations  did  not  reject  function
 162        keys; the SVr4 documentation asserted that, like the screen's erase and
 163        kill characters, they were
 164
 165               interpreted, as well as any special keys (such as function keys,
 166               "home" key, "clear" key, <EM>etc.</EM>)
 167
 168        without  further  detail.   It  lied.   In  fact, the "character" value
 169        appended to the string by those implementations was predictable but not
 170        useful  --  being,  in fact, the low-order eight bits of the key code's
 171        <STRONG>KEY_</STRONG> constant value.  (The same language, unchanged except for styling,
 172        survived into X/Open Curses Issue 4, but disappeared from Issue 7.)
 173
 174        X/Open  Curses Issue 5 (2007) stated that these functions "read at most
 175        <EM>n</EM> bytes" but did not  state  whether  the  terminating  null  character
 176        counted  toward  that limit.  X/Open Curses Issue 7 (2009) changed that
 177        to say they "read at most <EM>n</EM>-1 bytes" to allow for the terminating  null
 178        character.  As of 2018, some implementations count it, some do not.
 179
 180        <STRONG>o</STRONG>   <EM>ncurses</EM> 6.1 and <EM>PDCurses</EM> do not count the null character toward the
 181            limit, while Solaris and NetBSD <EM>curses</EM> do.
 182
 183        <STRONG>o</STRONG>   Solaris  <EM>xcurses</EM>  offers   both   behaviors:   its   wide-character
 184            <EM>wgetn</EM><STRONG>_</STRONG><EM>wstr</EM>  reserves  room  for a wide null character, but its non-
 185            wide <EM>wgetnstr</EM> does not consistently count a null  character  toward
 186            the limit.
 187
 188        In SVr4 <EM>curses</EM>, a negative <EM>n</EM> tells <EM>wgetnstr</EM> to assume that the caller's
 189        buffer is large enough to hold the result; that is, the  function  then
 190        acts  like  <EM>wgetstr</EM>.   X/Open Curses does not mention this behavior (or
 191        anything  related  to  nonpositive  <EM>n</EM>  values),  however  most   <EM>curses</EM>
 192        libraries  implement  it.  Most implementations nevertheless enforce an
 193        upper limit on the count of bytes they write to the destination  buffer
 194        <EM>str</EM>.
 195
 196        <STRONG>o</STRONG>   BSD   <EM>curses</EM>   lacked  <EM>wgetnstr</EM>,  and  its  <EM>wgetstr</EM>  wrote  to  <EM>str</EM>
 197            unboundedly, as did that in SVr2.
 198
 199        <STRONG>o</STRONG>   <EM>PDCurses</EM>, and SVr3.1, SVr4, and Solaris <EM>curses</EM> limit both functions
 200            to  writing  256  bytes.  Other System V-based platforms likely use
 201            the same limit.
 202
 203        <STRONG>o</STRONG>   Solaris <EM>xcurses</EM> limits the write to <STRONG>LINE_MAX</STRONG> bytes.
 204
 205        <STRONG>o</STRONG>   NetBSD 7 <EM>curses</EM> imposes no particular limit on the  length  of  the
 206            write,  but does validate <EM>n</EM> to ensure that it is greater than zero.
 207            A comment in NetBSD's source  code  asserts  that  SUSv2  specifies
 208            this.
 209
 210        <STRONG>o</STRONG>   <EM>ncurses</EM>  prior  to 6.2 (2020) imposes no limit on the length of the
 211            write, and treats <EM>wgetnstr</EM>'s <EM>n</EM> parameter as SVr4 <EM>curses</EM> does.
 212
 213        <STRONG>o</STRONG>   <EM>ncurses</EM> 6.2 uses <STRONG>LINE_MAX</STRONG>  or  a  larger  (system-dependent)  value
 214            provided  by  <STRONG>sysconf(3)</STRONG>.   If  neither  <STRONG>LINE_MAX</STRONG>  nor  <EM>sysconf</EM>  is
 215            available, <EM>ncurses</EM>  uses  the  POSIX  minimum  value  for  <STRONG>LINE_MAX</STRONG>
 216            (2048).   In  either  case,  it reserves a byte for the terminating
 217            null character.
 218
 219        Implementations vary in their handling of input control characters.
 220
 221        <STRONG>o</STRONG>   While they may enable the screen's echo option, some do not take it
 222            out  of  raw  mode,  and  may  take  cbreak  mode into account when
 223            deciding whether to handle echoing within <EM>wgetnstr</EM> or to rely on it
 224            as a side effect of calling <EM>wgetch</EM>.
 225
 226        <STRONG>o</STRONG>   Originally,  <EM>ncurses</EM>, like its progenitor <EM>pcurses</EM>, had its <EM>wgetnstr</EM>
 227            call <EM>noraw</EM> and <EM>cbreak</EM> before accepting input.  That may  have  been
 228            done  to  make  function keys work; it is not necessary with modern
 229            <EM>ncurses</EM>.
 230
 231            Since 1995, <EM>ncurses</EM> has provided handlers for <STRONG>SIGINTR</STRONG>  and  <STRONG>SIGQUIT</STRONG>
 232            events,  which  are typically generated at the keyboard with <STRONG>^C</STRONG> and
 233            <STRONG>^\</STRONG> respectively.  In cbreak mode, those handlers catch a signal and
 234            stop   the  program,  whereas  other  implementations  write  those
 235            characters into the buffer.
 236
 237        <STRONG>o</STRONG>   Starting with <EM>ncurses</EM> 6.3 (2021), <EM>wgetnstr</EM> preserves  raw  mode  if
 238            the  screen  was  already  in that state, allowing one to enter the
 239            characters the terminal interprets as  interrupt  and  quit  events
 240            into the buffer, for better compatibility with SVr4 <EM>curses</EM>.
 241
 242
 243 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 244        4BSD (1980) <EM>curses</EM> introduced <EM>wgetstr</EM> along with its variants.
 245
 246        SVr3.1 (1987) added <EM>wgetnstr</EM>, but none of its variants.
 247
 248        X/Open  Curses  Issue  4  (1995)  specified  <EM>getnstr</EM>,  <EM>mvwgetnstr</EM>,  and
 249        <EM>mvgetnstr</EM>.
 250
 251
 252 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 253        <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library
 254        in its wide-character configuration (<EM>ncursesw</EM>).
 255
 256        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,     <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>,     <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>,    <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>,
 257        <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>,
 258
 259
 260
 261 ncurses 6.5                       2024-06-22                   <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
 262 </PRE>
 263 <div class="nav">
 264 <ul>
 265 <li><a href="#h2-NAME">NAME</a></li>
 266 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 267 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
 268 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 269 <li><a href="#h2-NOTES">NOTES</a></li>
 270 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 271 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 272 <li><a href="#h2-HISTORY">HISTORY</a></li>
 273 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 274 </ul>
 275 </div>
 276 </BODY>
 277 </HTML>