4776a17f5e50b6e2c48814213a695b5bcea22a66
[ncurses.git] / doc / html / man / curs_inopts.3x.html
1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
2 <!-- 
3   ****************************************************************************
4   * Copyright (c) 1998-2005,2010 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_inopts.3x,v 1.14 2010/07/31 16:11:27 tom Exp @
31 -->
32 <HTML>
33 <HEAD>
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">
37 </HEAD>
38 <BODY>
39 <H1>curs_inopts 3x</H1>
40 <HR>
41 <PRE>
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>
44
45
46
47
48 </PRE>
49 <H2>NAME</H2><PRE>
50        <STRONG>cbreak</STRONG>, <STRONG>nocbreak</STRONG>, <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>,
51        <STRONG>keypad</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
53        options
54
55
56 </PRE>
57 <H2>SYNOPSIS</H2><PRE>
58        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
59
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>
77
78
79 </PRE>
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 unaffect-
85        ed), 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.
88
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>.]
95
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 initial-
99        ly <STRONG>getch</STRONG> is in echo mode, so characters typed are  echoed.
100        Authors  of  most  interactive programs prefer to do their
101        own echoing in a controlled area of the screen, or not  to
102        echo  at  all,  so they disable echoing by calling <STRONG>noecho</STRONG>.
103        [See <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> for a discussion of how these routines
104        interact with <STRONG>cbreak</STRONG> and <STRONG>nocbreak</STRONG>.]
105
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  re-
110        turned  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
112        half-delay mode.
113
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  in-
118        terrupt, but causing <STRONG>curses</STRONG> to have the wrong idea of what
119        is on the screen.  Disabling (<EM>bf</EM>  is  <STRONG>FALSE</STRONG>),  the  option
120        prevents  the flush.  The default for the option is inher-
121        ited from the tty driver settings.  The window argument is
122        ignored.
123
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  local-
132        ly),  turning on this option causes the terminal keypad to
133        be turned on when <STRONG>wgetch</STRONG> is called.  The default value for
134        keypad is false.
135
136        Initially, whether the terminal returns 7 or 8 significant
137        bits on input depends on the control mode of the tty driv-
138        er  [see  <STRONG><A HREF="termio.7.html">termio(7)</A></STRONG>].  To force 8 bits to be returned, in-
139        voke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>TRUE</STRONG>); this is equivalent, under POSIX,  to
140        setting  the CS8 flag on the terminal.  To force 7 bits to
141        be returned, invoke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>FALSE</STRONG>); this is  equivalent,
142        under POSIX, to setting the CS7 flag on the terminal.  The
143        window argument, <EM>win</EM>, is always ignored.  If the  terminfo
144        capabilities  <STRONG>smm</STRONG> (meta_on) and <STRONG>rmm</STRONG> (meta_off) are defined
145        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.
148
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.
152
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 be-
157        tween sequences received from a  function  key  and  those
158        typed by a user.
159
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 us-
163        er program.  The differences are that in raw mode, the in-
164        terrupt,  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>.
168
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.
176
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  in-
180        put).   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  <EM>de-</EM>
186        <EM>lay</EM> milliseconds (where <EM>delay</EM> is positive).
187
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.
199
200
201 </PRE>
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.
207
208        X/Open does not define any error conditions.  In this  im-
209        plementation,  functions  with a window parameter will re-
210        turn an error if it is null.  Any function will  also  re-
211        turn an error if the terminal was not initialized.  Also,
212
213               <STRONG>halfdelay</STRONG>
214                    returns  an  error if its parameter is outside
215                    the range 1..255.
216
217
218 </PRE>
219 <H2>PORTABILITY</H2><PRE>
220        These functions are described in the XSI Curses  standard,
221        Issue 4.
222
223        The  ncurses  library obeys the XPG4 standard and the his-
224        torical practice of the AT&amp;T  curses  implementations,  in
225        that  the  echo bit is cleared when curses initializes the
226        terminal state.  BSD curses differed from  this  slightly;
227        it left the echo bit on at initialization, but the BSD <STRONG>raw</STRONG>
228        call turned it off as a side-effect.  For best  portabili-
229        ty,  set  echo or noecho explicitly just after initializa-
230        tion, even if your program remains in cooked mode.
231
232
233 </PRE>
234 <H2>NOTES</H2><PRE>
235        Note that <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>meta</STRONG>,  <STRONG>node-</STRONG>
236        <STRONG>lay</STRONG>,  <STRONG>notimeout</STRONG>, <STRONG>noqiflush</STRONG>, <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, and <STRONG>wtimeout</STRONG>
237        may be macros.
238
239        The <STRONG>noraw</STRONG> and <STRONG>nocbreak</STRONG> calls follow historical practice in
240        that  they  attempt  to  restore to normal (`cooked') mode
241        from raw and cbreak modes respectively.  Mixing  raw/noraw
242        and  cbreak/nocbreak  calls  leads  to  tty driver control
243        states that are hard to predict or understand; it  is  not
244        recommended.
245
246
247 </PRE>
248 <H2>SEE ALSO</H2><PRE>
249        <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>
250
251
252
253                                                         <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
254 </PRE>
255 <HR>
256 <ADDRESS>
257 Man(1) output converted with
258 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
259 </ADDRESS>
260 </BODY>
261 </HTML>