doc/html/man/curs_inopts.3x.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
   2 <!--
   3   ****************************************************************************
   4   * Copyright (c) 1998-2003,2005 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.13 2005/05/15 16:18:07 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>