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