# curs_inopts

## NAME



           **cbreak** , **nocbreak** , **echo** , **noecho** , **halfdelay** , **intrflush** , **keypad** ,
           **meta** , **nl** , **nonl** , **nodelay** , **notimeout** , **raw** , **noraw** , **qiflush** ,
           **noqiflush** , **timeout** , **wtimeout** , **typeahead** - **curses** input options
    


## SYNOPSIS



           **#include <curses.h>**
    
           **int cbreak(void);**
           **int nocbreak(void);**
    
           **int echo(void);**
           **int noecho(void);**
    
           **int intrflush(WINDOW ***_win_**, bool** _bf_**);**
           **int keypad(WINDOW ***_win_**, bool** _bf_**);**
           **int meta(WINDOW ***_win_**, bool** _bf_**);**
           **int nodelay(WINDOW ***_win_**, bool** _bf_**);**
           **int notimeout(WINDOW ***_win_**, bool** _bf_**);**
    
           **int nl(void);**
           **int nonl(void);**
    
           **int raw(void);**
           **int noraw(void);**
    
           **void qiflush(void);**
           **void noqiflush(void);**
    
           **int halfdelay(int** _tenths_**);**
           **void timeout(int** _delay_**);**
           **void wtimeout(WINDOW ***_win_**, int** _delay_**);**
    
           **int typeahead(int** _fd_**);**
    


## DESCRIPTION



           The **ncurses** library provides several functions which let an appli‐
           cation  change  the  way input from the terminal is handled.  Some
           are global, applying to all windows.  Others apply only to a  spe‐
           cific  window.  Window-specific settings are not automatically ap‐
           plied to new or derived windows.  An application must apply  these
           to each window, if the same behavior is needed.
    
       **cbreak/nocbreak**
           Normally,  the tty driver buffers typed characters until a newline
           or carriage return is typed.  The  **cbreak** routine  disables  line
           buffering  and erase/kill character-processing (interrupt and flow
           control characters are unaffected), making characters typed by the
           user immediately available to the program.  The  **nocbreak** routine
           returns the terminal to normal (cooked) mode.
    
           Initially  the  terminal  may or may not be in **cbreak** mode, as the
           mode is inherited; therefore, a  program  should  call  **cbreak** or
           **nocbreak** explicitly.   Most interactive programs using **curses** set
           the  **cbreak** mode.   Note  that  **cbreak** overrides   **raw**.    [See
           **curs_getch**(3X)  for  a  discussion  of how these routines interact
           with **echo** and **noecho**.]
    
       **echo/noecho**
           The **echo** and **noecho** routines control whether characters  typed  by
           the  user  are  echoed by **getch**(3X) as they are typed.  Echoing by
           the tty driver is always disabled, but initially **getch** is in  echo
           mode, so characters typed are echoed.  Authors of most interactive
           programs  prefer  to  do their own echoing in a controlled area of
           the screen, or not to echo at all,  so  they  disable  echoing  by
           calling **noecho**.  [See **curs_getch**(3X) for a discussion of how these
           routines interact with **cbreak** and **nocbreak**.]
    
       **halfdelay**
           The  **halfdelay** routine is used for half-delay mode, which is simi‐
           lar to **cbreak** mode in that characters typed by the user are  imme‐
           diately  available  to  the  program.  However, after blocking for
           _tenths_ tenths of seconds, **ERR** is  returned  if  nothing  has  been
           typed.   The  value  of _tenths_ must be a number between 1 and 255.
           Use **nocbreak** to leave half-delay mode.
    
       **intrflush**
           If the **intrflush** option is enabled (_bf_ is **TRUE**), and an  interrupt
           key  is pressed on the keyboard (interrupt, break, quit), all out‐
           put in the tty driver queue will be flushed, giving the effect  of
           faster  response  to the interrupt, but causing **curses** to have the
           wrong idea of what is on the screen.  Disabling the option (_bf_  is
           **FALSE**) prevents the flush.  The default for the option is inherit‐
           ed from the tty driver settings.  The window argument is ignored.
    
       **keypad**
           The  **keypad** option enables the keypad of the user's terminal.  If
           enabled (_bf_ is **TRUE**), the user can press a function key  (such  as
           an  arrow  key) and **wgetch**(3X) returns a single value representing
           the function key, as in **KEY_LEFT**.   If  disabled  (_bf_  is  **FALSE**),
           **curses** does not treat function keys specially and the program has
           to interpret the escape sequences itself.  If the  keypad  in  the
           terminal can be turned on (made to transmit) and off (made to work
           locally),  turning on this option causes the terminal keypad to be
           turned on when **wgetch**(3X) is called.  The default value for keypad
           is **FALSE**.
    
       **meta**
           Initially, whether the terminal returns 7 or 8 significant bits on
           input  depends  on  the  control  mode  of  the  tty  driver  [see
           termios(3)].   To  force  8  bits to be returned, invoke **meta**(_win_ ,
           **TRUE**); this is equivalent, under POSIX, to setting the CS8 flag on
           the terminal.  To force 7 bits to be  returned,  invoke  **meta**(_win_ ,
           **FALSE**);  this  is equivalent, under POSIX, to setting the CS7 flag
           on the terminal.  The window argument, _win_ , is always ignored.  If
           the terminfo capabilities **smm**(meta_on) and **rmm**(meta_off) are de‐
           fined for the terminal, **smm** is sent to the terminal when **meta**(_win_ ,
           **TRUE**) is called and **rmm** is sent when **meta**(_win_ , **FALSE**) is called.
    
       **nl/nonl**
           The **nl** and **nonl** routines control whether  the  underlying  display
           device translates the return key into newline on input.
    
       **nodelay**
           The  **nodelay** option causes **getch** to be a non-blocking call.  If no
           input is ready, **getch** returns **ERR**.  If  disabled  (_bf_  is  **FALSE**),
           **getch** waits until a key is pressed.
    
       **notimeout**
           When  interpreting  an  escape  sequence,  **wgetch**(3X) sets a timer
           while waiting for the next character.  If **notimeout(**_win_ , **TRUE**)  is
           called,  then  **wgetch** does  not  set a timer.  The purpose of the
           timeout is to differentiate  between  sequences  received  from  a
           function key and those typed by a user.
    
       **raw/noraw**
           The  **raw** and **noraw** routines place the terminal into or out of raw
           mode.  Raw mode is similar to  **cbreak** mode,  in  that  characters
           typed  are  immediately  passed  through to the user program.  The
           differences are that in raw mode, the  interrupt,  quit,  suspend,
           and  flow control characters are all passed through uninterpreted,
           instead of generating a signal.  The behavior of the BREAK key de‐
           pends on other bits in the tty driver that are not set by **curses**.
    
       **qiflush/noqiflush**
           When the **noqiflush** routine is used, normal flush of input and out‐
           put queues associated with the **INTR** , **QUIT** and **SUSP** characters will
           not be done [see termios(3)].  When **qiflush** is called, the  queues
           will  be  flushed when these control characters are read.  You may
           want to call **noqiflush** in a signal handler if you want  output  to
           continue  as though the interrupt had not occurred, after the han‐
           dler exits.
    
       **timeout/wtimeout**
           The **timeout** and **wtimeout** routines  set  blocking  or  non-blocking
           read  for  a given window.  If _delay_ is negative, blocking read is
           used (i.e., waits indefinitely for input).  If _delay_ is zero, then
           non-blocking read is used (i.e., read returns **ERR** if no  input  is
           waiting).   If  _delay_ is positive, then read blocks for _delay_ mil‐
           liseconds, and returns **ERR** if there is  still  no  input.   Hence,
           these routines provide the same functionality as **nodelay** , plus the
           additional  capability  of being able to block for only _delay_ mil‐
           liseconds (where _delay_ is positive).
    
       **typeahead**
           The **curses** library does “line-breakout  optimization”  by  looking
           for typeahead periodically while updating the screen.  If input is
           found,  and  it  is coming from a tty, the current update is post‐
           poned until **refresh**(3X) or **doupdate** is called again.  This  allows
           faster response to commands typed in advance.  Normally, the input
           FILE  pointer passed to **newterm** , or **stdin** in the case that **initscr**
           was used, will be used to do this typeahead checking.  The  **typea‐**
           **head** routine  specifies that the file descriptor _fd_ is to be used
           to check for typeahead instead.  If _fd_ is -1,  then  no  typeahead
           checking is done.
    


## RETURN VALUE



           All routines that return an integer return **ERR** upon failure and **OK**
           (SVr4  specifies only “an integer value other than **ERR** ”) upon suc‐
           cessful completion, unless otherwise noted in the  preceding  rou‐
           tine descriptions.
    
           X/Open  does not define any error conditions.  In this implementa‐
           tion, functions with a window parameter will return an error if it
           is null.  Any function will also return an error if  the  terminal
           was not initialized.  Also,
    
                  **halfdelay**
                       returns an error if its parameter is outside the range
                       1..255.
    


## PORTABILITY



           These functions are described in the XSI Curses standard, Issue 4.
    
           The ncurses library obeys the XPG4 standard and the historical
           practice of the AT&T curses implementations, in that the echo bit
           is cleared when curses initializes the terminal state.  BSD curses
           differed from this slightly; it left the echo bit on at initial‐
           ization, but the BSD **raw** call turned it off as a side-effect.  For
           best portability, set **echo** or **noecho** explicitly just after ini‐
           tialization, even if your program remains in cooked mode.
    
           The XSI Curses standard is ambiguous on the question of whether
           **raw** should disable the CRLF translations controlled by **nl** and
           **nonl**.  BSD curses did turn off these translations; AT&T curses (at
           least as late as SVr1) did not.  We chose to do so, on the theory
           that a programmer requesting raw input wants a clean (ideally
           8-bit clean) connection that the operating system will not alter.
    
           When **keypad** is first enabled, ncurses loads the key-definitions
           for the current terminal description.  If the terminal description
           includes extended string capabilities, e.g., from using the **-x** op‐
           tion of **tic** , then ncurses also defines keys for the capabilities
           whose names begin with “k”.  The corresponding keycodes are gener‐
           ated and (depending on previous loads of terminal descriptions)
           may differ from one execution of a program to the next.  The gen‐
           erated keycodes are recognized by the **keyname** function (which will
           then return a name beginning with “k” denoting the terminfo capa‐
           bility name rather than “K”, used for curses key-names).  On the
           other hand, an application can use **define_key** to establish a spe‐
           cific keycode for a given string.  This makes it possible for an
           application to check for an extended capability's presence with
           **tigetstr** , and reassign the keycode to match its own needs.
    
           Low-level applications can use **tigetstr** to obtain the definition
           of any particular string capability.  Higher-level applications
           which use the curses **wgetch** and similar functions to return key‐
           codes rely upon the order in which the strings are loaded.  If
           more than one key definition has the same string value, then
           **wgetch** can return only one keycode.  Most curses implementations
           (including ncurses) load key definitions in the order defined by
           the array of string capability names.  The last key to be loaded
           determines the keycode which will be returned.  In ncurses, you
           may also have extended capabilities interpreted as key defini‐
           tions.  These are loaded after the predefined keys, and if a capa‐
           bility's value is the same as a previously-loaded key definition,
           the later definition is the one used.
    


## NOTES



           Note that **echo** , **noecho** , **halfdelay** , **intrflush** , **meta** , **nl** , **nonl** ,
           **nodelay** , **notimeout** , **noqiflush** , **qiflush** , **timeout** , and **wtimeout** may
           be macros.
    
           The **noraw** and **nocbreak** calls follow historical practice in that
           they attempt to restore to normal (“cooked”) mode from raw and
           cbreak modes respectively.  Mixing raw/noraw and cbreak/nocbreak
           calls leads to tty driver control states that are hard to predict
           or understand; it is not recommended.
    


* * *