ncurses 6.0 - patch 20160910
[ncurses.git] / doc / html / man / curs_getch.3x.html
1 <!-- 
2   * t
3   ****************************************************************************
4   * Copyright (c) 1998-2015,2016 Free Software Foundation, Inc.              *
5   *                                                                          *
6   * Permission is hereby granted, free of charge, to any person obtaining a  *
7   * copy of this software and associated documentation files (the            *
8   * "Software"), to deal in the Software without restriction, including      *
9   * without limitation the rights to use, copy, modify, merge, publish,      *
10   * distribute, distribute with modifications, sublicense, and/or sell       *
11   * copies of the Software, and to permit persons to whom the Software is    *
12   * furnished to do so, subject to the following conditions:                 *
13   *                                                                          *
14   * The above copyright notice and this permission notice shall be included  *
15   * in all copies or substantial portions of the Software.                   *
16   *                                                                          *
17   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
18   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
19   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
20   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
21   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
22   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
23   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
24   *                                                                          *
25   * Except as contained in this notice, the name(s) of the above copyright   *
26   * holders shall not be used in advertising or otherwise to promote the     *
27   * sale, use or other dealings in this Software without prior written       *
28   * authorization.                                                           *
29   ****************************************************************************
30   * @Id: curs_getch.3x,v 1.48 2016/09/10 21:56:25 Leon.Winter Exp @
31 -->
32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
33 <HTML>
34 <HEAD>
35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
36 <meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
37 <TITLE>curs_getch 3x</TITLE>
38 <link rev=made href="mailto:bug-ncurses@gnu.org">
39 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
40 </HEAD>
41 <BODY>
42 <H1 class="no-header">curs_getch 3x</H1>
43 <PRE>
44 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>                                           <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
45
46
47
48
49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
50        <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, <STRONG>mvwgetch</STRONG>, <STRONG>ungetch</STRONG>, <STRONG>has_key</STRONG> - get
51        (or push back) characters from <STRONG>curses</STRONG> terminal keyboard
52
53
54 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
55        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
56
57        <STRONG>int</STRONG> <STRONG>getch(void);</STRONG>
58        <STRONG>int</STRONG> <STRONG>wgetch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win);</EM>
59        <STRONG>int</STRONG> <STRONG>mvgetch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG>
60        <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>
61        <STRONG>int</STRONG> <STRONG>ungetch(int</STRONG> <EM>ch</EM><STRONG>);</STRONG>
62        <STRONG>int</STRONG> <STRONG>has_key(int</STRONG> <EM>ch</EM><STRONG>);</STRONG>
63
64
65 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
66
67 </PRE><H3><a name="h3-Reading-characters">Reading characters</a></H3><PRE>
68        The <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG> and <STRONG>mvwgetch</STRONG>, routines  read  a
69        character  from the window.  In no-delay mode, if no input
70        is waiting, the value <STRONG>ERR</STRONG> is returned.  In delay mode, the
71        program  waits until the system passes text through to the
72        program.  Depending on the setting of <STRONG>cbreak</STRONG>, this is  af-
73        ter  one  character (cbreak mode), or after the first new-
74        line (nocbreak mode).  In  half-delay  mode,  the  program
75        waits  until a character is typed or the specified timeout
76        has been reached.
77
78        If <STRONG>echo</STRONG> is enabled, and the window is not a pad, then  the
79        character  will  also be echoed into the designated window
80        according to the following rules:
81
82        <STRONG>o</STRONG>   If the character is the current erase character,  left
83            arrow,  or backspace, the cursor is moved one space to
84            the left and that screen  position  is  erased  as  if
85            <STRONG>delch</STRONG> had been called.
86
87        <STRONG>o</STRONG>   If  the  character value is any other <STRONG>KEY_</STRONG> define, the
88            user is alerted with a <STRONG>beep</STRONG> call.
89
90        <STRONG>o</STRONG>   If the character is a carriage-return, and  if  <STRONG>nl</STRONG>  is
91            enabled,  it  is translated to a line-feed after echo-
92            ing.
93
94        <STRONG>o</STRONG>   Otherwise  the  character  is  simply  output  to  the
95            screen.
96
97        If the window is not a pad, and it has been moved or modi-
98        fied since the last call to  <STRONG>wrefresh</STRONG>,  <STRONG>wrefresh</STRONG>  will  be
99        called before another character is read.
100
101
102 </PRE><H3><a name="h3-Keypad-mode">Keypad mode</a></H3><PRE>
103        If  <STRONG>keypad</STRONG> is <STRONG>TRUE</STRONG>, and a function key is pressed, the to-
104        ken for that function key is returned instead of  the  raw
105        characters:
106
107        <STRONG>o</STRONG>   The  predefined function keys are listed in <STRONG>&lt;curses.h&gt;</STRONG>
108            as macros with values outside the range of 8-bit char-
109            acters.  Their names begin with <STRONG>KEY_</STRONG>.
110
111        <STRONG>o</STRONG>   Other  (user-defined)  function  keys which may be de-
112            fined using <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> have no names, but also are
113            expected  to  have  values  outside the range of 8-bit
114            characters.
115
116        Thus, a variable intended to hold the return  value  of  a
117        function key must be of short size or larger.
118
119        When a character that could be the beginning of a function
120        key is received (which, on modern terminals, means an  es-
121        cape character), <STRONG>curses</STRONG> sets a timer.  If the remainder of
122        the sequence does not come in within the designated  time,
123        the  character  is passed through; otherwise, the function
124        key value is returned.  For this  reason,  many  terminals
125        experience a delay between the time a user presses the es-
126        cape key and the escape is returned to the program.
127
128        In <STRONG>ncurses</STRONG>, the timer normally expires after the value  in
129        <STRONG>ESCDELAY</STRONG>  (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>).  If <STRONG>notimeout</STRONG> is <STRONG>TRUE</STRONG>,
130        the timer does not expire; it  is  an  infinite  (or  very
131        large) value.  Because function keys usually begin with an
132        escape character, the terminal may appear to hang  in  no-
133        timeout  mode  after pressing the escape key until another
134        key is pressed.
135
136
137 </PRE><H3><a name="h3-Ungetting-characters">Ungetting characters</a></H3><PRE>
138        The <STRONG>ungetch</STRONG> routine places <EM>ch</EM> back onto the input queue to
139        be returned by the next call to <STRONG>wgetch</STRONG>.  There is just one
140        input queue for all windows.
141
142
143 </PRE><H3><a name="h3-Predefined-key-codes">Predefined key-codes</a></H3><PRE>
144        The following special keys are defined in <STRONG>&lt;curses.h&gt;</STRONG>.
145
146        <STRONG>o</STRONG>   Except for the special case <STRONG>KEY_RESIZE</STRONG>, it  is  neces-
147            sary to enable <STRONG>keypad</STRONG> for <STRONG>getch</STRONG> to return these codes.
148
149        <STRONG>o</STRONG>   Not all of these are necessarily supported on any par-
150            ticular terminal.
151
152        <STRONG>o</STRONG>   The naming convention may seem obscure, with some  ap-
153            parent  misspellings  (such  as "RSUME" for "resume").
154            The names correspond to the long  terminfo  capability
155            names  for the keys, and were defined long ago, in the
156            1980s.
157
158             <EM>Name</EM>            <EM>Key</EM> <EM>name</EM>
159             -------------------------------------------------
160             KEY_BREAK       Break key
161             KEY_DOWN        The four arrow keys ...
162             KEY_UP
163             KEY_LEFT
164             KEY_RIGHT
165             KEY_HOME        Home key (upward+left arrow)
166             KEY_BACKSPACE   Backspace
167             KEY_F0          Function keys; space for 64 keys
168                             is reserved.
169             KEY_F(<EM>n</EM>)        For 0 &lt;= <EM>n</EM> &lt;= 63
170             KEY_DL          Delete line
171             KEY_IL          Insert line
172             KEY_DC          Delete character
173             KEY_IC          Insert char or enter insert mode
174             KEY_EIC         Exit insert char mode
175             KEY_CLEAR       Clear screen
176             KEY_EOS         Clear to end of screen
177             KEY_EOL         Clear to end of line
178             KEY_SF          Scroll 1 line forward
179             KEY_SR          Scroll 1 line backward (reverse)
180             KEY_NPAGE       Next page
181             KEY_PPAGE       Previous page
182
183             KEY_STAB        Set tab
184             KEY_CTAB        Clear tab
185             KEY_CATAB       Clear all tabs
186             KEY_ENTER       Enter or send
187             KEY_SRESET      Soft (partial) reset
188             KEY_RESET       Reset or hard reset
189             KEY_PRINT       Print or copy
190             KEY_LL          Home down or bottom (lower left)
191             KEY_A1          Upper left of keypad
192             KEY_A3          Upper right of keypad
193             KEY_B2          Center of keypad
194             KEY_C1          Lower left of keypad
195             KEY_C3          Lower right of keypad
196             KEY_BTAB        Back tab key
197             KEY_BEG         Beg(inning) key
198             KEY_CANCEL      Cancel key
199             KEY_CLOSE       Close key
200             KEY_COMMAND     Cmd (command) key
201             KEY_COPY        Copy key
202             KEY_CREATE      Create key
203             KEY_END         End key
204             KEY_EXIT        Exit key
205             KEY_FIND        Find key
206             KEY_HELP        Help key
207             KEY_MARK        Mark key
208             KEY_MESSAGE     Message key
209             KEY_MOUSE       Mouse event read
210             KEY_MOVE        Move key
211             KEY_NEXT        Next object key
212             KEY_OPEN        Open key
213             KEY_OPTIONS     Options key
214             KEY_PREVIOUS    Previous object key
215             KEY_REDO        Redo key
216             KEY_REFERENCE   Ref(erence) key
217             KEY_REFRESH     Refresh key
218             KEY_REPLACE     Replace key
219             KEY_RESIZE      Screen resized
220             KEY_RESTART     Restart key
221             KEY_RESUME      Resume key
222             KEY_SAVE        Save key
223             KEY_SBEG        Shifted beginning key
224             KEY_SCANCEL     Shifted cancel key
225             KEY_SCOMMAND    Shifted command key
226             KEY_SCOPY       Shifted copy key
227             KEY_SCREATE     Shifted create key
228             KEY_SDC         Shifted delete char key
229             KEY_SDL         Shifted delete line key
230             KEY_SELECT      Select key
231             KEY_SEND        Shifted end key
232             KEY_SEOL        Shifted clear line key
233             KEY_SEXIT       Shifted exit key
234             KEY_SFIND       Shifted find key
235             KEY_SHELP       Shifted help key
236             KEY_SHOME       Shifted home key
237             KEY_SIC         Shifted input key
238             KEY_SLEFT       Shifted left arrow key
239             KEY_SMESSAGE    Shifted message key
240             KEY_SMOVE       Shifted move key
241             KEY_SNEXT       Shifted next key
242             KEY_SOPTIONS    Shifted options key
243             KEY_SPREVIOUS   Shifted prev key
244             KEY_SPRINT      Shifted print key
245             KEY_SREDO       Shifted redo key
246             KEY_SREPLACE    Shifted replace key
247             KEY_SRIGHT      Shifted right arrow
248
249             KEY_SRSUME      Shifted resume key
250             KEY_SSAVE       Shifted save key
251             KEY_SSUSPEND    Shifted suspend key
252             KEY_SUNDO       Shifted undo key
253             KEY_SUSPEND     Suspend key
254             KEY_UNDO        Undo key
255
256        Keypad is arranged like this:
257
258                          +-----+------+-------+
259                          | <STRONG>A1</STRONG>  |  <STRONG>up</STRONG>  |  <STRONG>A3</STRONG>   |
260                          +-----+------+-------+
261                          |<STRONG>left</STRONG> |  <STRONG>B2</STRONG>  | <STRONG>right</STRONG> |
262                          +-----+------+-------+
263                          | <STRONG>C1</STRONG>  | <STRONG>down</STRONG> |  <STRONG>C3</STRONG>   |
264                          +-----+------+-------+
265        A  few  of  these predefined values do <EM>not</EM> correspond to a
266        real key:
267
268        <STRONG>o</STRONG>   <STRONG>KEY_RESIZE</STRONG> is returned when the  <STRONG>SIGWINCH</STRONG>  signal  has
269            been  detected  (see  <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG> and <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>).
270            This code is returned whether or not <STRONG>keypad</STRONG>  has  been
271            enabled.
272
273        <STRONG>o</STRONG>   <STRONG>KEY_MOUSE</STRONG>    is   returned   for   mouse-events   (see
274            <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>).  This code relies upon whether or not
275            <STRONG><A HREF="keypad.3x.html">keypad(3x)</A></STRONG> has been enabled, because (e.g., with <EM>xterm</EM>
276            mouse prototocol) ncurses must read escape  sequences,
277            just like a function key.
278
279
280 </PRE><H3><a name="h3-Testing-key-codes">Testing key-codes</a></H3><PRE>
281        The  <STRONG>has_key</STRONG> routine takes a key-code value from the above
282        list, and returns <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG> according to  whether  the
283        current terminal type recognizes a key with that value.
284
285        The library also supports these extensions:
286
287           <STRONG>define_key</STRONG>
288                defines  a  key-code  for  a given string (see <STRONG>de-</STRONG>
289                <STRONG><A HREF="define_key.3x.html">fine_key(3x)</A></STRONG>).
290
291           <STRONG>key_defined</STRONG>
292                checks if there is a key-code defined for a  given
293                string (see <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>).
294
295
296 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
297        All  routines  return  the integer <STRONG>ERR</STRONG> upon failure and an
298        integer value other than <STRONG>ERR</STRONG> (<STRONG>OK</STRONG> in the case of ungetch())
299        upon successful completion.
300
301           <STRONG>ungetch</STRONG>
302                returns ERR if there is no more room in the FIFO.
303
304           <STRONG>wgetch</STRONG>
305                returns  ERR  if the window pointer is null, or if
306                its timeout expires without having any data, or if
307                the  execution  was interrupted by a signal (<STRONG>errno</STRONG>
308                will be set to <STRONG>EINTR</STRONG>).
309
310        Functions with a "mv" prefix first perform a cursor  move-
311        ment  using  <STRONG>wmove</STRONG>, and return an error if the position is
312        outside the window, or if the window pointer is null.
313
314
315 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
316        Use of the escape key by a programmer for a single charac-
317        ter  function  is discouraged, as it will cause a delay of
318        up to one second while the keypad code looks for a follow-
319        ing function-key sequence.
320
321        Some  keys  may be the same as commonly used control keys,
322        e.g., <STRONG>KEY_ENTER</STRONG>  versus  control/M,  <STRONG>KEY_BACKSPACE</STRONG>  versus
323        control/H.  Some curses implementations may differ accord-
324        ing to whether they treat  these  control  keys  specially
325        (and  ignore  the  terminfo),  or use the terminfo defini-
326        tions.  <STRONG>Ncurses</STRONG> uses the terminfo definition.  If it  says
327        that  <STRONG>KEY_ENTER</STRONG>  is control/M, <STRONG>getch</STRONG> will return <STRONG>KEY_ENTER</STRONG>
328        when you press control/M.
329
330        Generally, <STRONG>KEY_ENTER</STRONG> denotes the character(s) sent by  the
331        <EM>Enter</EM> key on the numeric keypad:
332
333        <STRONG>o</STRONG>   the terminal description lists the most useful keys,
334
335        <STRONG>o</STRONG>   the  <EM>Enter</EM> key on the regular keyboard is already han-
336            dled by the standard ASCII characters for carriage-re-
337            turn and line-feed,
338
339        <STRONG>o</STRONG>   depending  on  whether <STRONG>nl</STRONG> or <STRONG>nonl</STRONG> was called, pressing
340            "Enter" on the regular keyboard may  return  either  a
341            carriage-return or line-feed, and finally
342
343        <STRONG>o</STRONG>   "Enter  or  send" is the standard description for this
344            key.
345
346        When using <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, or  <STRONG>mvwgetch</STRONG>,  nocbreak
347        mode (<STRONG>nocbreak</STRONG>) and echo mode (<STRONG>echo</STRONG>) should not be used at
348        the same time.  Depending on the state of the  tty  driver
349        when  each character is typed, the program may produce un-
350        desirable results.
351
352        Note that <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be macros.
353
354        Historically, the set of keypad macros was largely defined
355        by  the  extremely  function-key-rich keyboard of the AT&amp;T
356        7300, aka 3B1, aka Safari 4.   Modern  personal  computers
357        usually  have  only a small subset of these.  IBM PC-style
358        consoles  typically  support  little  more  than   <STRONG>KEY_UP</STRONG>,
359        <STRONG>KEY_DOWN</STRONG>,    <STRONG>KEY_LEFT</STRONG>,   <STRONG>KEY_RIGHT</STRONG>,   <STRONG>KEY_HOME</STRONG>,   <STRONG>KEY_END</STRONG>,
360        <STRONG>KEY_NPAGE</STRONG>, <STRONG>KEY_PPAGE</STRONG>, and function keys 1 through 12.  The
361        Ins key is usually mapped to <STRONG>KEY_IC</STRONG>.
362
363
364 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
365        The  *get* functions are described in the XSI Curses stan-
366        dard, Issue 4.  They  read  single-byte  characters  only.
367        The  standard  specifies  that they return <STRONG>ERR</STRONG> on failure,
368        but specifies no error conditions.
369
370        The echo behavior of these functions on input of  <STRONG>KEY_</STRONG>  or
371        backspace  characters  was not specified in the SVr4 docu-
372        mentation.  This description is adopted from the XSI Curs-
373        es standard.
374
375        The  behavior of <STRONG>getch</STRONG> and friends in the presence of han-
376        dled signals is unspecified in the  SVr4  and  XSI  Curses
377        documentation.   Under  historical curses implementations,
378        it varied depending on whether the operating system's  im-
379        plementation   of  handled  signal  receipt  interrupts  a
380        <STRONG>read(2)</STRONG> call in progress or not, and also (in some  imple-
381        mentations)  depending on whether an input timeout or non-
382        blocking mode has been set.
383
384        <STRONG>KEY_MOUSE</STRONG> is mentioned in XSI Curses, along with a few re-
385        lated terminfo capabilities, but no higher-level functions
386        use the feature.  The implementation in ncurses is an  ex-
387        tension.
388
389        <STRONG>KEY_RESIZE</STRONG>  is an extension first implemented for ncurses.
390        NetBSD curses later added this extension.
391
392        Programmers concerned about portability should be prepared
393        for  either  of two cases: (a) signal receipt does not in-
394        terrupt <STRONG>getch</STRONG>; (b) signal  receipt  interrupts  <STRONG>getch</STRONG>  and
395        causes it to return ERR with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>.
396
397        The  <STRONG>has_key</STRONG>  function is unique to <STRONG>ncurses</STRONG>.  We recommend
398        that any code using it be conditionalized  on  the  <STRONG>NCURS-</STRONG>
399        <STRONG>ES_VERSION</STRONG> feature macro.
400
401
402 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
403        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,       <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>,       <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>,
404        <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>,      <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>,      <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>,
405        <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>.
406
407        Comparable  functions in the wide-character (ncursesw) li-
408        brary are described in <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>.
409
410
411
412                                                          <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
413 </PRE>
414 <div class="nav">
415 <ul>
416 <li><a href="#h2-NAME">NAME</a></li>
417 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
418 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
419 <ul>
420 <li><a href="#h3-Reading-characters">Reading characters</a></li>
421 <li><a href="#h3-Keypad-mode">Keypad mode</a></li>
422 <li><a href="#h3-Ungetting-characters">Ungetting characters</a></li>
423 <li><a href="#h3-Predefined-key-codes">Predefined key-codes</a></li>
424 <li><a href="#h3-Testing-key-codes">Testing key-codes</a></li>
425 </ul>
426 </li>
427 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
428 <li><a href="#h2-NOTES">NOTES</a></li>
429 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
430 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
431 </ul>
432 </div>
433 </BODY>
434 </HTML>