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