2 ****************************************************************************
3 * Copyright (c) 1998-2012,2013 Free Software Foundation, Inc. *
5 * Permission is hereby granted, free of charge, to any person obtaining a *
6 * copy of this software and associated documentation files (the *
7 * "Software"), to deal in the Software without restriction, including *
8 * without limitation the rights to use, copy, modify, merge, publish, *
9 * distribute, distribute with modifications, sublicense, and/or sell *
10 * copies of the Software, and to permit persons to whom the Software is *
11 * furnished to do so, subject to the following conditions: *
13 * The above copyright notice and this permission notice shall be included *
14 * in all copies or substantial portions of the Software. *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 * Except as contained in this notice, the name(s) of the above copyright *
25 * holders shall not be used in advertising or otherwise to promote the *
26 * sale, use or other dealings in this Software without prior written *
28 ****************************************************************************
29 * @Id: curs_inopts.3x,v 1.18 2013/07/20 19:42:02 tom Exp @
31 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
34 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
35 <meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
36 <TITLE>curs_inopts 3x</TITLE>
37 <link rev=made href="mailto:bug-ncurses@gnu.org">
38 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
41 <H1>curs_inopts 3x</H1>
44 <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
50 <H2><a name="h2-NAME">NAME</a></H2><PRE>
51 <STRONG>cbreak</STRONG>, <STRONG>nocbreak</STRONG>, <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>,
52 <STRONG>keypad</STRONG>, <STRONG>meta</STRONG>, <STRONG>nodelay</STRONG>, <STRONG>notimeout</STRONG>, <STRONG>raw</STRONG>, <STRONG>noraw</STRONG>, <STRONG>noqiflush</STRONG>,
53 <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, <STRONG>wtimeout</STRONG>, <STRONG>typeahead</STRONG> - <STRONG>curses</STRONG> input
58 <H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
59 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
61 <STRONG>int</STRONG> <STRONG>cbreak(void);</STRONG>
62 <STRONG>int</STRONG> <STRONG>nocbreak(void);</STRONG>
63 <STRONG>int</STRONG> <STRONG>echo(void);</STRONG>
64 <STRONG>int</STRONG> <STRONG>noecho(void);</STRONG>
65 <STRONG>int</STRONG> <STRONG>halfdelay(int</STRONG> <STRONG>tenths);</STRONG>
66 <STRONG>int</STRONG> <STRONG>intrflush(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
67 <STRONG>int</STRONG> <STRONG>keypad(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
68 <STRONG>int</STRONG> <STRONG>meta(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
69 <STRONG>int</STRONG> <STRONG>nodelay(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
70 <STRONG>int</STRONG> <STRONG>raw(void);</STRONG>
71 <STRONG>int</STRONG> <STRONG>noraw(void);</STRONG>
72 <STRONG>void</STRONG> <STRONG>noqiflush(void);</STRONG>
73 <STRONG>void</STRONG> <STRONG>qiflush(void);</STRONG>
74 <STRONG>int</STRONG> <STRONG>notimeout(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
75 <STRONG>void</STRONG> <STRONG>timeout(int</STRONG> <STRONG>delay);</STRONG>
76 <STRONG>void</STRONG> <STRONG>wtimeout(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>delay);</STRONG>
77 <STRONG>int</STRONG> <STRONG>typeahead(int</STRONG> <STRONG>fd);</STRONG>
81 <H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
82 Normally, the tty driver buffers typed characters until a
83 newline or carriage return is typed. The <STRONG>cbreak</STRONG> routine
84 disables line buffering and erase/kill character-process-
85 ing (interrupt and flow control characters are unaffect-
86 ed), making characters typed by the user immediately
87 available to the program. The <STRONG>nocbreak</STRONG> routine returns
88 the terminal to normal (cooked) mode.
90 Initially the terminal may or may not be in <STRONG>cbreak</STRONG> mode,
91 as the mode is inherited; therefore, a program should call
92 <STRONG>cbreak</STRONG> or <STRONG>nocbreak</STRONG> explicitly. Most interactive programs
93 using <STRONG>curses</STRONG> set the <STRONG>cbreak</STRONG> mode. Note that <STRONG>cbreak</STRONG> over-
94 rides <STRONG>raw</STRONG>. [See <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> for a discussion of how
95 these routines interact with <STRONG>echo</STRONG> and <STRONG>noecho</STRONG>.]
97 The <STRONG>echo</STRONG> and <STRONG>noecho</STRONG> routines control whether characters
98 typed by the user are echoed by <STRONG>getch</STRONG> as they are typed.
99 Echoing by the tty driver is always disabled, but initial-
100 ly <STRONG>getch</STRONG> is in echo mode, so characters typed are echoed.
101 Authors of most interactive programs prefer to do their
102 own echoing in a controlled area of the screen, or not to
103 echo at all, so they disable echoing by calling <STRONG>noecho</STRONG>.
104 [See <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> for a discussion of how these routines
105 interact with <STRONG>cbreak</STRONG> and <STRONG>nocbreak</STRONG>.]
107 The <STRONG>halfdelay</STRONG> routine is used for half-delay mode, which
108 is similar to <STRONG>cbreak</STRONG> mode in that characters typed by the
109 user are immediately available to the program. However,
110 after blocking for <EM>tenths</EM> tenths of seconds, ERR is re-
111 turned if nothing has been typed. The value of <STRONG>tenths</STRONG>
112 must be a number between 1 and 255. Use <STRONG>nocbreak</STRONG> to leave
115 If the <STRONG>intrflush</STRONG> option is enabled, (<EM>bf</EM> is <STRONG>TRUE</STRONG>), when an
116 interrupt key is pressed on the keyboard (interrupt,
117 break, quit) all output in the tty driver queue will be
118 flushed, giving the effect of faster response to the in-
119 terrupt, but causing <STRONG>curses</STRONG> to have the wrong idea of what
120 is on the screen. Disabling (<EM>bf</EM> is <STRONG>FALSE</STRONG>), the option
121 prevents the flush. The default for the option is inher-
122 ited from the tty driver settings. The window argument is
125 The <STRONG>keypad</STRONG> option enables the keypad of the user's termi-
126 nal. If enabled (<EM>bf</EM> is <STRONG>TRUE</STRONG>), the user can press a func-
127 tion key (such as an arrow key) and <STRONG>wgetch</STRONG> returns a sin-
128 gle value representing the function key, as in <STRONG>KEY_LEFT</STRONG>.
129 If disabled (<EM>bf</EM> is <STRONG>FALSE</STRONG>), <STRONG>curses</STRONG> does not treat function
130 keys specially and the program has to interpret the escape
131 sequences itself. If the keypad in the terminal can be
132 turned on (made to transmit) and off (made to work local-
133 ly), turning on this option causes the terminal keypad to
134 be turned on when <STRONG>wgetch</STRONG> is called. The default value for
137 Initially, whether the terminal returns 7 or 8 significant
138 bits on input depends on the control mode of the tty driv-
139 er [see <STRONG>termio(7)</STRONG>]. To force 8 bits to be returned, in-
140 voke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>TRUE</STRONG>); this is equivalent, under POSIX, to
141 setting the CS8 flag on the terminal. To force 7 bits to
142 be returned, invoke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>FALSE</STRONG>); this is equivalent,
143 under POSIX, to setting the CS7 flag on the terminal. The
144 window argument, <EM>win</EM>, is always ignored. If the terminfo
145 capabilities <STRONG>smm</STRONG> (meta_on) and <STRONG>rmm</STRONG> (meta_off) are defined
146 for the terminal, <STRONG>smm</STRONG> is sent to the terminal when
147 <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>TRUE</STRONG>) is called and <STRONG>rmm</STRONG> is sent when <STRONG>meta</STRONG>(<EM>win</EM>,
148 <STRONG>FALSE</STRONG>) is called.
150 The <STRONG>nodelay</STRONG> option causes <STRONG>getch</STRONG> to be a non-blocking call.
151 If no input is ready, <STRONG>getch</STRONG> returns <STRONG>ERR</STRONG>. If disabled (<EM>bf</EM>
152 is <STRONG>FALSE</STRONG>), <STRONG>getch</STRONG> waits until a key is pressed.
154 While interpreting an input escape sequence, <STRONG>wgetch</STRONG> sets a
155 timer while waiting for the next character. If <STRONG>notime-</STRONG>
156 <STRONG>out(</STRONG><EM>win</EM>, <STRONG>TRUE</STRONG>) is called, then <STRONG>wgetch</STRONG> does not set a
157 timer. The purpose of the timeout is to differentiate be-
158 tween sequences received from a function key and those
161 The <STRONG>raw</STRONG> and <STRONG>noraw</STRONG> routines place the terminal into or out
162 of raw mode. Raw mode is similar to <STRONG>cbreak</STRONG> mode, in that
163 characters typed are immediately passed through to the us-
164 er program. The differences are that in raw mode, the in-
165 terrupt, quit, suspend, and flow control characters are
166 all passed through uninterpreted, instead of generating a
167 signal. The behavior of the BREAK key depends on other
168 bits in the tty driver that are not set by <STRONG>curses</STRONG>.
170 When the <STRONG>noqiflush</STRONG> routine is used, normal flush of input
171 and output queues associated with the <STRONG>INTR</STRONG>, <STRONG>QUIT</STRONG> and <STRONG>SUSP</STRONG>
172 characters will not be done [see <STRONG>termio(7)</STRONG>]. When <STRONG>qiflush</STRONG>
173 is called, the queues will be flushed when these control
174 characters are read. You may want to call <STRONG>noqiflush()</STRONG> in
175 a signal handler if you want output to continue as though
176 the interrupt had not occurred, after the handler exits.
178 The <STRONG>timeout</STRONG> and <STRONG>wtimeout</STRONG> routines set blocking or non-
179 blocking read for a given window. If <EM>delay</EM> is negative,
180 blocking read is used (i.e., waits indefinitely for in-
181 put). If <EM>delay</EM> is zero, then non-blocking read is used
182 (i.e., read returns <STRONG>ERR</STRONG> if no input is waiting). If <EM>delay</EM>
183 is positive, then read blocks for <EM>delay</EM> milliseconds, and
184 returns <STRONG>ERR</STRONG> if there is still no input. Hence, these rou-
185 tines provide the same functionality as <STRONG>nodelay</STRONG>, plus the
186 additional capability of being able to block for only <EM>de-</EM>
187 <EM>lay</EM> milliseconds (where <EM>delay</EM> is positive).
189 The <STRONG>curses</STRONG> library does "line-breakout optimization" by
190 looking for typeahead periodically while updating the
191 screen. If input is found, and it is coming from a tty,
192 the current update is postponed until <STRONG>refresh</STRONG> or <STRONG>doupdate</STRONG>
193 is called again. This allows faster response to commands
194 typed in advance. Normally, the input FILE pointer passed
195 to <STRONG>newterm</STRONG>, or <STRONG>stdin</STRONG> in the case that <STRONG>initscr</STRONG> was used,
196 will be used to do this typeahead checking. The <STRONG>typeahead</STRONG>
197 routine specifies that the file descriptor <EM>fd</EM> is to be
198 used to check for typeahead instead. If <EM>fd</EM> is -1, then no
199 typeahead checking is done.
203 <H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
204 All routines that return an integer return <STRONG>ERR</STRONG> upon fail-
205 ure and OK (SVr4 specifies only "an integer value other
206 than <STRONG>ERR</STRONG>") upon successful completion, unless otherwise
207 noted in the preceding routine descriptions.
209 X/Open does not define any error conditions. In this im-
210 plementation, functions with a window parameter will re-
211 turn an error if it is null. Any function will also re-
212 turn an error if the terminal was not initialized. Also,
214 <STRONG>halfdelay</STRONG>
215 returns an error if its parameter is outside
220 <H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
221 These functions are described in the XSI Curses standard,
224 The ncurses library obeys the XPG4 standard and the his-
225 torical practice of the AT&T curses implementations, in
226 that the echo bit is cleared when curses initializes the
227 terminal state. BSD curses differed from this slightly;
228 it left the echo bit on at initialization, but the BSD <STRONG>raw</STRONG>
229 call turned it off as a side-effect. For best portabili-
230 ty, set echo or noecho explicitly just after initializa-
231 tion, even if your program remains in cooked mode.
233 When <STRONG>keypad</STRONG> is first enabled, ncurses loads the key-defi-
234 nitions for the current terminal description. If the ter-
235 minal description includes extended string capabilities,
236 e.g., from using the <STRONG>-x</STRONG> option of tic, then ncurses also
237 defines keys for the capabilities whose names begin with
238 "k". The corresponding keycodes are generated and (de-
239 pending on previous loads of terminal descriptions) may
240 differ from one execution of a program to the next. The
241 generated keycodes are recognized by the <STRONG>keyname</STRONG> function
242 (which will then return a name beginning with "k" denoting
243 the terminfo capability name rather than "K", used for
244 curses key-names). On the other hand, an application can
245 use <STRONG>define_key</STRONG> to establish a specific keycode for a given
246 string. This makes it possible for an application to
247 check for an extended capability's presence with <EM>tigetstr</EM>,
248 and reassign the keycode to match its own needs.
250 Low-level applications can use <STRONG>tigetstr</STRONG> to obtain the def-
251 inition of any particular string capability. Higher-level
252 applications which use the curses <STRONG>wgetch</STRONG> and similar func-
253 tions to return keycodes rely upon the order in which the
254 strings are loaded. If more than one key definition has
255 the same string value, then <STRONG>wgetch</STRONG> can return only one
256 keycode. Most curses implementations (including ncurses)
257 load key definitions in the order defined by the array of
258 string capability names. The last key to be loaded deter-
259 mines the keycode which will be returned. In ncurses, you
260 may also have extended capabilities interpreted as key
261 definitions. These are loaded after the predefined keys,
262 and if a capability's value is the same as a previously-
263 loaded key definition, the later definition is the one
268 <H2><a name="h2-NOTES">NOTES</a></H2><PRE>
269 Note that <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>meta</STRONG>, <STRONG>node-</STRONG>
270 <STRONG>lay</STRONG>, <STRONG>notimeout</STRONG>, <STRONG>noqiflush</STRONG>, <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, and <STRONG>wtimeout</STRONG>
273 The <STRONG>noraw</STRONG> and <STRONG>nocbreak</STRONG> calls follow historical practice in
274 that they attempt to restore to normal (`cooked') mode
275 from raw and cbreak modes respectively. Mixing raw/noraw
276 and cbreak/nocbreak calls leads to tty driver control
277 states that are hard to predict or understand; it is not
282 <H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
283 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>,
284 <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>, <STRONG>termio(7)</STRONG>
288 <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
292 <li><a href="#h2-NAME">NAME</a></li>
293 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
294 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
295 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
296 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
297 <li><a href="#h2-NOTES">NOTES</a></li>
298 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>