1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
3 ****************************************************************************
4 * Copyright (c) 1998,2001 Free Software Foundation, Inc. *
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: *
14 * The above copyright notice and this permission notice shall be included *
15 * in all copies or substantial portions of the Software. *
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. *
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 *
29 ****************************************************************************
30 * @Id: curs_inopts.3x,v 1.9 2002/08/10 22:29:49 tom Exp @
34 <TITLE>curs_inopts 3x</TITLE>
35 <link rev=made href="mailto:bug-ncurses@gnu.org">
36 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
39 <H1>curs_inopts 3x</H1>
42 <!-- Manpage converted by man2html 3.0.1 -->
46 <STRONG>cbreak</STRONG>, <STRONG>nocbreak</STRONG>, <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>key-</STRONG>
47 <STRONG>pad</STRONG>, <STRONG>meta</STRONG>, <STRONG>nodelay</STRONG>, <STRONG>notimeout</STRONG>, <STRONG>raw</STRONG>, <STRONG>noraw</STRONG>, <STRONG>noqiflush</STRONG>,
48 <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, <STRONG>wtimeout</STRONG>, <STRONG>typeahead</STRONG> - <STRONG>curses</STRONG> input
53 <H2>SYNOPSIS</H2><PRE>
54 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
56 <STRONG>int</STRONG> <STRONG>cbreak(void);</STRONG>
57 <STRONG>int</STRONG> <STRONG>nocbreak(void);</STRONG>
58 <STRONG>int</STRONG> <STRONG>echo(void);</STRONG>
59 <STRONG>int</STRONG> <STRONG>noecho(void);</STRONG>
60 <STRONG>int</STRONG> <STRONG>halfdelay(int</STRONG> <STRONG>tenths);</STRONG>
61 <STRONG>int</STRONG> <STRONG>intrflush(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
62 <STRONG>int</STRONG> <STRONG>keypad(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
63 <STRONG>int</STRONG> <STRONG>meta(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
64 <STRONG>int</STRONG> <STRONG>nodelay(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
65 <STRONG>int</STRONG> <STRONG>raw(void);</STRONG>
66 <STRONG>int</STRONG> <STRONG>noraw(void);</STRONG>
67 <STRONG>void</STRONG> <STRONG>noqiflush(void);</STRONG>
68 <STRONG>void</STRONG> <STRONG>qiflush(void);</STRONG>
69 <STRONG>int</STRONG> <STRONG>notimeout(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
70 <STRONG>void</STRONG> <STRONG>timeout(int</STRONG> <STRONG>delay);</STRONG>
71 <STRONG>void</STRONG> <STRONG>wtimeout(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>delay);</STRONG>
72 <STRONG>int</STRONG> <STRONG>typeahead(int</STRONG> <STRONG>fd);</STRONG>
76 <H2>DESCRIPTION</H2><PRE>
77 Normally, the tty driver buffers typed characters until a
78 newline or carriage return is typed. The <STRONG>cbreak</STRONG> routine
79 disables line buffering and erase/kill character-process-
80 ing (interrupt and flow control characters are unaf-
81 fected), making characters typed by the user immediately
82 available to the program. The <STRONG>nocbreak</STRONG> routine returns
83 the terminal to normal (cooked) mode.
85 Initially the terminal may or may not be in <STRONG>cbreak</STRONG> mode,
86 as the mode is inherited; therefore, a program should call
87 <STRONG>cbreak</STRONG> or <STRONG>nocbreak</STRONG> explicitly. Most interactive programs
88 using <STRONG>curses</STRONG> set the <STRONG>cbreak</STRONG> mode. Note that <STRONG>cbreak</STRONG> over-
89 rides <STRONG>raw</STRONG>. [See <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> for a discussion of how
90 these routines interact with <STRONG>echo</STRONG> and <STRONG>noecho</STRONG>.]
92 The <STRONG>echo</STRONG> and <STRONG>noecho</STRONG> routines control whether characters
93 typed by the user are echoed by <STRONG>getch</STRONG> as they are typed.
94 Echoing by the tty driver is always disabled, but ini-
95 tially <STRONG>getch</STRONG> is in echo mode, so characters typed are
96 echoed. Authors of most interactive programs prefer to do
97 their own echoing in a controlled area of the screen, or
98 not to echo at all, so they disable echoing by calling
99 <STRONG>noecho</STRONG>. [See <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> for a discussion of how these
100 routines interact with <STRONG>cbreak</STRONG> and <STRONG>nocbreak</STRONG>.]
102 The <STRONG>halfdelay</STRONG> routine is used for half-delay mode, which
103 is similar to <STRONG>cbreak</STRONG> mode in that characters typed by the
104 user are immediately available to the program. However,
105 after blocking for <EM>tenths</EM> tenths of seconds, ERR is
106 returned if nothing has been typed. The value of <STRONG>tenths</STRONG>
107 must be a number between 1 and 255. Use <STRONG>nocbreak</STRONG> to leave
110 If the <STRONG>intrflush</STRONG> option is enabled, (<EM>bf</EM> is <STRONG>TRUE</STRONG>), when an
111 interrupt key is pressed on the keyboard (interrupt,
112 break, quit) all output in the tty driver queue will be
113 flushed, giving the effect of faster response to the
114 interrupt, but causing <STRONG>curses</STRONG> to have the wrong idea of
115 what is on the screen. Disabling (<EM>bf</EM> is <STRONG>FALSE</STRONG>), the
116 option prevents the flush. The default for the option is
117 inherited from the tty driver settings. The window argu-
120 The <STRONG>keypad</STRONG> option enables the keypad of the user's termi-
121 nal. If enabled (<EM>bf</EM> is <STRONG>TRUE</STRONG>), the user can press a func-
122 tion key (such as an arrow key) and <STRONG>wgetch</STRONG> returns a sin-
123 gle value representing the function key, as in <STRONG>KEY_LEFT</STRONG>.
124 If disabled (<EM>bf</EM> is <STRONG>FALSE</STRONG>), <STRONG>curses</STRONG> does not treat function
125 keys specially and the program has to interpret the escape
126 sequences itself. If the keypad in the terminal can be
127 turned on (made to transmit) and off (made to work
128 locally), turning on this option causes the terminal key-
129 pad to be turned on when <STRONG>wgetch</STRONG> is called. The default
130 value for keypad is false.
132 Initially, whether the terminal returns 7 or 8 significant
133 bits on input depends on the control mode of the tty
134 driver [see <STRONG><A HREF="termio.7.html">termio(7)</A></STRONG>]. To force 8 bits to be returned,
135 invoke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>TRUE</STRONG>); this is equivalent, under POSIX,
136 to setting the CS8 flag on the terminal. To force 7 bits
137 to be returned, invoke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>FALSE</STRONG>); this is equiva-
138 lent, under POSIX, to setting the CS7 flag on the termi-
139 nal. The window argument, <EM>win</EM>, is always ignored. If the
140 terminfo capabilities <STRONG>smm</STRONG> (meta_on) and <STRONG>rmm</STRONG> (meta_off) are
141 defined for the terminal, <STRONG>smm</STRONG> is sent to the terminal when
142 <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>TRUE</STRONG>) is called and <STRONG>rmm</STRONG> is sent when <STRONG>meta</STRONG>(<EM>win</EM>,
143 <STRONG>FALSE</STRONG>) is called.
145 The <STRONG>nodelay</STRONG> option causes <STRONG>getch</STRONG> to be a non-blocking call.
146 If no input is ready, <STRONG>getch</STRONG> returns <STRONG>ERR</STRONG>. If disabled (<EM>bf</EM>
147 is <STRONG>FALSE</STRONG>), <STRONG>getch</STRONG> waits until a key is pressed.
149 While interpreting an input escape sequence, <STRONG>wgetch</STRONG> sets a
150 timer while waiting for the next character. If <STRONG>notime-</STRONG>
151 <STRONG>out(</STRONG><EM>win</EM>, <STRONG>TRUE</STRONG>) is called, then <STRONG>wgetch</STRONG> does not set a
152 timer. The purpose of the timeout is to differentiate
153 between sequences received from a function key and those
156 The <STRONG>raw</STRONG> and <STRONG>noraw</STRONG> routines place the terminal into or out
157 of raw mode. Raw mode is similar to <STRONG>cbreak</STRONG> mode, in that
158 characters typed are immediately passed through to the
159 user program. The differences are that in raw mode, the
160 interrupt, quit, suspend, and flow control characters are
161 all passed through uninterpreted, instead of generating a
162 signal. The behavior of the BREAK key depends on other
163 bits in the tty driver that are not set by <STRONG>curses</STRONG>.
165 When the <STRONG>noqiflush</STRONG> routine is used, normal flush of input
166 and output queues associated with the <STRONG>INTR</STRONG>, <STRONG>QUIT</STRONG> and <STRONG>SUSP</STRONG>
167 characters will not be done [see <STRONG><A HREF="termio.7.html">termio(7)</A></STRONG>]. When <STRONG>qiflush</STRONG>
168 is called, the queues will be flushed when these control
169 characters are read. You may want to call <STRONG>noqiflush()</STRONG> in
170 a signal handler if you want output to continue as though
171 the interrupt had not occurred, after the handler exits.
173 The <STRONG>timeout</STRONG> and <STRONG>wtimeout</STRONG> routines set blocking or non-
174 blocking read for a given window. If <EM>delay</EM> is negative,
175 blocking read is used (<EM>i</EM>.<EM>e</EM>., waits indefinitely for
176 input). If <EM>delay</EM> is zero, then non-blocking read is used
177 (<EM>i</EM>.<EM>e</EM>., read returns <STRONG>ERR</STRONG> if no input is waiting). If <EM>delay</EM>
178 is positive, then read blocks for <EM>delay</EM> milliseconds, and
179 returns <STRONG>ERR</STRONG> if there is still no input. Hence, these rou-
180 tines provide the same functionality as <STRONG>nodelay</STRONG>, plus the
181 additional capability of being able to block for only
182 <EM>delay</EM> milliseconds (where <EM>delay</EM> is positive).
184 The <STRONG>curses</STRONG> library does ``line-breakout optimization'' by
185 looking for typeahead periodically while updating the
186 screen. If input is found, and it is coming from a tty,
187 the current update is postponed until <STRONG>refresh</STRONG> or <STRONG>doupdate</STRONG>
188 is called again. This allows faster response to commands
189 typed in advance. Normally, the input FILE pointer passed
190 to <STRONG>newterm</STRONG>, or <STRONG>stdin</STRONG> in the case that <STRONG>initscr</STRONG> was used,
191 will be used to do this typeahead checking. The <STRONG>typeahead</STRONG>
192 routine specifies that the file descriptor <EM>fd</EM> is to be
193 used to check for typeahead instead. If <EM>fd</EM> is -1, then no
194 typeahead checking is done.
198 <H2>RETURN VALUE</H2><PRE>
199 All routines that return an integer return <STRONG>ERR</STRONG> upon fail-
200 ure and OK (SVr4 specifies only "an integer value other
201 than <STRONG>ERR</STRONG>") upon successful completion, unless otherwise
202 noted in the preceding routine descriptions.
206 <H2>PORTABILITY</H2><PRE>
207 These functions are described in the XSI Curses standard,
210 The ncurses library obeys the XPG4 standard and the his-
211 torical practice of the AT&T curses implementations, in
212 that the echo bit is cleared when curses initializes the
213 terminal state. BSD curses differed from this slightly;
214 it left the echo bit on at initialization, but the BSD <STRONG>raw</STRONG>
215 call turned it off as a side-effect. For best portabil-
216 ity, set echo or noecho explicitly just after initializa-
217 tion, even if your program remains in cooked mode.
222 Note that <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>meta</STRONG>, <STRONG>node-</STRONG>
223 <STRONG>lay</STRONG>, <STRONG>notimeout</STRONG>, <STRONG>noqiflush</STRONG>, <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, and <STRONG>wtimeout</STRONG>
226 The <STRONG>noraw</STRONG> and <STRONG>nocbreak</STRONG> calls follow historical practice in
227 that they attempt to restore to normal (`cooked') mode
228 from raw and cbreak modes respectively. Mixing raw/noraw
229 and cbreak/nocbreak calls leads to tty driver control
230 states that are hard to predict or understand; it is not
235 <H2>SEE ALSO</H2><PRE>
236 <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>, <STRONG><A HREF="termio.7.html">termio(7)</A></STRONG>
276 Man(1) output converted with
277 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>