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