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

   1 <!--
   2   * t
   3   ****************************************************************************
   4   * Copyright 2018-2023,2024 Thomas E. Dickey                                *
   5   * Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
   6   *                                                                          *
   7   * Permission is hereby granted, free of charge, to any person obtaining a  *
   8   * copy of this software and associated documentation files (the            *
   9   * "Software"), to deal in the Software without restriction, including      *
  10   * without limitation the rights to use, copy, modify, merge, publish,      *
  11   * distribute, distribute with modifications, sublicense, and/or sell       *
  12   * copies of the Software, and to permit persons to whom the Software is    *
  13   * furnished to do so, subject to the following conditions:                 *
  14   *                                                                          *
  15   * The above copyright notice and this permission notice shall be included  *
  16   * in all copies or substantial portions of the Software.                   *
  17   *                                                                          *
  18   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  19   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  20   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  21   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  22   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  23   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  24   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  25   *                                                                          *
  26   * Except as contained in this notice, the name(s) of the above copyright   *
  27   * holders shall not be used in advertising or otherwise to promote the     *
  28   * sale, use or other dealings in this Software without prior written       *
  29   * authorization.                                                           *
  30   ****************************************************************************
  31   * @Id: curs_inopts.3x,v 1.73 2024/06/08 23:24:17 tom Exp @
  32 -->
  33 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  34 <HTML>
  35 <HEAD>
  36 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  37 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  38 <TITLE>curs_inopts 3x 2024-06-08 ncurses 6.5 Library calls</TITLE>
  39 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  40
  41 </HEAD>
  42 <BODY>
  43 <H1 class="no-header">curs_inopts 3x 2024-06-08 ncurses 6.5 Library calls</H1>
  44 <PRE>
  45 <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>                  Library calls                 <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
  46
  47
  48
  49
  50 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  51        <STRONG>cbreak</STRONG>,  <STRONG>echo</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>is_cbreak</STRONG>, <STRONG>is_echo</STRONG>, <STRONG>is_nl</STRONG>, <STRONG>is_raw</STRONG>,
  52        <STRONG>keypad</STRONG>, <STRONG>meta</STRONG>, <STRONG>nl</STRONG>, <STRONG>nocbreak</STRONG>, <STRONG>nodelay</STRONG>, <STRONG>noecho</STRONG>,  <STRONG>nonl</STRONG>,  <STRONG>noqiflush</STRONG>,  <STRONG>noraw</STRONG>,
  53        <STRONG>notimeout</STRONG>,  <STRONG>qiflush</STRONG>,  <STRONG>raw</STRONG>,  <STRONG>timeout</STRONG>,  <STRONG>wtimeout</STRONG>, <STRONG>typeahead</STRONG> - get and set
  54        <EM>curses</EM> terminal input options
  55
  56
  57 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></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
  63        <STRONG>int</STRONG> <STRONG>echo(void);</STRONG>
  64        <STRONG>int</STRONG> <STRONG>noecho(void);</STRONG>
  65
  66        <STRONG>int</STRONG> <STRONG>intrflush(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM> <EM>/*</EM> <EM>ignored</EM> <EM>*/</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
  67        <STRONG>int</STRONG> <STRONG>keypad(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
  68        <STRONG>int</STRONG> <STRONG>meta(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM> <EM>/*</EM> <EM>ignored</EM> <EM>*/</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
  69        <STRONG>int</STRONG> <STRONG>nodelay(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
  70        <STRONG>int</STRONG> <STRONG>notimeout(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
  71
  72        <STRONG>int</STRONG> <STRONG>nl(void);</STRONG>
  73        <STRONG>int</STRONG> <STRONG>nonl(void);</STRONG>
  74
  75        <STRONG>void</STRONG> <STRONG>qiflush(void);</STRONG>
  76        <STRONG>void</STRONG> <STRONG>noqiflush(void);</STRONG>
  77
  78        <STRONG>int</STRONG> <STRONG>raw(void);</STRONG>
  79        <STRONG>int</STRONG> <STRONG>noraw(void);</STRONG>
  80
  81        <STRONG>int</STRONG> <STRONG>halfdelay(int</STRONG> <EM>tenths</EM><STRONG>);</STRONG>
  82        <STRONG>void</STRONG> <STRONG>timeout(int</STRONG> <EM>delay</EM><STRONG>);</STRONG>
  83        <STRONG>void</STRONG> <STRONG>wtimeout(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>delay</EM><STRONG>);</STRONG>
  84
  85        <STRONG>int</STRONG> <STRONG>typeahead(int</STRONG> <EM>fd</EM><STRONG>);</STRONG>
  86
  87        <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
  88        <STRONG>int</STRONG> <STRONG>is_cbreak(void);</STRONG>
  89        <STRONG>int</STRONG> <STRONG>is_echo(void);</STRONG>
  90        <STRONG>int</STRONG> <STRONG>is_nl(void);</STRONG>
  91        <STRONG>int</STRONG> <STRONG>is_raw(void);</STRONG>
  92
  93
  94 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  95        <EM>curses</EM> offers configurable  parameters  permitting  an  application  to
  96        control  the  handling  of  input  from the terminal.  Some are global,
  97        applying to all windows; others apply only to a specific  window.   The
  98        library  does not automatically apply such parameters to new or derived
  99        windows; an application must configure  each  window  for  the  desired
 100        behavior.
 101
 102        Some  descriptions  below  make reference to an <EM>input</EM> <EM>character</EM> <EM>reading</EM>
 103        <EM>function</EM>: this is <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> in the non-wide character <EM>curses</EM>  API  and
 104        <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG>  in  the  wide  character API.  In addition to the variant
 105        forms  of  these  described  in  <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>,  the   <EM>curses</EM>   functions
 106        <STRONG><A HREF="curs_getstr.3x.html">wgetstr(3x)</A></STRONG>   and   <STRONG><A HREF="curs_get_wstr.3x.html">wget_wstr(3x)</A></STRONG>  and  their  own  variants  call  the
 107        appropriate input character reading function.
 108
 109
 110 </PRE><H3><a name="h3-cbreak_nocbreak">cbreak, nocbreak</a></H3><PRE>
 111        Normally, the terminal driver buffers typed characters, not  delivering
 112        them  to  an application until a line feed or carriage return is typed.
 113        <STRONG>cbreak</STRONG> configures the terminal in  <EM>cbreak</EM>  <EM>mode</EM>,  which  disables  line
 114        buffering and erase and kill character processing (the interrupt, quit,
 115        suspend,  and  flow  control  characters  are  unaffected)  and   makes
 116        characters  typed  by  the  user  immediately available to the program.
 117        <STRONG>nocbreak</STRONG> returns the terminal to normal ("cooked") mode.
 118
 119        The state of the terminal is unknown to a <EM>curses</EM>  application  when  it
 120        starts; therefore, a program should call <STRONG>cbreak</STRONG> or <STRONG>nocbreak</STRONG> explicitly.
 121        Most interactive programs using <EM>curses</EM> set cbreak mode.  Calling <STRONG>cbreak</STRONG>
 122        overrides  <STRONG>raw</STRONG>.   The man page for the input character reading function
 123        discusses how <STRONG>cbreak</STRONG> and <STRONG>nocbreak</STRONG> interact with <STRONG>echo</STRONG> and <STRONG>noecho</STRONG>.
 124
 125
 126 </PRE><H3><a name="h3-echo_noecho">echo, noecho</a></H3><PRE>
 127        <STRONG>echo</STRONG> and <STRONG>noecho</STRONG> determine whether characters  typed  by  the  user  are
 128        written to the <EM>curses</EM> window by the input character reading function as
 129        they are typed.  <EM>curses</EM>  always  disables  the  terminal  driver's  own
 130        echoing.  By default, a <EM>curses</EM> screen's echo option is set.  Authors of
 131        most  interactive  programs  prefer  to  do  their  own  echoing  in  a
 132        controlled  area  of  the  screen,  or not to echo at all, so they call
 133        <STRONG>noecho</STRONG>.   The  man  page  for  the  input  character  reading  function
 134        discusses how <STRONG>echo</STRONG> and <STRONG>noecho</STRONG> interact with <STRONG>cbreak</STRONG> and <STRONG>nocbreak</STRONG>.
 135
 136
 137 </PRE><H3><a name="h3-halfdelay">halfdelay</a></H3><PRE>
 138        <STRONG>halfdelay</STRONG>  configures  <EM>half-delay</EM> <EM>mode</EM>, which is similar to cbreak mode
 139        in that characters typed by the user are immediately available  to  the
 140        program.   However,  after  blocking  for  <EM>tenths</EM> tenths of seconds, an
 141        input character reading function returns <STRONG>ERR</STRONG> if no  input  is  pending.
 142        The  value  of <EM>tenths</EM> must be between 1 and 255.  Use <STRONG>nocbreak</STRONG> to leave
 143        half-delay mode.
 144
 145
 146 </PRE><H3><a name="h3-intrflush">intrflush</a></H3><PRE>
 147        <STRONG>intrflush</STRONG> calls <STRONG>qiflush</STRONG> (see below) if <EM>bf</EM> is <STRONG>TRUE</STRONG>, and <STRONG>noqiflush</STRONG> if  <EM>bf</EM>
 148        is <STRONG>FALSE</STRONG>.  It ignores its <EM>win</EM> argument.
 149
 150
 151 </PRE><H3><a name="h3-keypad">keypad</a></H3><PRE>
 152        <STRONG>keypad</STRONG>  enables  recognition of a terminal's function keys.  If enabled
 153        (<EM>bf</EM> is <STRONG>TRUE</STRONG>), the input character  reading  function  returns  a  value
 154        representing  the  function key, such as <STRONG>KEY_LEFT</STRONG>.  (Wide-character API
 155        users: <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG> returns <STRONG>KEY_CODE_YES</STRONG> to indicate  the  availability
 156        of  a  function  key  code  in  its <EM>wch</EM> parameter.)  If disabled (<EM>bf</EM> is
 157        <STRONG>FALSE</STRONG>), <EM>curses</EM> does not treat function keys specially and  the  program
 158        has to interpret escape sequences itself.  If the terminal's keypad can
 159        be turned on (made to transmit) and off (made to work locally),  <STRONG>keypad</STRONG>
 160        configures  it  consistently  with  the  <EM>bf</EM>  parameter.   By default, a
 161        window's keypad mode is off.
 162
 163
 164 </PRE><H3><a name="h3-meta">meta</a></H3><PRE>
 165        Initially, whether the terminal returns 7- or 8-bit character codes  on
 166        input  depends  on  the  configuration  of  the  terminal  driver;  see
 167        <STRONG>termios(3)</STRONG>.  To force 8 bits to be returned, call <STRONG>meta(</STRONG>...<STRONG>,</STRONG> <STRONG>TRUE)</STRONG>; this
 168        is  equivalent,  on  POSIX  systems,  to  setting  the  CS8 flag on the
 169        terminal.  To force 7 bits to be returned, call <STRONG>meta(</STRONG>...<STRONG>,</STRONG> <STRONG>FALSE)</STRONG>;  this
 170        is  equivalent,  on  POSIX  systems,  to  setting  the  CS7 flag on the
 171        terminal.  The window argument, <EM>win</EM>, is always ignored.  If  the  <EM>term-</EM>
 172        <EM>info</EM>  string  capabilities <STRONG>meta_on</STRONG> (<STRONG>smm</STRONG>) and <STRONG>meta_off</STRONG> (<STRONG>rmm</STRONG>) are defined
 173        for the terminal type, enabling meta mode sends <STRONG>smm</STRONG> to the terminal and
 174        disabling it sends <STRONG>rmm</STRONG> to the terminal.
 175
 176
 177 </PRE><H3><a name="h3-nl_nonl">nl, nonl</a></H3><PRE>
 178        Initially,  whether  the  terminal  reports a carriage return using the
 179        character code for a line feed in cbreak or raw modes  depends  on  the
 180        configuration  of  the  terminal driver; see <STRONG>termios(3)</STRONG>.  <STRONG>nl</STRONG> configures
 181        the terminal to perform this translation.  <STRONG>nonl</STRONG> disables it.  In normal
 182        (or  "cooked")  mode,  the  terminal  driver always translates carriage
 183        returns to line feeds.
 184
 185
 186 </PRE><H3><a name="h3-nodelay">nodelay</a></H3><PRE>
 187        <STRONG>nodelay</STRONG> configures the input character  reading  function  to  be  non-
 188        blocking  for  window  <EM>win</EM>.  If no input is ready, the reading function
 189        returns <STRONG>ERR</STRONG>.  If disabled (<EM>bf</EM> is <STRONG>FALSE</STRONG>), the reading function does  not
 190        return until it has input.
 191
 192
 193 </PRE><H3><a name="h3-notimeout">notimeout</a></H3><PRE>
 194        When  the  input  character reading function reads an ESC character, it
 195        sets a timer while waiting  for  the  next  character.   <STRONG>notimeout(</STRONG><EM>win</EM><STRONG>,</STRONG>
 196        <STRONG>TRUE)</STRONG>   disables  this  timer.   The  purpose  of  the  timeout  is  to
 197        distinguish sequences produced by a function key from those typed by  a
 198        user.   To configure the timeout rather than disabling it, see <STRONG>wtimeout</STRONG>
 199        below.
 200
 201
 202 </PRE><H3><a name="h3-qiflush_noqiflush">qiflush, noqiflush</a></H3><PRE>
 203        <STRONG>qiflush</STRONG> and <STRONG>noqiflush</STRONG> configure the terminal driver's treatment of  its
 204        input and output queues when it handles the interrupt, suspend, or quit
 205        characters  in  <EM>cbreak</EM>  and  "cooked"  modes;  on  POSIX  systems,  see
 206        <STRONG>termios(3)</STRONG>.  The default behavior is inherited from the terminal driver
 207        settings.  Calling <STRONG>qiflush</STRONG> configures the terminal to flush the  queues
 208        when  any  of  these  events  occurs,  giving  the impression of faster
 209        response to user input, but making the library's model  of  the  screen
 210        contents  incorrect.   Calling  <STRONG>noqiflush</STRONG>  prevents  such flushing, but
 211        might frustrate impatient users on slow connections if a <EM>curses</EM>  update
 212        of the screen is in progress when the event occurs; see <STRONG>typeahead</STRONG> below
 213        for a mitigation of this problem.  You may want to call <STRONG>noqiflush</STRONG> in  a
 214        signal  handler  if you want output to continue after the handler exits
 215        as though the interrupt had not occurred.
 216
 217
 218 </PRE><H3><a name="h3-raw_noraw">raw, noraw</a></H3><PRE>
 219        <STRONG>raw</STRONG> configures the terminal to read input in <EM>raw</EM> <EM>mode</EM>, which is similar
 220        to  cbreak  mode  (see  <STRONG>cbreak</STRONG> above) except that it furthermore passes
 221        through the terminal's configured interrupt, quit,  suspend,  and  flow
 222        control   characters  uninterpreted  to  the  application,  instead  of
 223        generating a signal or  acting  on  I/O  flow.   The  behavior  of  the
 224        terminal's   "Break"   key   (if   any)   depends  on  terminal  driver
 225        configuration parameters that <EM>curses</EM> does not  handle.   <STRONG>noraw</STRONG>  returns
 226        the terminal to normal ("cooked") mode.
 227
 228
 229 </PRE><H3><a name="h3-timeout_wtimeout">timeout, wtimeout</a></H3><PRE>
 230        <STRONG>wtimeout</STRONG>  configures  whether a <EM>curses</EM> input character reading function
 231        called on window <EM>win</EM> uses blocking or non-blocking reads.  If <EM>delay</EM>  is
 232        negative,  a blocking read is used, waiting indefinitely for input.  If
 233        <EM>delay</EM> is zero, a non-blocking read is used; an input character  reading
 234        function  returns <STRONG>ERR</STRONG> if no input is pending.  If <EM>delay</EM> is positive, an
 235        input character reading function blocks  for  <EM>delay</EM>  milliseconds,  and
 236        returns  <STRONG>ERR</STRONG>  if the delay elapses and there is still no input pending.
 237        <STRONG>timeout</STRONG> calls <STRONG>wtimeout</STRONG> on <STRONG>stdscr</STRONG>.
 238
 239
 240 </PRE><H3><a name="h3-typeahead">typeahead</a></H3><PRE>
 241        Normally, a <EM>curses</EM> library checks the terminal for input while updating
 242        the  screen.   If  any is found, the update is postponed until the next
 243        <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG> or <STRONG><A HREF="curs_refresh.3x.html">doupdate(3x)</A></STRONG> call, allowing faster response to user key
 244        strokes.   The  library  tests the file descriptor corresponding to the
 245        <EM>FILE</EM> stream pointer passed to <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> (or <EM>stdin</EM> if <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG>  was
 246        called),  for  pending  input.  <STRONG>typeahead</STRONG> instructs <EM>curses</EM> to test file
 247        descriptor <EM>fd</EM> instead.  An <EM>fd</EM> of <STRONG>-1</STRONG> disables the check.
 248
 249
 250 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 251        <STRONG>timeout</STRONG> and <STRONG>wtimeout</STRONG> return no value.
 252
 253        <STRONG>cbreak</STRONG>, <STRONG>nocbreak</STRONG>, <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>,  <STRONG>halfdelay</STRONG>,  <STRONG>intrflush</STRONG>,  <STRONG>keypad</STRONG>,  <STRONG>meta</STRONG>,
 254        <STRONG>nodelay</STRONG>,  <STRONG>notimeout</STRONG>,  <STRONG>nl</STRONG>,  <STRONG>nonl</STRONG>, <STRONG>raw</STRONG>, <STRONG>noraw</STRONG>, and <STRONG>typeahead</STRONG> return <STRONG>OK</STRONG> on
 255        success and <STRONG>ERR</STRONG> on failure.
 256
 257        In <EM>ncurses</EM>, the functions in the previous paragraph return <STRONG>ERR</STRONG> if
 258
 259        <STRONG>o</STRONG>   the terminal is not initialized or
 260
 261        <STRONG>o</STRONG>   <EM>win</EM> is <STRONG>NULL</STRONG> (except  for  <STRONG>intrflush</STRONG>  and  <STRONG>meta</STRONG>,  which  ignore  its
 262            value).
 263
 264        Further, <STRONG>halfdelay</STRONG> returns <STRONG>ERR</STRONG> if <EM>delay</EM> is outside the range 1..255.
 265
 266        See  section  "EXTENSIONS"  below  for  the return values of <STRONG>is_cbreak</STRONG>,
 267        <STRONG>is_echo</STRONG>, <STRONG>is_nl</STRONG>, and <STRONG>is_raw</STRONG>.
 268
 269
 270 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 271        <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>meta</STRONG>, <STRONG>nl</STRONG>, <STRONG>nonl</STRONG>, <STRONG>nodelay</STRONG>, <STRONG>notimeout</STRONG>,
 272        <STRONG>noqiflush</STRONG>, <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, and <STRONG>wtimeout</STRONG> may be implemented as macros.
 273
 274        <STRONG>noraw</STRONG>  and  <STRONG>nocbreak</STRONG> follow historical practice in that they attempt to
 275        restore normal ("cooked") mode from raw and cbreak modes, respectively.
 276        Mixing  <STRONG>raw</STRONG>/<STRONG>noraw</STRONG>  calls  with  <STRONG>cbreak</STRONG>/<STRONG>nocbreak</STRONG> calls leads to terminal
 277        driver control states that are hard to predict or understand; doing  so
 278        is not recommended.
 279
 280
 281 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 282        <EM>ncurses</EM>  provides  four  "is_" functions corresponding to <STRONG>cbreak</STRONG>, <STRONG>echo</STRONG>,
 283        <STRONG>nl</STRONG>, and <STRONG>raw</STRONG>, permitting their states to be queried by the application.
 284
 285                             <STRONG>Query</STRONG>       <STRONG>Set</STRONG>      <STRONG>Reset</STRONG>
 286                             ------------------------------
 287                             is_cbreak   cbreak   nocbreak
 288                             is_echo     echo     noecho
 289                             is_nl       nl       nonl
 290                             is_raw      raw      noraw
 291
 292        In each case, the function returns
 293
 294        <STRONG>1</STRONG>    if the option is set,
 295
 296        <STRONG>0</STRONG>    if the option is reset, or
 297
 298        <STRONG>-1</STRONG>   if the library is not initialized.
 299
 300
 301 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 302        Applications employing <EM>ncurses</EM> extensions should condition their use on
 303        the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro.
 304
 305        Except  as  noted in section "EXTENSIONS" above, X/Open Curses, Issue 4
 306        describes these functions.  It specifies no error conditions for them.
 307
 308        SVr4 <EM>curses</EM> describes a successful return value  only  as  "an  integer
 309        value other than <STRONG>ERR</STRONG>".
 310
 311        <EM>ncurses</EM>  follows  X/Open Curses and the historical practice of System V
 312        <EM>curses</EM>, clearing the terminal driver's "echo"  flag  when  initializing
 313        the  screen.  BSD <EM>curses</EM> did not, but its <EM>raw</EM> function turned it off as
 314        a side effect.  For best portability, call <STRONG>echo</STRONG>  or  <STRONG>noecho</STRONG>  explicitly
 315        just  after  initialization,  even  if  your  program remains in normal
 316        ("cooked") mode.
 317
 318        X/Open Curses is ambiguous regarding whether  <EM>raw</EM>  should  disable  the
 319        carriage  return and line feed translation feature controlled by <EM>nl</EM> and
 320        <EM>nonl</EM>.  BSD <EM>curses</EM> did turn off these translations; System V <EM>curses</EM>  did
 321        not.   <EM>ncurses</EM>  does so, on the assumption that a programmer requesting
 322        raw input wants a clean (ideally,  8-bit  clean)  connection  that  the
 323        operating system will not alter.
 324
 325        When <STRONG>keypad</STRONG> is first enabled, <EM>ncurses</EM> loads the key definitions for the
 326        current terminal description.  If  the  terminal  description  includes
 327        extended  string  capabilities,  for example, by using the <STRONG>-x</STRONG> option of
 328        <STRONG><A HREF="tic.1m.html">tic(1)</A></STRONG>, then <EM>ncurses</EM> also defines keys for the capabilities whose names
 329        begin  with  "k".  Corresponding key codes are generated and (depending
 330        on previous  loads  of  terminal  descriptions)  may  differ  from  one
 331        execution  of  a  program  to  the  next.   The generated key codes are
 332        recognized by <STRONG><A HREF="curs_util.3x.html">keyname(3x)</A></STRONG>, which then returns a name beginning with "k"
 333        denoting  the <EM>terminfo</EM> capability name rather than "K", used for <EM>curses</EM>
 334        key names.  On the other hand, an application can use <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> to
 335        bind  a  specific  key  to  a  string of the programmer's choice.  This
 336        feature  enables  an  application  to  check  for  its  presence   with
 337        <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG>, and reassign the key code to match its own needs.
 338
 339        Low-level applications can use <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG> to obtain the definition of
 340        any string capability.  <EM>curses</EM> applications  use  the  input  character
 341        reading function to obtain key codes from input and rely upon the order
 342        in which the string capabilities are loaded.  Multiple  key  capability
 343        strings  can  have  the  same  value,  but  the input character reading
 344        function can report only one key  code.   Most  <EM>curses</EM>  implementations
 345        (including  <EM>ncurses</EM>)  load  key definitions in the order they appear in
 346        the <STRONG>strfnames</STRONG> array of string capability names; see <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>.
 347        The  last  capability read using a particular definition determines the
 348        key code to be reported.  In  <EM>ncurses</EM>,  extended  capabilities  can  be
 349        interpreted  as key definitions.  These are loaded after the predefined
 350        keys, and if a capability's value is the same as  a  previously  loaded
 351        key definition, the later definition is the one used.
 352
 353
 354 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 355        4BSD <EM>curses</EM> (1980) introduced <EM>echo</EM>, <EM>noecho</EM>, <EM>nl</EM>, <EM>nonl</EM>, <EM>raw</EM>, and <EM>noraw</EM>.
 356
 357        SVr2 (1984) featured a new terminal driver, extending the <EM>curses</EM> API to
 358        support it with <EM>cbreak</EM>, <EM>nocbreak</EM>, <EM>intrflush</EM>, <EM>keypad</EM>, <EM>meta</EM>, <EM>nodelay</EM>, and
 359        <EM>typeahead</EM>.
 360
 361        SVr3  (1987)  added  <EM>halfdelay</EM>,  <EM>notimeout</EM>,  and <EM>wtimeout</EM>.  <EM>qiflush</EM> and
 362        <EM>noqiflush</EM> appeared in SVr3.1 (1987), at which point <EM>intrflush</EM> became  a
 363        wrapper  for  either  of these functions, depending on the value of its
 364        Boolean argument.  SVr3.1 also added <EM>timeout</EM>.
 365
 366        <EM>ncurses</EM> 6.5 (2024) introduced <EM>is</EM><STRONG>_</STRONG><EM>cbreak</EM>, <EM>is</EM><STRONG>_</STRONG><EM>echo</EM>, <EM>is</EM><STRONG>_</STRONG><EM>nl</EM>, and <EM>is</EM><STRONG>_</STRONG><EM>raw</EM>.
 367
 368        Formerly, <EM>ncurses</EM> used  <EM>nl</EM>  and  <EM>nonl</EM>  to  control  the  conversion  of
 369        newlines  to  carriage  return/line  feed  on  output as well as input.
 370        X/Open Curses documents the use of  these  functions  only  for  input.
 371        This  difference arose from converting the <EM>pcurses</EM> source (1986), which
 372        used <STRONG>ioctl(2)</STRONG> calls and the <EM>sgttyb</EM> structure,  to  <EM>termios</EM>  (the  POSIX
 373        terminal  API).   In  the former, both input and output were controlled
 374        via a single option "CRMOD", while the latter separates these features.
 375        Because  that  conversion  interferes with output optimization, <EM>ncurses</EM>
 376        6.2 (2020) amended <EM>nl</EM> and <EM>nonl</EM> to eliminate their effect on output.
 377
 378
 379 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 380        <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="curs_util.3x.html">curs_util(3x)</A></STRONG>,
 381        <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>, <STRONG>termios(3)</STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>.
 382
 383
 384
 385 ncurses 6.5                       2024-06-08                   <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
 386 </PRE>
 387 <div class="nav">
 388 <ul>
 389 <li><a href="#h2-NAME">NAME</a></li>
 390 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 391 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 392 <ul>
 393 <li><a href="#h3-cbreak_nocbreak">cbreak, nocbreak</a></li>
 394 <li><a href="#h3-echo_noecho">echo, noecho</a></li>
 395 <li><a href="#h3-halfdelay">halfdelay</a></li>
 396 <li><a href="#h3-intrflush">intrflush</a></li>
 397 <li><a href="#h3-keypad">keypad</a></li>
 398 <li><a href="#h3-meta">meta</a></li>
 399 <li><a href="#h3-nl_nonl">nl, nonl</a></li>
 400 <li><a href="#h3-nodelay">nodelay</a></li>
 401 <li><a href="#h3-notimeout">notimeout</a></li>
 402 <li><a href="#h3-qiflush_noqiflush">qiflush, noqiflush</a></li>
 403 <li><a href="#h3-raw_noraw">raw, noraw</a></li>
 404 <li><a href="#h3-timeout_wtimeout">timeout, wtimeout</a></li>
 405 <li><a href="#h3-typeahead">typeahead</a></li>
 406 </ul>
 407 </li>
 408 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 409 <li><a href="#h2-NOTES">NOTES</a></li>
 410 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 411 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 412 <li><a href="#h2-HISTORY">HISTORY</a></li>
 413 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 414 </ul>
 415 </div>
 416 </BODY>
 417 </HTML>