curs_inopts 3x 2024-06-15 ncurses 6.5 Library calls

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


       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


       #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);


       curses offers configurable  parameters  permitting  an  application  to
       control  the  handling  of  input  from the terminal.  Some 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

       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.
       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 returns the terminal to normal ("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  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 tenths of 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 calls qiflush (see below) if bf is TRUE, and noqiflush if  bf
       is FALSE.  It ignores its win argument.


       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.


       Initially, whether the terminal returns 7- or 8-bit character codes  on
       input  depends  on  the  configuration  of  the  terminal  driver;  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.  The window argument, win, is always ignored.  If  the  term-
       info  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.  In normal
       (or  "cooked")  mode,  the  terminal  driver always translates carriage
       returns to line feeds.


       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.


       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

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  in  cbreak  and  "cooked"  modes;  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
       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 you want output to continue after the handler exits
       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  returns
       the terminal to normal ("cooked") mode.

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,  a blocking read is used, waiting indefinitely for input.  If
       delay is zero, a non-blocking read is used; 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.


       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.


       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 terminal is not initialized or

       o   win is NULL (except  for  intrflush  and  meta,  which  ignore  its

       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.


       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 normal ("cooked") mode from raw and cbreak modes, 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.


       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 reset, or

       -1   if the library is not initialized.


       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 curses 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 remains in normal
       ("cooked") mode.

       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 later definition is the one used.


       4BSD curses (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

       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.


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

ncurses 6.5                       2024-06-15                   curs_inopts(3x)