ncurses 6.0 - patch 20160514
[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.45 2016/05/15 01:05:18 tom Exp @
31 -->
32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
33 <HTML>
34 <HEAD>
35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
36 <meta name="generator" content="Manpage converted by man2html - see 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
129 </PRE><H3><a name="h3-Ungetting-characters">Ungetting characters</a></H3><PRE>
130        The <STRONG>ungetch</STRONG> routine places <EM>ch</EM> back onto the input queue to
131        be returned by the next call to <STRONG>wgetch</STRONG>.  There is just one
132        input queue for all windows.
133
134
135 </PRE><H3><a name="h3-Predefined-key-codes">Predefined key-codes</a></H3><PRE>
136        The following special keys are defined in <STRONG>&lt;curses.h&gt;</STRONG>.
137
138        <STRONG>o</STRONG>   Except for the special case <STRONG>KEY_RESIZE</STRONG>, it  is  neces-
139            sary to enable <STRONG>keypad</STRONG> for <STRONG>getch</STRONG> to return these codes.
140
141        <STRONG>o</STRONG>   Not all of these are necessarily supported on any par-
142            ticular terminal.
143
144        <STRONG>o</STRONG>   The naming convention may seem obscure, with some  ap-
145            parent  misspellings  (such  as "RSUME" for "resume").
146            The names correspond to the long  terminfo  capability
147            names  for the keys, and were defined long ago, in the
148            1980s.
149
150             <EM>Name</EM>            <EM>Key</EM> <EM>name</EM>
151             -------------------------------------------------
152             KEY_BREAK       Break key
153             KEY_DOWN        The four arrow keys ...
154             KEY_UP
155             KEY_LEFT
156             KEY_RIGHT
157             KEY_HOME        Home key (upward+left arrow)
158             KEY_BACKSPACE   Backspace
159             KEY_F0          Function keys; space for 64 keys
160                             is reserved.
161             KEY_F(<EM>n</EM>)        For 0 &lt;= <EM>n</EM> &lt;= 63
162             KEY_DL          Delete line
163             KEY_IL          Insert line
164             KEY_DC          Delete character
165             KEY_IC          Insert char or enter insert mode
166             KEY_EIC         Exit insert char mode
167             KEY_CLEAR       Clear screen
168             KEY_EOS         Clear to end of screen
169             KEY_EOL         Clear to end of line
170             KEY_SF          Scroll 1 line forward
171             KEY_SR          Scroll 1 line backward (reverse)
172             KEY_NPAGE       Next page
173             KEY_PPAGE       Previous page
174             KEY_STAB        Set tab
175             KEY_CTAB        Clear tab
176             KEY_CATAB       Clear all tabs
177             KEY_ENTER       Enter or send
178             KEY_SRESET      Soft (partial) reset
179             KEY_RESET       Reset or hard reset
180             KEY_PRINT       Print or copy
181             KEY_LL          Home down or bottom (lower left)
182
183             KEY_A1          Upper left of keypad
184             KEY_A3          Upper right of keypad
185             KEY_B2          Center of keypad
186             KEY_C1          Lower left of keypad
187             KEY_C3          Lower right of keypad
188             KEY_BTAB        Back tab key
189             KEY_BEG         Beg(inning) key
190             KEY_CANCEL      Cancel key
191             KEY_CLOSE       Close key
192             KEY_COMMAND     Cmd (command) key
193             KEY_COPY        Copy key
194             KEY_CREATE      Create key
195             KEY_END         End key
196             KEY_EXIT        Exit key
197             KEY_FIND        Find key
198             KEY_HELP        Help key
199             KEY_MARK        Mark key
200             KEY_MESSAGE     Message key
201             KEY_MOUSE       Mouse event read
202             KEY_MOVE        Move key
203             KEY_NEXT        Next object key
204             KEY_OPEN        Open key
205             KEY_OPTIONS     Options key
206             KEY_PREVIOUS    Previous object key
207             KEY_REDO        Redo key
208             KEY_REFERENCE   Ref(erence) key
209             KEY_REFRESH     Refresh key
210             KEY_REPLACE     Replace key
211             KEY_RESIZE      Screen resized
212             KEY_RESTART     Restart key
213             KEY_RESUME      Resume key
214             KEY_SAVE        Save key
215             KEY_SBEG        Shifted beginning key
216             KEY_SCANCEL     Shifted cancel key
217             KEY_SCOMMAND    Shifted command key
218             KEY_SCOPY       Shifted copy key
219             KEY_SCREATE     Shifted create key
220             KEY_SDC         Shifted delete char key
221             KEY_SDL         Shifted delete line key
222             KEY_SELECT      Select key
223             KEY_SEND        Shifted end key
224             KEY_SEOL        Shifted clear line key
225             KEY_SEXIT       Shifted exit key
226             KEY_SFIND       Shifted find key
227             KEY_SHELP       Shifted help key
228             KEY_SHOME       Shifted home key
229             KEY_SIC         Shifted input key
230             KEY_SLEFT       Shifted left arrow key
231             KEY_SMESSAGE    Shifted message key
232             KEY_SMOVE       Shifted move key
233             KEY_SNEXT       Shifted next key
234             KEY_SOPTIONS    Shifted options key
235             KEY_SPREVIOUS   Shifted prev key
236             KEY_SPRINT      Shifted print key
237             KEY_SREDO       Shifted redo key
238             KEY_SREPLACE    Shifted replace key
239             KEY_SRIGHT      Shifted right arrow
240             KEY_SRSUME      Shifted resume key
241             KEY_SSAVE       Shifted save key
242             KEY_SSUSPEND    Shifted suspend key
243             KEY_SUNDO       Shifted undo key
244             KEY_SUSPEND     Suspend key
245             KEY_UNDO        Undo key
246
247        Keypad is arranged like this:
248
249                          +-----+------+-------+
250                          | <STRONG>A1</STRONG>  |  <STRONG>up</STRONG>  |  <STRONG>A3</STRONG>   |
251                          +-----+------+-------+
252                          |<STRONG>left</STRONG> |  <STRONG>B2</STRONG>  | <STRONG>right</STRONG> |
253                          +-----+------+-------+
254                          | <STRONG>C1</STRONG>  | <STRONG>down</STRONG> |  <STRONG>C3</STRONG>   |
255                          +-----+------+-------+
256        A  few  of  these predefined values do <EM>not</EM> correspond to a
257        real key:
258
259        <STRONG>o</STRONG>   <STRONG>KEY_RESIZE</STRONG> is returned when the  <STRONG>SIGWINCH</STRONG>  signal  has
260            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>).
261            This code is returned whether or not <STRONG>keypad</STRONG>  has  been
262            enabled.
263
264        <STRONG>o</STRONG>   <STRONG>KEY_MOUSE</STRONG>    is   returned   for   mouse-events   (see
265            <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>).  This code relies upon whether or not
266            <STRONG><A HREF="keypad.3x.html">keypad(3x)</A></STRONG> has been enabled, because (e.g., with <EM>xterm</EM>
267            mouse prototocol) ncurses must read escape  sequences,
268            just like a function key.
269
270
271 </PRE><H3><a name="h3-Testing-key-codes">Testing key-codes</a></H3><PRE>
272        The  <STRONG>has_key</STRONG> routine takes a key-code value from the above
273        list, and returns <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG> according to  whether  the
274        current terminal type recognizes a key with that value.
275
276        The library also supports these extensions:
277
278           <STRONG>define_key</STRONG>
279                defines  a  key-code  for  a given string (see <STRONG>de-</STRONG>
280                <STRONG><A HREF="define_key.3x.html">fine_key(3x)</A></STRONG>).
281
282           <STRONG>key_defined</STRONG>
283                checks if there is a key-code defined for a  given
284                string (see <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>).
285
286
287 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
288        All  routines  return  the integer <STRONG>ERR</STRONG> upon failure and an
289        integer value other than <STRONG>ERR</STRONG> (<STRONG>OK</STRONG> in the case of ungetch())
290        upon successful completion.
291
292           <STRONG>ungetch</STRONG>
293                returns ERR if there is no more room in the FIFO.
294
295           <STRONG>wgetch</STRONG>
296                returns  ERR  if the window pointer is null, or if
297                its timeout expires without having any data.
298
299        Functions with a "mv" prefix first perform a cursor  move-
300        ment  using  <STRONG>wmove</STRONG>, and return an error if the position is
301        outside the window, or if the window pointer is null.
302
303
304 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
305        Use of the escape key by a programmer for a single charac-
306        ter  function  is discouraged, as it will cause a delay of
307        up to one second while the keypad code looks for a follow-
308        ing function-key sequence.
309
310        Some  keys  may be the same as commonly used control keys,
311        e.g., <STRONG>KEY_ENTER</STRONG>  versus  control/M,  <STRONG>KEY_BACKSPACE</STRONG>  versus
312        control/H.  Some curses implementations may differ accord-
313        ing to whether they treat  these  control  keys  specially
314        (and  ignore  the  terminfo),  or use the terminfo defini-
315        tions.  <STRONG>Ncurses</STRONG> uses the terminfo definition.  If it  says
316        that  <STRONG>KEY_ENTER</STRONG>  is control/M, <STRONG>getch</STRONG> will return <STRONG>KEY_ENTER</STRONG>
317        when you press control/M.
318
319        Generally, <STRONG>KEY_ENTER</STRONG> denotes the character(s) sent by  the
320        <EM>Enter</EM> key on the numeric keypad:
321
322        <STRONG>o</STRONG>   the terminal description lists the most useful keys,
323
324        <STRONG>o</STRONG>   the  <EM>Enter</EM> key on the regular keyboard is already han-
325            dled by the standard ASCII characters for carriage-re-
326            turn and line-feed,
327
328        <STRONG>o</STRONG>   depending  on  whether <STRONG>nl</STRONG> or <STRONG>nonl</STRONG> was called, pressing
329            "Enter" on the regular keyboard may  return  either  a
330            carriage-return or line-feed, and finally
331
332        <STRONG>o</STRONG>   "Enter  or  send" is the standard description for this
333            key.
334
335        When using <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, or  <STRONG>mvwgetch</STRONG>,  nocbreak
336        mode (<STRONG>nocbreak</STRONG>) and echo mode (<STRONG>echo</STRONG>) should not be used at
337        the same time.  Depending on the state of the  tty  driver
338        when  each character is typed, the program may produce un-
339        desirable results.
340
341        Note that <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be macros.
342
343        Historically, the set of keypad macros was largely defined
344        by  the  extremely  function-key-rich keyboard of the AT&amp;T
345        7300, aka 3B1, aka Safari 4.   Modern  personal  computers
346        usually  have  only a small subset of these.  IBM PC-style
347        consoles  typically  support  little  more  than   <STRONG>KEY_UP</STRONG>,
348        <STRONG>KEY_DOWN</STRONG>,    <STRONG>KEY_LEFT</STRONG>,   <STRONG>KEY_RIGHT</STRONG>,   <STRONG>KEY_HOME</STRONG>,   <STRONG>KEY_END</STRONG>,
349        <STRONG>KEY_NPAGE</STRONG>, <STRONG>KEY_PPAGE</STRONG>, and function keys 1 through 12.  The
350        Ins key is usually mapped to <STRONG>KEY_IC</STRONG>.
351
352
353 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
354        The  *get* functions are described in the XSI Curses stan-
355        dard, Issue 4.  They  read  single-byte  characters  only.
356        The  standard  specifies  that they return <STRONG>ERR</STRONG> on failure,
357        but specifies no error conditions.
358
359        The echo behavior of these functions on input of  <STRONG>KEY_</STRONG>  or
360        backspace  characters  was not specified in the SVr4 docu-
361        mentation.  This description is adopted from the XSI Curs-
362        es standard.
363
364        The  behavior of <STRONG>getch</STRONG> and friends in the presence of han-
365        dled signals is unspecified in the  SVr4  and  XSI  Curses
366        documentation.   Under  historical curses implementations,
367        it varied depending on whether the operating system's  im-
368        plementation   of  handled  signal  receipt  interrupts  a
369        <STRONG>read(2)</STRONG> call in progress or not, and also (in some  imple-
370        mentations)  depending on whether an input timeout or non-
371        blocking mode has been set.
372
373        <STRONG>KEY_MOUSE</STRONG> is mentioned in XSI Curses, along with a few re-
374        lated terminfo capabilities, but no higher-level functions
375        use the feature.  The implementation in ncurses is an  ex-
376        tension.
377
378        <STRONG>KEY_RESIZE</STRONG>  is an extension first implemented for ncurses.
379        NetBSD curses later added this extension.
380
381        Programmers concerned about portability should be prepared
382        for  either  of two cases: (a) signal receipt does not in-
383        terrupt <STRONG>getch</STRONG>; (b) signal  receipt  interrupts  <STRONG>getch</STRONG>  and
384        causes  it  to  return ERR with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>.  Under
385        the <STRONG>ncurses</STRONG> implementation, handled signals  never  inter-
386        rupt <STRONG>getch</STRONG>.
387
388        The  <STRONG>has_key</STRONG>  function is unique to <STRONG>ncurses</STRONG>.  We recommend
389        that any code using it be conditionalized  on  the  <STRONG>NCURS-</STRONG>
390        <STRONG>ES_VERSION</STRONG> feature macro.
391
392
393 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
394        <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>,
395        <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>,   <STRONG>re-</STRONG>
396        <STRONG><A HREF="resizeterm.3x.html">sizeterm(3x)</A></STRONG>.
397
398        Comparable  functions in the wide-character (ncursesw) li-
399        brary are described in <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>.
400
401
402
403                                                          <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
404 </PRE>
405 <div class="nav">
406 <ul>
407 <li><a href="#h2-NAME">NAME</a></li>
408 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
409 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
410 <ul>
411 <li><a href="#h3-Reading-characters">Reading characters</a></li>
412 <li><a href="#h3-Keypad-mode">Keypad mode</a></li>
413 <li><a href="#h3-Ungetting-characters">Ungetting characters</a></li>
414 <li><a href="#h3-Predefined-key-codes">Predefined key-codes</a></li>
415 <li><a href="#h3-Testing-key-codes">Testing key-codes</a></li>
416 </ul>
417 </li>
418 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
419 <li><a href="#h2-NOTES">NOTES</a></li>
420 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
421 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
422 </ul>
423 </div>
424 </BODY>
425 </HTML>