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