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.97 2024/06/08 20:26:46 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-06-08 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-06-08 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> or <STRONG><A HREF="curs_inopts.3x.html">noraw(3x)</A></STRONG> has
  88        been called, it occurs when the next newline  is  read.   (Because  the
  89        terminal's  normal  or  "cooked" mode is line-buffered, multiple <STRONG>wgetch</STRONG>
  90        calls  may  then  be  necessary  to  empty  the   input   queue.)    If
  91        <STRONG><A HREF="curs_inopts.3x.html">halfdelay(3x)</A></STRONG> has been called, <EM>curses</EM> waits until input is available or
  92        the specified delay elapses.
  93
  94        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
  95        the returned character <EM>c</EM> to the window (at the cursor position) per the
  96        following rules.
  97
  98        <STRONG>o</STRONG>   If <EM>c</EM> matches the terminal's erase  character  (see  <STRONG><A HREF="curs_termattrs.3x.html">erasechar(3x)</A></STRONG>),
  99            the  cursor  moves  leftward  one  position and the new position is
 100            erased as if <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
 101            window's   keypad   mode  is  enabled  (see  below),  <STRONG>KEY_LEFT</STRONG>  and
 102            <STRONG>KEY_BACKSPACE</STRONG> are handled the same way.
 103
 104        <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>.
 105
 106        <STRONG>o</STRONG>   If the window <EM>win</EM> has been moved or modified since the last call to
 107            <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, <EM>curses</EM> calls <STRONG>wrefresh</STRONG> on it.
 108
 109        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
 110        the character code for line feed instead.
 111
 112
 113 </PRE><H3><a name="h3-Keypad-Mode">Keypad Mode</a></H3><PRE>
 114        To <EM>curses</EM>, key strokes not from the alphabetic section of the  keyboard
 115        (those    corresponding    to    the    ECMA-6    character    set--see
 116        <STRONG>ascii(7)</STRONG>--optionally modified by either the control or shift keys)  are
 117        treated as <EM>function</EM> keys.  (In <EM>curses</EM>, the term "function key" includes
 118        but is not limited to keycaps engraved with "F1", "PF1",  and  so  on.)
 119        If  the  window  is  in  keypad  mode,  these  produce  a  numeric code
 120        corresponding to the <STRONG>KEY_</STRONG> symbols listed in subsection "Predefined  Key
 121        Codes"  below;  otherwise,  they transmit a sequence of codes typically
 122        starting with the escape character, and which must  be  collected  with
 123        multiple <STRONG>wgetch</STRONG> calls.
 124
 125        <STRONG>o</STRONG>   The  <EM>curses.h</EM>  header  file  declares many <EM>predefined</EM> <EM>function</EM> <EM>keys</EM>
 126            whose names begin with <STRONG>KEY_</STRONG>; these object-like macros  have  values
 127            outside the range of eight-bit character codes.
 128
 129        <STRONG>o</STRONG>   In   <EM>ncurses</EM>,   <EM>user-defined</EM>  <EM>function</EM>  <EM>keys</EM>  are  configured  with
 130            <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>; they have no names, but are also expected  to  have
 131            values outside the range of eight-bit codes.
 132
 133        A  variable  intended  to hold a function key code must thus be of type
 134        <EM>short</EM> or larger.
 135
 136        Most terminals one encounters follow the ECMA-48  standard  insofar  as
 137        their  function  keys  produce  character  sequences  prefixed with the
 138        escape character ESC.  This fact implies that <EM>curses</EM> cannot distinguish
 139        a  user's  press  of  the  escape  key (assuming it sends ESC) from the
 140        beginning of a function key's character sequence without waiting to see
 141        if,  and  how  soon,  further input arrives.  When <EM>curses</EM> reads such an
 142        ambiguous character, it sets a timer.  If the remainder of the sequence
 143        does  not  arrive within the designated time, <STRONG>wgetch</STRONG> returns the prefix
 144        character; otherwise, it returns the function key code corresponding to
 145        the unique sequence defined by the terminal.  Consequently, a user of a
 146        <EM>curses</EM> application may experience a  delay  after  the  escape  key  is
 147        pressed  while <EM>curses</EM> disambiguates the input; see section "EXTENSIONS"
 148        below.  If the window is in "no time-out"  mode,  the  timer  does  not
 149        expire;  it  is  an infinite (or very large) value.  See <STRONG><A HREF="notimeout.3x.html">notimeout(3x)</A></STRONG>.
 150        Because function key sequences usually begin with ESC, the terminal may
 151        appear  to  hang  in no time-out mode after the user presses the escape
 152        key.  Generally, further typing "awakens" <EM>curses</EM>.
 153
 154
 155 </PRE><H3><a name="h3-Ungetting-Characters">Ungetting Characters</a></H3><PRE>
 156        <STRONG>ungetch</STRONG> places <EM>c</EM> into the input queue to be returned by the  next  call
 157        to <STRONG>wgetch</STRONG>.  A single input queue serves all windows associated with the
 158        terminal.
 159
 160
 161 </PRE><H3><a name="h3-Predefined-Key-Codes">Predefined Key Codes</a></H3><PRE>
 162        The header file <EM>curses.h</EM> defines the following function key codes.
 163
 164        <STRONG>o</STRONG>   Except for the special case of <STRONG>KEY_RESIZE</STRONG>, a window's  keypad  mode
 165            must be enabled for <STRONG>wgetch</STRONG> to read these codes from it.
 166
 167        <STRONG>o</STRONG>   Not  all  of  these  are  necessarily  supported  on any particular
 168            terminal.
 169
 170        <STRONG>o</STRONG>   The  naming  convention  may  seem  obscure,  with  some   apparent
 171            misspellings  (such  as "RSUME" for "resume"); the names correspond
 172            to  the  <EM>terminfo</EM>  capability  names  for  the   keys,   and   were
 173            standardized  before  the  IBM  PC/AT  keyboard  layout  achieved a
 174            dominant position in industry.
 175
 176               <STRONG>Symbol</STRONG>          <STRONG>Key</STRONG> <STRONG>name</STRONG>
 177               -----------------------------------------------------------------
 178               <STRONG>KEY_BREAK</STRONG>       Break key
 179               <STRONG>KEY_DOWN</STRONG>
 180               <STRONG>KEY_UP</STRONG>          Arrow keys
 181               <STRONG>KEY_LEFT</STRONG>
 182               <STRONG>KEY_RIGHT</STRONG>
 183
 184               <STRONG>KEY_HOME</STRONG>        Home key (upward+left arrow)
 185               <STRONG>KEY_BACKSPACE</STRONG>   Backspace
 186               <STRONG>KEY_F0</STRONG>          Function keys; space for 64 keys is reserved
 187               <STRONG>KEY_F(</STRONG><EM>n</EM><STRONG>)</STRONG>        Function key <EM>n</EM> where 0 &lt;= <EM>n</EM> &lt;= 63
 188               <STRONG>KEY_DL</STRONG>          Delete line
 189               <STRONG>KEY_IL</STRONG>          Insert line
 190               <STRONG>KEY_DC</STRONG>          Delete character
 191               <STRONG>KEY_IC</STRONG>          Insert character/Enter insert mode
 192               <STRONG>KEY_EIC</STRONG>         Exit insert character mode
 193               <STRONG>KEY_CLEAR</STRONG>       Clear screen
 194               <STRONG>KEY_EOS</STRONG>         Clear to end of screen
 195               <STRONG>KEY_EOL</STRONG>         Clear to end of line
 196               <STRONG>KEY_SF</STRONG>          Scroll one line forward
 197               <STRONG>KEY_SR</STRONG>          Scroll one line backward (reverse)
 198               <STRONG>KEY_NPAGE</STRONG>       Next page/Page up
 199               <STRONG>KEY_PPAGE</STRONG>       Previous page/Page down
 200               <STRONG>KEY_STAB</STRONG>        Set tab
 201               <STRONG>KEY_CTAB</STRONG>        Clear tab
 202               <STRONG>KEY_CATAB</STRONG>       Clear all tabs
 203               <STRONG>KEY_ENTER</STRONG>       Enter/Send
 204               <STRONG>KEY_SRESET</STRONG>      Soft (partial) reset
 205               <STRONG>KEY_RESET</STRONG>       (Hard) reset
 206               <STRONG>KEY_PRINT</STRONG>       Print/Copy
 207               <STRONG>KEY_LL</STRONG>          Home down/Bottom (lower left)
 208               <STRONG>KEY_A1</STRONG>          Upper left of keypad
 209               <STRONG>KEY_A3</STRONG>          Upper right of keypad
 210               <STRONG>KEY_B2</STRONG>          Center of keypad
 211               <STRONG>KEY_C1</STRONG>          Lower left of keypad
 212               <STRONG>KEY_C3</STRONG>          Lower right of keypad
 213               <STRONG>KEY_BTAB</STRONG>        Back tab key
 214               <STRONG>KEY_BEG</STRONG>         Beg(inning) key
 215               <STRONG>KEY_CANCEL</STRONG>      Cancel key
 216               <STRONG>KEY_CLOSE</STRONG>       Close key
 217               <STRONG>KEY_COMMAND</STRONG>     Cmd (command) key
 218               <STRONG>KEY_COPY</STRONG>        Copy key
 219               <STRONG>KEY_CREATE</STRONG>      Create key
 220               <STRONG>KEY_END</STRONG>         End key
 221               <STRONG>KEY_EXIT</STRONG>        Exit key
 222               <STRONG>KEY_FIND</STRONG>        Find key
 223               <STRONG>KEY_HELP</STRONG>        Help key
 224               <STRONG>KEY_MARK</STRONG>        Mark key
 225               <STRONG>KEY_MESSAGE</STRONG>     Message key
 226               <STRONG>KEY_MOUSE</STRONG>       Mouse event occurred
 227               <STRONG>KEY_MOVE</STRONG>        Move key
 228               <STRONG>KEY_NEXT</STRONG>        Next object key
 229               <STRONG>KEY_OPEN</STRONG>        Open key
 230               <STRONG>KEY_OPTIONS</STRONG>     Options key
 231               <STRONG>KEY_PREVIOUS</STRONG>    Previous object key
 232               <STRONG>KEY_REDO</STRONG>        Redo key
 233               <STRONG>KEY_REFERENCE</STRONG>   Ref(erence) key
 234               <STRONG>KEY_REFRESH</STRONG>     Refresh key
 235               <STRONG>KEY_REPLACE</STRONG>     Replace key
 236               <STRONG>KEY_RESIZE</STRONG>      Screen resized
 237               <STRONG>KEY_RESTART</STRONG>     Restart key
 238               <STRONG>KEY_RESUME</STRONG>      Resume key
 239               <STRONG>KEY_SAVE</STRONG>        Save key
 240               <STRONG>KEY_SELECT</STRONG>      Select key
 241               <STRONG>KEY_SUSPEND</STRONG>     Suspend key
 242               <STRONG>KEY_UNDO</STRONG>        Undo key
 243               -----------------------------------------------------------------
 244               <STRONG>KEY_SBEG</STRONG>        Shifted beginning key
 245               <STRONG>KEY_SCANCEL</STRONG>     Shifted cancel key
 246               <STRONG>KEY_SCOMMAND</STRONG>    Shifted command key
 247               <STRONG>KEY_SCOPY</STRONG>       Shifted copy key
 248               <STRONG>KEY_SCREATE</STRONG>     Shifted create key
 249
 250               <STRONG>KEY_SDC</STRONG>         Shifted delete character key
 251               <STRONG>KEY_SDL</STRONG>         Shifted delete line key
 252               <STRONG>KEY_SEND</STRONG>        Shifted end key
 253               <STRONG>KEY_SEOL</STRONG>        Shifted clear line key
 254               <STRONG>KEY_SEXIT</STRONG>       Shifted exit key
 255               <STRONG>KEY_SFIND</STRONG>       Shifted find key
 256               <STRONG>KEY_SHELP</STRONG>       Shifted help key
 257               <STRONG>KEY_SHOME</STRONG>       Shifted home key
 258               <STRONG>KEY_SIC</STRONG>         Shifted insert key
 259               <STRONG>KEY_SLEFT</STRONG>       Shifted left arrow key
 260               <STRONG>KEY_SMESSAGE</STRONG>    Shifted message key
 261               <STRONG>KEY_SMOVE</STRONG>       Shifted move key
 262               <STRONG>KEY_SNEXT</STRONG>       Shifted next object key
 263               <STRONG>KEY_SOPTIONS</STRONG>    Shifted options key
 264               <STRONG>KEY_SPREVIOUS</STRONG>   Shifted previous object key
 265               <STRONG>KEY_SPRINT</STRONG>      Shifted print key
 266               <STRONG>KEY_SREDO</STRONG>       Shifted redo key
 267               <STRONG>KEY_SREPLACE</STRONG>    Shifted replace key
 268               <STRONG>KEY_SRIGHT</STRONG>      Shifted right arrow key
 269               <STRONG>KEY_SRSUME</STRONG>      Shifted resume key
 270               <STRONG>KEY_SSAVE</STRONG>       Shifted save key
 271               <STRONG>KEY_SSUSPEND</STRONG>    Shifted suspend key
 272               <STRONG>KEY_SUNDO</STRONG>       Shifted undo key
 273
 274        Many keyboards feature a nine-key directional pad.
 275
 276                                    +-----+------+-------+
 277                                    | A1  |  up  |  A3   |
 278                                    +-----+------+-------+
 279                                    |left |  B2  | right |
 280                                    +-----+------+-------+
 281                                    | C1  | down |  C3   |
 282                                    +-----+------+-------+
 283        Two of the symbols in the list above do <EM>not</EM> correspond  to  a  physical
 284        key.
 285
 286        <STRONG>o</STRONG>   <STRONG>wgetch</STRONG>  returns  <STRONG>KEY_RESIZE</STRONG>,  even  if  the window's keypad mode is
 287            disabled, if <EM>ncurses</EM> has handled a <STRONG>SIGWINCH</STRONG> signal since <STRONG>wgetch</STRONG> was
 288            called; see <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> and <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>.
 289
 290        <STRONG>o</STRONG>   <STRONG>wgetch</STRONG>  returns <STRONG>KEY_MOUSE</STRONG> to indicate that a mouse event is pending
 291            collection; see <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>.  Receipt of this  code  requires  a
 292            window's  keypad  mode  to  be  enabled, because to interpret mouse
 293            input (as with with <STRONG>xterm(1)</STRONG>'s mouse protocol), <EM>ncurses</EM>  must  read
 294            an escape sequence, as with a function key.
 295
 296
 297 </PRE><H3><a name="h3-Testing-Key-Codes">Testing Key Codes</a></H3><PRE>
 298        In  <EM>ncurses</EM>,  <STRONG>has_key</STRONG>  returns  a  Boolean value indicating whether the
 299        terminal type recognizes its parameter as a key code value.   See  also
 300        <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>.
 301
 302
 303 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 304        Except  for  <STRONG>has_key</STRONG>,  these  functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on
 305        failure.
 306
 307        Functions taking a <EM>WINDOW</EM> pointer argument fail if the pointer is <STRONG>NULL</STRONG>.
 308
 309        Functions prefixed with "mv" first perform cursor movement and fail  if
 310        the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
 311
 312        <STRONG>wgetch</STRONG> also fails if
 313
 314        <STRONG>o</STRONG>   its timeout expires without any data arriving, or
 315
 316        <STRONG>o</STRONG>   execution  was  interrupted by a signal, in which case <STRONG>errno</STRONG> is set
 317            to <STRONG>EINTR</STRONG>.
 318
 319        <STRONG>ungetch</STRONG> fails if there is no more room in the input queue.
 320
 321        <STRONG>has_key</STRONG> returns <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>.
 322
 323
 324 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 325        <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be implemented as macros.
 326
 327        <EM>curses</EM> discourages assignment of the ESC key to a discrete function  by
 328        the programmer because the library requires a delay while it awaits the
 329        potential remainder of a terminal escape sequence.
 330
 331        Some key strokes are indistinguishable  from  control  characters;  for
 332        example,  <STRONG>KEY_ENTER</STRONG> may be the same as <STRONG>^M</STRONG>, and <STRONG>KEY_BACKSPACE</STRONG> may be the
 333        same as <STRONG>^H</STRONG> or <STRONG>^?</STRONG>.  Consult the <EM>terminfo</EM> entry for the terminal type  to
 334        determine  whether  this  is  the  case;  see  <STRONG><A HREF="infocmp.1m.html">infocmp(1)</A></STRONG>.  Some <EM>curses</EM>
 335        implementations, including <EM>ncurses</EM>, honor the <EM>terminfo</EM> key definitions;
 336        others treat such control characters specially.
 337
 338        <EM>curses</EM>  distinguishes  the  Enter  keys  in  the alphabetic and numeric
 339        keypad sections of a keyboard because (most) terminals  do.   <STRONG>KEY_ENTER</STRONG>
 340        refers  to the key on the numeric keypad and, like other function keys,
 341        is reliably recognized only if the window's keypad mode is enabled.
 342
 343        <STRONG>o</STRONG>   The <EM>terminfo</EM> <STRONG>key_enter</STRONG> (<STRONG>kent</STRONG>) capability  describes  the  character
 344            (sequence)  sent  by  the  Enter  key  of  a terminal's numeric (or
 345            similar) keypad.
 346
 347        <STRONG>o</STRONG>   "Enter or send" is X/Open Curses's description of this key.
 348
 349        <EM>curses</EM> treats the Enter or Return key in the <EM>alphabetic</EM> section of  the
 350        keyboard differently.
 351
 352        <STRONG>o</STRONG>   It usually produces a control code for carriage return (<STRONG>^M</STRONG>) or line
 353            feed (<STRONG>^J</STRONG>).
 354
 355        <STRONG>o</STRONG>   Depending on the terminal mode  (raw,  cbreak,  or  "cooked"),  and
 356            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
 357            either a carriage return or line feed upon an Enter or  Return  key
 358            stroke.
 359
 360        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
 361        well-defined.
 362
 363        Historically, the list of key code macros above was influenced  by  the
 364        keyboard  of  the AT&amp;T 7300 (also known variously as the "3B1", "Safari
 365        4", and "UNIX PC"), a 1985 machine  rich  in  function  keys.   Today's
 366        computer  keyboards are based on that of the IBM PC/AT and tend to have
 367        fewer.  A <EM>curses</EM> application can expect such a keyboard to transmit key
 368        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>,
 369        <STRONG>KEY_PPAGE</STRONG> (Page Up), <STRONG>KEY_NPAGE</STRONG> (Page  Down),  <STRONG>KEY_IC</STRONG>  (Insert),  <STRONG>KEY_DC</STRONG>
 370        (Delete), and <STRONG>KEY_F(</STRONG><EM>n</EM><STRONG>)</STRONG> for 1 &lt;= <EM>n</EM> &lt;= 12.
 371
 372
 373 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 374        In <EM>ncurses</EM>, when a window's "no time-out" mode is <EM>not</EM> set, the <STRONG>ESCDELAY</STRONG>
 375        variable configures the duration of the timer used  to  disambiguate  a
 376        function  key character sequence from a series of key strokes beginning
 377        with ESC typed by the user; see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
 378
 379        <STRONG>has_key</STRONG> was designed for <EM>ncurses</EM>, and is  not  found  in  SVr4  <EM>curses</EM>,
 380        4.4BSD <EM>curses</EM>, or any other previous <EM>curses</EM> implementation.
 381
 382
 383 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 384        Applications employing <EM>ncurses</EM> extensions should condition their use on
 385        the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro.
 386
 387        Except as noted in section "EXTENSIONS" above, X/Open Curses,  Issue  4
 388        describes these functions.  It specifies no error conditions for them.
 389
 390        <STRONG>wgetch</STRONG> reads only single-byte characters.
 391
 392        The  echo  behavior  of  these  functions on input of <STRONG>KEY_</STRONG> or backspace
 393        characters is not documented in SVr4 <EM>curses</EM>.
 394
 395        The behavior of <STRONG>wgetch</STRONG> in  the  presence  of  signal  handlers  is  not
 396        documented  in  SVr4  <EM>curses</EM>  and  is unspecified by X/Open Curses.  In
 397        historical <EM>curses</EM> implementations, it varied depending on  whether  the
 398        operating  system's  dispatch  of  a  signal to a handler interrupted a
 399        <STRONG>read(2)</STRONG> call in progress, and also (in some implementations) whether an
 400        input  timeout  or  non-blocking  mode had been set.  A portable <EM>curses</EM>
 401        application prepares  for  two  cases:  (a)  signal  receipt  does  not
 402        interrupt <STRONG>wgetch</STRONG>; or (b) signal receipt interrupts <STRONG>wgetch</STRONG> and causes it
 403        to return <STRONG>ERR</STRONG> with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>.
 404
 405        <STRONG>KEY_MOUSE</STRONG> is mentioned in X/Open Curses, along with a few related <EM>term-</EM>
 406        <EM>info</EM>  capabilities, but no higher-level functions use the feature.  The
 407        implementation in <EM>ncurses</EM> is an extension.
 408
 409        <STRONG>KEY_RESIZE</STRONG> and <STRONG>has_key</STRONG> are extensions first  implemented  for  <EM>ncurses</EM>.
 410        By  2022,  <EM>PDCurses</EM>  and  NetBSD  <EM>curses</EM>  had  added  them  along  with
 411        <STRONG>KEY_MOUSE</STRONG>.
 412
 413
 414 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 415        ECMA-6 "7-bit  coded  Character  Set"  &lt;https://ecma-international.org/
 416        publications-and-standards/standards/ecma-6/&gt;
 417
 418        ECMA-48   "Control   Functions  for  Coded  Character  Sets"  &lt;https://
 419        ecma-international.org/publications-and-standards/standards/ecma-48/&gt;
 420
 421        <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM>  library
 422        in its wide-character configuration (<EM>ncursesw</EM>).
 423
 424        <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>,
 425        <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>,
 426        <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>, <STRONG>ascii(7)</STRONG>
 427
 428
 429
 430 ncurses 6.5                       2024-06-08                    <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
 431 </PRE>
 432 <div class="nav">
 433 <ul>
 434 <li><a href="#h2-NAME">NAME</a></li>
 435 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 436 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 437 <ul>
 438 <li><a href="#h3-Reading-Characters">Reading Characters</a></li>
 439 <li><a href="#h3-Keypad-Mode">Keypad Mode</a></li>
 440 <li><a href="#h3-Ungetting-Characters">Ungetting Characters</a></li>
 441 <li><a href="#h3-Predefined-Key-Codes">Predefined Key Codes</a></li>
 442 <li><a href="#h3-Testing-Key-Codes">Testing Key Codes</a></li>
 443 </ul>
 444 </li>
 445 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 446 <li><a href="#h2-NOTES">NOTES</a></li>
 447 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 448 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 449 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 450 </ul>
 451 </div>
 452 </BODY>
 453 </HTML>