doc/html/man/curs_getch.3x.html

   1 <!--
   2   * t
   3   ****************************************************************************
   4   * Copyright 2018-2023,2024 Thomas E. Dickey                                *
   5   * Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
   6   *                                                                          *
   7   * Permission is hereby granted, free of charge, to any person obtaining a  *
   8   * copy of this software and associated documentation files (the            *
   9   * "Software"), to deal in the Software without restriction, including      *
  10   * without limitation the rights to use, copy, modify, merge, publish,      *
  11   * distribute, distribute with modifications, sublicense, and/or sell       *
  12   * copies of the Software, and to permit persons to whom the Software is    *
  13   * furnished to do so, subject to the following conditions:                 *
  14   *                                                                          *
  15   * The above copyright notice and this permission notice shall be included  *
  16   * in all copies or substantial portions of the Software.                   *
  17   *                                                                          *
  18   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  19   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  20   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  21   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  22   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  23   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  24   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  25   *                                                                          *
  26   * Except as contained in this notice, the name(s) of the above copyright   *
  27   * holders shall not be used in advertising or otherwise to promote the     *
  28   * sale, use or other dealings in this Software without prior written       *
  29   * authorization.                                                           *
  30   ****************************************************************************
  31   * @Id: curs_getch.3x,v 1.88 2024/05/11 20:39:53 tom Exp @
  32 -->
  33 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  34 <HTML>
  35 <HEAD>
  36 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  37 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  38 <TITLE>curs_getch 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
  39 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  40
  41 </HEAD>
  42 <BODY>
  43 <H1 class="no-header">curs_getch 3x 2024-05-11 ncurses 6.5 Library calls</H1>
  44 <PRE>
  45 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>                   Library calls                  <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
  46
  47
  48
  49
  50 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  51        <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, <STRONG>mvwgetch</STRONG>, <STRONG>ungetch</STRONG>, <STRONG>has_key</STRONG> - get (or push back)
  52        characters from <EM>curses</EM> terminal keyboard
  53
  54
  55 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  56        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  57
  58        <STRONG>int</STRONG> <STRONG>getch(void);</STRONG>
  59        <STRONG>int</STRONG> <STRONG>wgetch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG>
  60        <STRONG>int</STRONG> <STRONG>mvgetch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG>
  61        <STRONG>int</STRONG> <STRONG>mvwgetch(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>
  62
  63        <STRONG>int</STRONG> <STRONG>ungetch(int</STRONG> <EM>c</EM><STRONG>);</STRONG>
  64
  65        <EM>/*</EM> <EM>extension</EM> <EM>*/</EM>
  66        <STRONG>int</STRONG> <STRONG>has_key(int</STRONG> <EM>c</EM><STRONG>);</STRONG>
  67
  68
  69 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  70
  71 </PRE><H3><a name="h3-Reading-Characters">Reading Characters</a></H3><PRE>
  72        <STRONG>wgetch</STRONG> gathers a key event from the terminal keyboard associated with a
  73        <EM>curses</EM>   window  <EM>win</EM>.   <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>  describes  the  variants  of  this
  74        function.
  75
  76        When input is pending, <STRONG>wgetch</STRONG> returns an integer  identifying  the  key
  77        event; for alphanumeric and punctuation keys, this value corresponds to
  78        the character encoding used by the terminal.  Use of the control key as
  79        a  modifier,  by  holding  it down while pressing and releasing another
  80        key, often results in a distinct code.   The  behavior  of  other  keys
  81        depends  on whether <EM>win</EM> is in keypad mode; see subsection "Keypad Mode"
  82        below.
  83
  84        If no input is pending, then if the no-delay flag is set in the  window
  85        (see  <STRONG><A HREF="nodelay.3x.html">nodelay(3x)</A></STRONG>),  the  function returns <STRONG>ERR</STRONG>; otherwise, <EM>curses</EM> waits
  86        until the terminal has input.  If  <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG>  has  been  called,  this
  87        happens  after one character is read.  If <STRONG><A HREF="curs_inopts.3x.html">nocbreak(3x)</A></STRONG> has been called,
  88        it occurs when the next newline is read.   If  <STRONG><A HREF="curs_inopts.3x.html">halfdelay(3x)</A></STRONG>  has  been
  89        called,  <EM>curses</EM>  waits  until input is available or the specified delay
  90        elapses.
  91
  92        If <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG> has been called, and the window is not a pad, <EM>curses</EM> writes
  93        the returned character <EM>c</EM> to the window (at the cursor position) per the
  94        following rules.
  95
  96        <STRONG>o</STRONG>   If <EM>c</EM> matches the  terminal's  erase  character,  the  cursor  moves
  97            leftward  one  position  and  the  new  position  is  erased  as if
  98            <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> and then  <STRONG><A HREF="curs_delch.3x.html">wdelch(3x)</A></STRONG>  were  called.   When  the  window's
  99            keypad  mode is enabled (see below), <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> are
 100            handled the same way.
 101
 102        <STRONG>o</STRONG>   <EM>curses</EM> writes any other <EM>c</EM> to the window, as with <STRONG><A HREF="curs_addch.3x.html">wechochar(3x)</A></STRONG>.
 103
 104        <STRONG>o</STRONG>   If the window <EM>win</EM> has been moved or modified since the last call to
 105            <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, <EM>curses</EM> calls <STRONG>wrefresh</STRONG> on it.
 106
 107        If  <EM>c</EM>  is  a carriage return and <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> has been called, <STRONG>wgetch</STRONG> returns
 108        the character code for line feed instead.
 109
 110
 111 </PRE><H3><a name="h3-Keypad-Mode">Keypad Mode</a></H3><PRE>
 112        To <EM>curses</EM>, key strokes not from the alphabetic section of the  keyboard
 113        (those    corresponding    to    the    ECMA-6    character    set--see
 114        <STRONG>ascii(7)</STRONG>--optionally modified by either the control or shift keys)  are
 115        treated as <EM>function</EM> keys.  (In <EM>curses</EM>, the term "function key" includes
 116        but is not limited to keycaps engraved with "F1", "PF1",  and  so  on.)
 117        If  the  window  is  in  keypad  mode,  these  produce  a  numeric code
 118        corresponding to the <STRONG>KEY_</STRONG> symbols listed in subsection "Predefined  Key
 119        Codes"  below;  otherwise,  they transmit a sequence of codes typically
 120        starting with the escape character, and which must  be  collected  with
 121        multiple <STRONG>wgetch</STRONG> calls.
 122
 123        <STRONG>o</STRONG>   The  <EM>curses.h</EM>  header  file  declares many <EM>predefined</EM> <EM>function</EM> <EM>keys</EM>
 124            whose names begin with <STRONG>KEY_</STRONG>; these object-like macros  have  values
 125            outside the range of eight-bit character codes.
 126
 127        <STRONG>o</STRONG>   In   <EM>ncurses</EM>,   <EM>user-defined</EM>  <EM>function</EM>  <EM>keys</EM>  are  configured  with
 128            <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>; they have no names, but are also expected  to  have
 129            values outside the range of eight-bit codes.
 130
 131        A  variable  intended  to hold a function key code must thus be of type
 132        <EM>short</EM> or larger.
 133
 134        Most terminals one encounters follow the ECMA-48  standard  insofar  as
 135        their  function  keys  produce  character  sequences  prefixed with the
 136        escape character ESC.  This fact implies that <EM>curses</EM> cannot distinguish
 137        a  user's  press  of  the  escape  key (assuming it sends ESC) from the
 138        beginning of a function key's character sequence without waiting to see
 139        if,  and  how  soon,  further input arrives.  When <EM>curses</EM> reads such an
 140        ambiguous character, it sets a timer.  If the remainder of the sequence
 141        does  not  arrive within the designated time, <STRONG>wgetch</STRONG> returns the prefix
 142        character; otherwise, it returns the function key code corresponding to
 143        the unique sequence defined by the terminal.  Consequently, a user of a
 144        <EM>curses</EM> application may experience a delay  after  they  escape  key  is
 145        pressed  while <EM>curses</EM> disambiguates the input; see section "EXTENSIONS"
 146        below.  If the window is in "no time-out"  mode,  the  timer  does  not
 147        expire;  it  is  an infinite (or very large) value.  See <STRONG><A HREF="notimeout.3x.html">notimeout(3x)</A></STRONG>.
 148        Because function key sequences usually begin with ESC, the terminal may
 149        appear  to  hang  in no time-out mode after the user presses the escape
 150        key.  Generally, further typing "awakens" <EM>curses</EM>.
 151
 152
 153 </PRE><H3><a name="h3-Ungetting-Characters">Ungetting Characters</a></H3><PRE>
 154        <STRONG>ungetch</STRONG> places <EM>c</EM> into the input queue to be returned by the  next  call
 155        to <STRONG>wgetch</STRONG>.  A single input queue serves all windows associated with the
 156        terminal.
 157
 158
 159 </PRE><H3><a name="h3-Predefined-Key-Codes">Predefined Key Codes</a></H3><PRE>
 160        The header file <EM>curses.h</EM> defines the following function key codes.
 161
 162        <STRONG>o</STRONG>   Except for the special case of <STRONG>KEY_RESIZE</STRONG>, a window's  keypad  mode
 163            must be enabled for <STRONG>wgetch</STRONG> to read these codes from it.
 164
 165        <STRONG>o</STRONG>   Not  all  of  these  are  necessarily  supported  on any particular
 166            terminal.
 167
 168        <STRONG>o</STRONG>   The  naming  convention  may  seem  obscure,  with  some   apparent
 169            misspellings  (such  as "RSUME" for "resume"); the names correspond
 170            to  the  <EM>terminfo</EM>  capability  names  for  the   keys,   and   were
 171            standardized  before  the  IBM  PC/AT  keyboard  layout  achieved a
 172            dominant position in industry.
 173
 174               <STRONG>Symbol</STRONG>          <STRONG>Key</STRONG> <STRONG>name</STRONG>
 175               -----------------------------------------------------------------
 176               <STRONG>KEY_BREAK</STRONG>       Break key
 177               <STRONG>KEY_DOWN</STRONG>
 178               <STRONG>KEY_UP</STRONG>          Arrow keys
 179               <STRONG>KEY_LEFT</STRONG>
 180               <STRONG>KEY_RIGHT</STRONG>
 181               <STRONG>KEY_HOME</STRONG>        Home key (upward+left arrow)
 182               <STRONG>KEY_BACKSPACE</STRONG>   Backspace
 183
 184               <STRONG>KEY_F0</STRONG>          Function keys; space for 64 keys is reserved
 185               <STRONG>KEY_F(</STRONG><EM>n</EM><STRONG>)</STRONG>        Function key <EM>n</EM> where 0 &lt;= <EM>n</EM> &lt;= 63
 186               <STRONG>KEY_DL</STRONG>          Delete line
 187               <STRONG>KEY_IL</STRONG>          Insert line
 188               <STRONG>KEY_DC</STRONG>          Delete character
 189               <STRONG>KEY_IC</STRONG>          Insert character/Enter insert mode
 190               <STRONG>KEY_EIC</STRONG>         Exit insert character mode
 191               <STRONG>KEY_CLEAR</STRONG>       Clear screen
 192               <STRONG>KEY_EOS</STRONG>         Clear to end of screen
 193               <STRONG>KEY_EOL</STRONG>         Clear to end of line
 194               <STRONG>KEY_SF</STRONG>          Scroll one line forward
 195               <STRONG>KEY_SR</STRONG>          Scroll one line backward (reverse)
 196               <STRONG>KEY_NPAGE</STRONG>       Next page/Page up
 197               <STRONG>KEY_PPAGE</STRONG>       Previous page/Page down
 198               <STRONG>KEY_STAB</STRONG>        Set tab
 199               <STRONG>KEY_CTAB</STRONG>        Clear tab
 200               <STRONG>KEY_CATAB</STRONG>       Clear all tabs
 201               <STRONG>KEY_ENTER</STRONG>       Enter/Send
 202               <STRONG>KEY_SRESET</STRONG>      Soft (partial) reset
 203               <STRONG>KEY_RESET</STRONG>       (Hard) reset
 204               <STRONG>KEY_PRINT</STRONG>       Print/Copy
 205               <STRONG>KEY_LL</STRONG>          Home down/Bottom (lower left)
 206               <STRONG>KEY_A1</STRONG>          Upper left of keypad
 207               <STRONG>KEY_A3</STRONG>          Upper right of keypad
 208               <STRONG>KEY_B2</STRONG>          Center of keypad
 209               <STRONG>KEY_C1</STRONG>          Lower left of keypad
 210               <STRONG>KEY_C3</STRONG>          Lower right of keypad
 211               <STRONG>KEY_BTAB</STRONG>        Back tab key
 212               <STRONG>KEY_BEG</STRONG>         Beg(inning) key
 213               <STRONG>KEY_CANCEL</STRONG>      Cancel key
 214               <STRONG>KEY_CLOSE</STRONG>       Close key
 215               <STRONG>KEY_COMMAND</STRONG>     Cmd (command) key
 216               <STRONG>KEY_COPY</STRONG>        Copy key
 217               <STRONG>KEY_CREATE</STRONG>      Create key
 218               <STRONG>KEY_END</STRONG>         End key
 219               <STRONG>KEY_EXIT</STRONG>        Exit key
 220               <STRONG>KEY_FIND</STRONG>        Find key
 221               <STRONG>KEY_HELP</STRONG>        Help key
 222               <STRONG>KEY_MARK</STRONG>        Mark key
 223               <STRONG>KEY_MESSAGE</STRONG>     Message key
 224               <STRONG>KEY_MOUSE</STRONG>       Mouse event occurred
 225               <STRONG>KEY_MOVE</STRONG>        Move key
 226               <STRONG>KEY_NEXT</STRONG>        Next object key
 227               <STRONG>KEY_OPEN</STRONG>        Open key
 228               <STRONG>KEY_OPTIONS</STRONG>     Options key
 229               <STRONG>KEY_PREVIOUS</STRONG>    Previous object key
 230               <STRONG>KEY_REDO</STRONG>        Redo key
 231               <STRONG>KEY_REFERENCE</STRONG>   Ref(erence) key
 232               <STRONG>KEY_REFRESH</STRONG>     Refresh key
 233               <STRONG>KEY_REPLACE</STRONG>     Replace key
 234               <STRONG>KEY_RESIZE</STRONG>      Screen resized
 235               <STRONG>KEY_RESTART</STRONG>     Restart key
 236               <STRONG>KEY_RESUME</STRONG>      Resume key
 237               <STRONG>KEY_SAVE</STRONG>        Save key
 238               <STRONG>KEY_SELECT</STRONG>      Select key
 239               <STRONG>KEY_SUSPEND</STRONG>     Suspend key
 240               <STRONG>KEY_UNDO</STRONG>        Undo key
 241               -----------------------------------------------------------------
 242               <STRONG>KEY_SBEG</STRONG>        Shifted beginning key
 243               <STRONG>KEY_SCANCEL</STRONG>     Shifted cancel key
 244               <STRONG>KEY_SCOMMAND</STRONG>    Shifted command key
 245               <STRONG>KEY_SCOPY</STRONG>       Shifted copy key
 246               <STRONG>KEY_SCREATE</STRONG>     Shifted create key
 247               <STRONG>KEY_SDC</STRONG>         Shifted delete character key
 248               <STRONG>KEY_SDL</STRONG>         Shifted delete line key
 249
 250               <STRONG>KEY_SEND</STRONG>        Shifted end key
 251               <STRONG>KEY_SEOL</STRONG>        Shifted clear line key
 252               <STRONG>KEY_SEXIT</STRONG>       Shifted exit key
 253               <STRONG>KEY_SFIND</STRONG>       Shifted find key
 254               <STRONG>KEY_SHELP</STRONG>       Shifted help key
 255               <STRONG>KEY_SHOME</STRONG>       Shifted home key
 256               <STRONG>KEY_SIC</STRONG>         Shifted insert key
 257               <STRONG>KEY_SLEFT</STRONG>       Shifted left arrow key
 258               <STRONG>KEY_SMESSAGE</STRONG>    Shifted message key
 259               <STRONG>KEY_SMOVE</STRONG>       Shifted move key
 260               <STRONG>KEY_SNEXT</STRONG>       Shifted next object key
 261               <STRONG>KEY_SOPTIONS</STRONG>    Shifted options key
 262               <STRONG>KEY_SPREVIOUS</STRONG>   Shifted previous object key
 263               <STRONG>KEY_SPRINT</STRONG>      Shifted print key
 264               <STRONG>KEY_SREDO</STRONG>       Shifted redo key
 265               <STRONG>KEY_SREPLACE</STRONG>    Shifted replace key
 266               <STRONG>KEY_SRIGHT</STRONG>      Shifted right arrow key
 267               <STRONG>KEY_SRSUME</STRONG>      Shifted resume key
 268               <STRONG>KEY_SSAVE</STRONG>       Shifted save key
 269               <STRONG>KEY_SSUSPEND</STRONG>    Shifted suspend key
 270               <STRONG>KEY_SUNDO</STRONG>       Shifted undo key
 271
 272        Many keyboards feature a nine-key directional pad.
 273
 274                                    +-----+------+-------+
 275                                    | A1  |  up  |  A3   |
 276                                    +-----+------+-------+
 277                                    |left |  B2  | right |
 278                                    +-----+------+-------+
 279                                    | C1  | down |  C3   |
 280                                    +-----+------+-------+
 281        Two of the symbols in the list above do <EM>not</EM> correspond  to  a  physical
 282        key.
 283
 284        <STRONG>o</STRONG>   <STRONG>wgetch</STRONG>  returns  <STRONG>KEY_RESIZE</STRONG>,  even  if  the window's keypad mode is
 285            disabled, when <EM>ncurses</EM> handles a <STRONG>SIGWINCH</STRONG> signal;  see  <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG>
 286            and <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>.
 287
 288        <STRONG>o</STRONG>   <STRONG>wgetch</STRONG>  returns <STRONG>KEY_MOUSE</STRONG> to indicate that a mouse event is pending
 289            collection; see <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>.  Receipt of this  code  requires  a
 290            window's  keypad  mode  to  be  enabled, because to interpret mouse
 291            input (as with with <STRONG>xterm(1)</STRONG>'s mouse prototocol), <EM>ncurses</EM> must read
 292            an escape sequence, as with a function key.
 293
 294
 295 </PRE><H3><a name="h3-Testing-Key-Codes">Testing Key Codes</a></H3><PRE>
 296        In  <EM>ncurses</EM>,  <STRONG>has_key</STRONG>  returns  a  Boolean value indicating whether the
 297        terminal type recognizes its parameter as a key code value.   See  also
 298        <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> and <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>.
 299
 300
 301 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 302        Except  for  <STRONG>has_key</STRONG>,  these  functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on
 303        failure.
 304
 305        Functions taking a <EM>WINDOW</EM> pointer argument fail if the pointer is <STRONG>NULL</STRONG>.
 306
 307        Functions prefixed with "mv" first perform cursor movement and fail  if
 308        the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
 309
 310        <STRONG>wgetch</STRONG> also fails if
 311
 312        <STRONG>o</STRONG>   its timeout expires without any data arriving, or
 313
 314        <STRONG>o</STRONG>   execution  was  interrupted by a signal, in which case <STRONG>errno</STRONG> is set
 315            to <STRONG>EINTR</STRONG>.
 316
 317        <STRONG>ungetch</STRONG> fails if there is no more room in the input queue.
 318
 319        <STRONG>has_key</STRONG> returns <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>.
 320
 321
 322 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 323        <EM>curses</EM> discourages assignment of the ESC key to a discrete function  by
 324        the programmer because the library requires a delay while it awaits the
 325        potential remainder of a terminal escape sequence.
 326
 327        Some key strokes are indistinguishable  from  control  characters;  for
 328        example,  <STRONG>KEY_ENTER</STRONG> may be the same as <STRONG>^M</STRONG>, and <STRONG>KEY_BACKSPACE</STRONG> may be the
 329        same as <STRONG>^H</STRONG> or <STRONG>^?</STRONG>.  Consult the terminal's <EM>terminfo</EM> entry  to  determine
 330        whether this is the case; see <STRONG><A HREF="infocmp.1m.html">infocmp(1)</A></STRONG>.  Some <EM>curses</EM> implementations,
 331        including <EM>ncurses</EM>, honor the <EM>terminfo</EM>  key  definitions;  others  treat
 332        such control characters specially.
 333
 334        <EM>curses</EM>  distinguishes  the  Enter  keys  in  the alphabetic and numeric
 335        keypad sections of a keyboard because (most) terminals  do.   <STRONG>KEY_ENTER</STRONG>
 336        refers  to the key on the numeric keypad and, like other function keys,
 337        is reliably recognized only if the window's keypad mode is enabled.
 338
 339        <STRONG>o</STRONG>   The <EM>terminfo</EM> <STRONG>key_enter</STRONG> (<STRONG>kent</STRONG>) capability  describes  the  character
 340            (sequence)  sent  by  the  Enter  key  of  a terminal's numeric (or
 341            similar) keypad.
 342
 343        <STRONG>o</STRONG>   "Enter or send" is X/Open Curses's description of this key.
 344
 345        <EM>curses</EM> treats the Enter or Return key in the <EM>alphabetic</EM> section of  the
 346        keyboard differently.
 347
 348        <STRONG>o</STRONG>   It usually produces a control code for carriage return (<STRONG>^M</STRONG>) or line
 349            feed (<STRONG>^J</STRONG>).
 350
 351        <STRONG>o</STRONG>   Depending on the terminal mode  (raw,  cbreak,  or  "cooked"),  and
 352            whether  <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG>  or  <STRONG><A HREF="curs_inopts.3x.html">nonl(3x)</A></STRONG>  has  been  called, <STRONG>wgetch</STRONG> may return
 353            either a carriage return or line feed upon an Enter or  Return  key
 354            stroke.
 355
 356        Use  of  <STRONG>wgetch</STRONG> with <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG> and neither <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> nor <STRONG><A HREF="curs_inopts.3x.html">raw(3x)</A></STRONG> is not
 357        well-defined.
 358
 359        Historically, the list of key code macros above was influenced  by  the
 360        function-key-rich  keyboard  of  the AT&amp;T 7300 (also known variously as
 361        the "3B1", "Safari  4",  and  "UNIX  PC"),  a  1985  machine.   Today's
 362        computer  keyboards  are  based  that of the IBM PC/AT and tend to have
 363        fewer.  A <EM>curses</EM> application can expect such a keyboard to transmit key
 364        codes   <STRONG>KEY_UP</STRONG>,   <STRONG>KEY_DOWN</STRONG>,  <STRONG>KEY_LEFT</STRONG>,  <STRONG>KEY_RIGHT</STRONG>,  <STRONG>KEY_HOME</STRONG>,  <STRONG>KEY_END</STRONG>,
 365        <STRONG>KEY_PPAGE</STRONG> (Page Up), <STRONG>KEY_NPAGE</STRONG> (Page  Down),  <STRONG>KEY_IC</STRONG>  (Insert),  <STRONG>KEY_DC</STRONG>
 366        (Delete), and <STRONG>KEY_F(</STRONG><EM>n</EM><STRONG>)</STRONG> for 1 &lt;= <EM>n</EM> &lt;= 12.
 367
 368        <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be implemented as macros.
 369
 370
 371 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 372        In <EM>ncurses</EM>, when a window's "no time-out" mode is <EM>not</EM> set, the <STRONG>ESCDELAY</STRONG>
 373        variable configures the duration of the timer used  to  disambiguate  a
 374        function  key character sequence from a series of key strokes beginning
 375        with ESC typed by the user; see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
 376
 377        <STRONG>has_key</STRONG> was designed for <EM>ncurses</EM>, and is  not  found  in  SVr4  <EM>curses</EM>,
 378        4.4BSD <EM>curses</EM>, or any other previous <EM>curses</EM> implementation.
 379
 380
 381 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 382        Applications employing <EM>ncurses</EM> extensions should condition their use on
 383        the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro.
 384
 385        X/Open Curses, Issue 4 describes <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, <STRONG>mvwgetch</STRONG>,  and
 386        <STRONG>ungetch</STRONG>.  It specifies no error conditions for them.
 387
 388        <STRONG>wgetch</STRONG> reads only single-byte characters.
 389
 390        The  echo  behavior  of  these  functions on input of <STRONG>KEY_</STRONG> or backspace
 391        characters  was  not  specified  in  the  SVr4   documentation.    This
 392        description is adapted from X/Open Curses.
 393
 394        The   behavior  of  <STRONG>wgetch</STRONG>  in  the  presence  of  signal  handlers  is
 395        unspecified in the SVr4 documentation and X/Open Curses.  In historical
 396        <EM>curses</EM>  implementations,  it  varied depending on whether the operating
 397        system's dispatch of a signal to a handler interrupted a  <STRONG>read(2)</STRONG>  call
 398        in  progress,  and  also  (in  some  implementations)  whether an input
 399        timeout or non-blocking mode had been set.  Programmers concerned about
 400        portability  should  be  prepared  for  either of two cases: (a) signal
 401        receipt does not interrupt <STRONG>wgetch</STRONG>; or  (b)  signal  receipt  interrupts
 402        <STRONG>wgetch</STRONG> and causes it to return <STRONG>ERR</STRONG> with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>.
 403
 404        <STRONG>KEY_MOUSE</STRONG> is mentioned in X/Open Curses, along with a few related <EM>term-</EM>
 405        <EM>info</EM> capabilities, but no higher-level functions use the feature.   The
 406        implementation in <EM>ncurses</EM> is an extension.
 407
 408        <STRONG>KEY_RESIZE</STRONG>  and  <STRONG>has_key</STRONG>  are extensions first implemented for <EM>ncurses</EM>.
 409        By  2022,  <EM>PDCurses</EM>  and  NetBSD  <EM>curses</EM>  had  added  them  along  with
 410        <STRONG>KEY_MOUSE</STRONG>.
 411
 412
 413 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 414        <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>  describes comparable functions of the <EM>ncurses</EM> library
 415        in its wide-character configuration (<EM>ncursesw</EM>).
 416
 417        <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_inopts.3x.html">curs_inopts(3x)</A></STRONG>,     <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>,
 418        <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>,  <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,
 419        <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>, <STRONG>ascii(7)</STRONG>
 420
 421        ECMA-6 "7-bit  coded  Character  Set"  &lt;https://ecma-international.org/
 422        publications-and-standards/standards/ecma-6/&gt;
 423
 424        ECMA-48   "Control   Functions  for  Coded  Character  Sets"  &lt;https://
 425        ecma-international.org/publications-and-standards/standards/ecma-48/&gt;
 426
 427
 428
 429 ncurses 6.5                       2024-05-11                    <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
 430 </PRE>
 431 <div class="nav">
 432 <ul>
 433 <li><a href="#h2-NAME">NAME</a></li>
 434 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 435 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 436 <ul>
 437 <li><a href="#h3-Reading-Characters">Reading Characters</a></li>
 438 <li><a href="#h3-Keypad-Mode">Keypad Mode</a></li>
 439 <li><a href="#h3-Ungetting-Characters">Ungetting Characters</a></li>
 440 <li><a href="#h3-Predefined-Key-Codes">Predefined Key Codes</a></li>
 441 <li><a href="#h3-Testing-Key-Codes">Testing Key Codes</a></li>
 442 </ul>
 443 </li>
 444 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 445 <li><a href="#h2-NOTES">NOTES</a></li>
 446 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 447 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 448 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 449 </ul>
 450 </div>
 451 </BODY>
 452 </HTML>