# curs_inopts 3x 2025-02-01 ncurses 6.5 Library calls

    curs_inopts(3x)                  Library calls                 curs_inopts(3x)

## NAME

           cbreak,  echo, halfdelay, intrflush, is_cbreak, is_echo, is_nl, is_raw,
           keypad, meta, nl, nocbreak, nodelay, noecho,  nonl,  noqiflush,  noraw,
           notimeout,  qiflush,  raw,  timeout,  wtimeout, typeahead - get and set
           curses terminal input options

## SYNOPSIS

           #include <curses.h>

           int cbreak(void);
           int nocbreak(void);

           int echo(void);
           int noecho(void);

           int intrflush(WINDOW * win /* ignored */, bool bf);
           int keypad(WINDOW * win, bool bf);
           int meta(WINDOW * win /* ignored */, bool bf);
           int nodelay(WINDOW * win, bool bf);
           int notimeout(WINDOW * win, bool bf);

           int nl(void);
           int nonl(void);

           void qiflush(void);
           void noqiflush(void);

           int raw(void);
           int noraw(void);

           int halfdelay(int tenths);
           void timeout(int delay);
           void wtimeout(WINDOW * win, int delay);

           int typeahead(int fd);

           /* extensions */
           int is_cbreak(void);
           int is_echo(void);
           int is_nl(void);
           int is_raw(void);

## DESCRIPTION

           curses offers configurable  parameters  permitting  an  application  to
           control  the  handling of input from the terminal.  Some, such as those
           affecting the terminal's mode or line discipline, are global,  applying
           to  all  windows;  others apply only to a specific window.  The library
           does not automatically apply such parameters to new or derived windows;
           an application must configure each window for the desired behavior.

           Some  descriptions  below  make reference to an input character reading
           function: this is wgetch(3x) in the non-wide character curses  API  and
           wget_wch(3x)  in  the  wide  character API.  In addition to the variant
           forms  of  these  described  in  ncurses(3x),  the   curses   functions
           wgetstr(3x)   and   wget_wstr(3x)  and  their  own  variants  call  the
           appropriate input character reading function.

### cbreak, nocbreak

           Normally, the terminal driver buffers typed characters, not  delivering
           them  to  an application until a line feed or carriage return is typed.
           This canonical ("cooked") line discipline also supports  software  flow
           control,  simple  line editing functions (character and word erase, and
           whole-line erasure or "kill"), and job control.  cbreak configures  the
           terminal  in  cbreak  mode, which disables line buffering and erase and
           kill character processing -- the interrupt,  quit,  suspend,  and  flow
           control  characters are unaffected -- and makes characters typed by the
           user immediately available to the program.  nocbreak restores canonical
           ("cooked") mode.

           The  state  of  the terminal is unknown to a curses application when it
           starts; therefore, a program should call cbreak or nocbreak explicitly.
           Most interactive programs using curses set cbreak mode.  Calling cbreak
           overrides raw.  The man page for the input character  reading  function
           discusses how cbreak and nocbreak interact with echo and noecho.

### echo, noecho

           echo  and  noecho  determine  whether  characters typed by the user are
           written to the curses window by the input character reading function as
           they  are  typed.   curses  always  disables  the terminal driver's own
           echoing.  By default, a curses screen's echo option is set.  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  call
           noecho.   The  man  page  for  the  input  character  reading  function
           discusses how echo and noecho interact with cbreak and nocbreak.

### halfdelay

           halfdelay configures half-delay mode, which is similar to  cbreak  mode
           in  that  characters typed by the user are immediately available to the
           program.  However, after blocking for tenths  tenth-seconds,  an  input
           character  reading  function  returns  ERR if no input is pending.  The
           value of tenths must be between 1 and 255.  Use nocbreak to leave half-
           delay mode.

### intrflush

           intrflush  calls qiflush (see below) if bf is TRUE, and noqiflush if bf
           is FALSE.  It ignores its win argument.

### keypad

           keypad enables recognition of a terminal's function keys.   If  enabled
           (bf  is  TRUE),  the  input  character reading function returns a value
           representing the function key, such as KEY_LEFT.   (Wide-character  API
           users:  wget_wch(3x)  returns KEY_CODE_YES to indicate the availability
           of a function key code in its  wch  parameter.)   If  disabled  (bf  is
           FALSE),  curses  does not treat function keys specially and the program
           has to interpret escape sequences itself.  If the terminal's keypad can
           be  turned on (made to transmit) and off (made to work locally), keypad
           configures it consistently  with  the  bf  parameter.   By  default,  a
           window's keypad mode is off.

### meta

           Initially,  whether the terminal returns 7- or 8-bit character codes on
           input depends on the configuration of the  terminal  driver;  on  POSIX
           systems,  see  termios(3).   To  force  8  bits  to  be  returned, call
           meta(..., TRUE); this is equivalent, on POSIX systems, to  setting  the
           CS8  flag  on  the  terminal.   To  force  7  bits to be returned, call
           meta(..., FALSE); this is equivalent, on POSIX systems, to setting  the
           CS7  flag on the terminal.  curses ignores the window argument win.  If
           the terminfo string capabilities meta_on (smm) and meta_off  (rmm)  are
           defined  for  the  terminal  type,  enabling meta mode sends smm to the
           terminal and disabling it sends rmm to the terminal.

### nl, nonl

           Initially, whether the terminal reports a  carriage  return  using  the
           character  code  for  a line feed in cbreak or raw modes depends on the
           configuration of the terminal driver; see  termios(3).   nl  configures
           the terminal to perform this translation.  nonl disables it.  Under its
           canonical  ("cooked")  line  discipline,  the  terminal  driver  always
           translates carriage returns to line feeds.

### nodelay

           nodelay  configures  the  input  character  reading function to be non-
           blocking for window win.  If no input is ready,  the  reading  function
           returns  ERR.  If disabled (bf is FALSE), the reading function does not
           return until it has input.

### notimeout

           When the input character reading function reads an  ESC  character,  it
           sets  a  timer  while  waiting  for the next character.  notimeout(win,
           TRUE)  disables  this  timer.   The  purpose  of  the  timeout  is   to
           distinguish  sequences produced by a function key from those typed by a
           user.  To configure the timeout rather than disabling it, see  wtimeout
           below.

### qiflush, noqiflush

           qiflush  and noqiflush configure the terminal driver's treatment of its
           input and output queues when it handles the interrupt, suspend, or quit
           characters under the canonical ("cooked") or cbreak line disciplines on
           POSIX systems; see termios(3).  The default behavior is inherited  from
           the  terminal driver settings.  Calling qiflush configures the terminal
           to flush the queues (discarding  their  contents)  when  any  of  these
           events  occurs, giving the impression of faster response to user input,
           but making the  library's  model  of  the  screen  contents  incorrect.
           Calling noqiflush prevents such flushing, but might frustrate impatient
           users on slow connections if a  curses  update  of  the  screen  is  in
           progress when the event occurs; see typeahead below for a mitigation of
           this problem.  You may want to call noqiflush in a signal  handler  if,
           after  the  handler  exits,  you  want output to continue as though the
           interrupt had not occurred.

### raw, noraw

           raw configures the terminal to read input in raw mode, which is similar
           to  cbreak  mode  (see  cbreak above) except that it furthermore passes
           through the terminal's configured interrupt, quit,  suspend,  and  flow
           control   characters  uninterpreted  to  the  application,  instead  of
           generating a signal or  acting  on  I/O  flow.   The  behavior  of  the
           terminal's   "Break"   key   (if   any)   depends  on  terminal  driver
           configuration parameters that curses does not handle.   noraw  restores
           the terminal's canonical ("cooked") line discipline.

### timeout, wtimeout

           wtimeout  configures  whether a curses input character reading function
           called on window win uses blocking or non-blocking reads.  If delay  is
           negative,  curses uses a blocking read, waiting indefinitely for input.
           If delay is zero, the read is non-blocking; an input character  reading
           function  returns ERR if no input is pending.  If delay is positive, an
           input character reading function blocks  for  delay  milliseconds,  and
           returns  ERR  if the delay elapses and there is still no input pending.
           timeout calls wtimeout on stdscr.

### typeahead

           Normally, a curses library checks the terminal for input while updating
           the  screen.   If  any is found, the update is postponed until the next
           wrefresh(3x) or doupdate(3x) call, allowing faster response to user key
           strokes.   The  library  tests the file descriptor corresponding to the
           FILE stream pointer passed to newterm(3x) (or stdin if initscr(3x)  was
           called),  for  pending  input.  typeahead instructs curses to test file
           descriptor fd instead.  An fd of -1 disables the check.

## RETURN VALUE

           timeout and wtimeout return no value.

           cbreak, nocbreak, echo, noecho,  halfdelay,  intrflush,  keypad,  meta,
           nodelay,  notimeout,  nl,  nonl, raw, noraw, and typeahead return OK on
           success and ERR on failure.

           In ncurses, the functions in the previous paragraph return ERR if

           o   the library's TERMINAL  structure  for  the  device  has  not  been
               initialized with initscr(3x), newterm(3x), or setupterm(3x), or

           o   win is a null pointer (except with intrflush and meta, which ignore
               its value).

           Further, halfdelay returns ERR if delay is outside the range 1..255.

           See section "EXTENSIONS" below for  the  return  values  of  is_cbreak,
           is_echo, is_nl, and is_raw.

## NOTES

           echo, noecho, halfdelay, intrflush, meta, nl, nonl, nodelay, notimeout,
           noqiflush, qiflush, timeout, and wtimeout may be implemented as macros.

           noraw and nocbreak follow historical practice in that they  attempt  to
           restore  the  terminal's  canonical ("cooked") line discipline from raw
           and cbreak, respectively.  Mixing raw/noraw calls with  cbreak/nocbreak
           calls  leads to terminal driver control states that are hard to predict
           or understand; doing so is not recommended.

## EXTENSIONS

           ncurses provides four "is_" functions corresponding  to  cbreak,  echo,
           nl, and raw, permitting their states to be queried by the application.

                                Query       Set      Reset
                                ------------------------------
                                is_cbreak   cbreak   nocbreak
                                is_echo     echo     noecho
                                is_nl       nl       nonl
                                is_raw      raw      noraw

           In each case, the function returns

           1    if the option is set,

           0    if the option is unset, or

           -1   if  the  library's  TERMINAL structure for the device has not been
                initialized.

## PORTABILITY

           Applications employing ncurses extensions should condition their use on
           the visibility of the NCURSES_VERSION preprocessor macro.

           Except  as  noted  in section "EXTENSIONS" above, X/Open Curses Issue 4
           describes these functions.  It specifies no error conditions for them.

           SVr4 describes a successful return value  only  as  "an  integer  value
           other than ERR".

           ncurses  follows  X/Open Curses and the historical practice of System V
           curses, clearing the terminal driver's "echo"  flag  when  initializing
           the  screen.  BSD curses did not, but its raw function turned it off as
           a side effect.  For best portability, call echo  or  noecho  explicitly
           just  after initialization, even if your program retains the terminal's
           canonical ("cooked") line discipline.

           X/Open Curses is ambiguous regarding whether  raw  should  disable  the
           carriage  return and line feed translation feature controlled by nl and
           nonl.  BSD curses did turn off these translations; System V curses  did
           not.   ncurses  does so, on the assumption 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,  for example, by using the -x option of
           tic(1), then ncurses also defines keys for the capabilities whose names
           begin  with  "k".  Corresponding key codes are generated and (depending
           on previous  loads  of  terminal  descriptions)  may  differ  from  one
           execution  of  a  program  to  the  next.   The generated key codes are
           recognized by keyname(3x), which then returns a name beginning with "k"
           denoting  the terminfo capability name rather than "K", used for curses
           key names.  On the other hand, an application can use define_key(3x) to
           bind  a  specific  key  to  a  string of the programmer's choice.  This
           feature  enables  an  application  to  check  for  its  presence   with
           tigetstr(3x), and reassign the key code to match its own needs.

           Low-level applications can use tigetstr(3x) to obtain the definition of
           any string capability.  curses applications  use  the  input  character
           reading function to obtain key codes from input and rely upon the order
           in which the string capabilities are loaded.  Multiple  key  capability
           strings  can  have  the  same  value,  but  the input character reading
           function can report only one key  code.   Most  curses  implementations
           (including  ncurses)  load  key definitions in the order they appear in
           the strfnames array of string capability names; see term_variables(3x).
           The  last  capability read using a particular definition determines the
           key code to be reported.  In  ncurses,  extended  capabilities  can  be
           interpreted  as key definitions.  These are loaded after the predefined
           keys, and if a capability's value is the same as  a  previously  loaded
           key definition, the library uses the later definition.

## HISTORY

           4BSD (1980) introduced echo, noecho, nl, nonl, raw, and noraw.

           SVr2 (1984) featured a new terminal driver, extending the curses API to
           support it with cbreak, nocbreak, intrflush, keypad, meta, nodelay, and
           typeahead.

           SVr3  (1987)  added  halfdelay,  notimeout,  and wtimeout.  qiflush and
           noqiflush appeared in SVr3.1 (1987), at which point intrflush became  a
           wrapper  for  either  of these functions, depending on the value of its
           Boolean argument.  SVr3.1 also added timeout.

           ncurses 6.5 (2024) introduced is_cbreak, is_echo, is_nl, and is_raw.

           Formerly, ncurses used  nl  and  nonl  to  control  the  conversion  of
           newlines  to  carriage  return/line  feed  on  output as well as input.
           X/Open Curses documents the use of  these  functions  only  for  input.
           This  difference arose from converting the pcurses source (1986), which
           used ioctl(2) calls and the sgttyb structure,  to  termios  (the  POSIX
           terminal  API).   In  the former, both input and output were controlled
           via a single option "CRMOD", while the latter separates these features.
           Because  that  conversion  interferes with output optimization, ncurses
           6.2 (2020) amended nl and nonl to eliminate their effect on output.

## SEE ALSO

           curses(3x),    curs_getch(3x),     curs_initscr(3x),     curs_util(3x),
           define_key(3x), termios(3), term_variables(3x)

    ncurses 6.5                       2025-02-01                   curs_inopts(3x)