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.70 2024/06/01 22:28:41 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-01 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-01 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> window has its echo flag set.  Authors
 131        of 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 depends  on  the  configuration  of  the
 180        terminal driver; see <STRONG>termios(3)</STRONG>.  <STRONG>nl</STRONG> configures the terminal to perform
 181        this translation.  <STRONG>nonl</STRONG> disables it.
 182
 183
 184 </PRE><H3><a name="h3-nodelay">nodelay</a></H3><PRE>
 185        <STRONG>nodelay</STRONG> configures the input character  reading  function  to  be  non-
 186        blocking  for  window  <EM>win</EM>.  If no input is ready, the reading function
 187        returns <STRONG>ERR</STRONG>.  If disabled (<EM>bf</EM> is <STRONG>FALSE</STRONG>), the reading function does  not
 188        return until it has input.
 189
 190
 191 </PRE><H3><a name="h3-notimeout">notimeout</a></H3><PRE>
 192        When  the  input  character reading function reads an ESC character, it
 193        sets a timer while waiting  for  the  next  character.   <STRONG>notimeout(</STRONG><EM>win</EM><STRONG>,</STRONG>
 194        <STRONG>TRUE)</STRONG>   disables  this  timer.   The  purpose  of  the  timeout  is  to
 195        distinguish sequences produced by a function key from those typed by  a
 196        user.   To configure the timeout rather than disabling it, see <STRONG>wtimeout</STRONG>
 197        below.
 198
 199
 200 </PRE><H3><a name="h3-qiflush_noqiflush">qiflush, noqiflush</a></H3><PRE>
 201        <STRONG>qiflush</STRONG> and <STRONG>noqiflush</STRONG> configure the terminal driver's treatment of  its
 202        input and output queues when it handles the interrupt, suspend, or quit
 203        characters  in  <EM>cbreak</EM>  and  "cooked"  modes;  on  POSIX  systems,  see
 204        <STRONG>termios(3)</STRONG>.  The default behavior is inherited from the terminal driver
 205        settings.  Calling <STRONG>qiflush</STRONG> configures the terminal to flush the  queues
 206        when  any  of  these  events  occurs,  giving  the impression of faster
 207        response to user input, but making the library's model  of  the  screen
 208        contents  incorrect.   Calling  <STRONG>noqiflush</STRONG>  prevents  such flushing, but
 209        might frustrate impatient users on slow connections if a <EM>curses</EM>  update
 210        of the screen is in progress when the event occurs; see <STRONG>typeahead</STRONG> below
 211        for a mitigation of this problem.  You may want to call <STRONG>noqiflush</STRONG> in  a
 212        signal  handler  if you want output to continue after the handler exits
 213        as though the interrupt had not occurred.
 214
 215
 216 </PRE><H3><a name="h3-raw_noraw">raw, noraw</a></H3><PRE>
 217        <STRONG>raw</STRONG> configures the terminal to read input in <EM>raw</EM> <EM>mode</EM>, which is similar
 218        to  cbreak  mode  (see  <STRONG>cbreak</STRONG> above) except that it furthermore passes
 219        through the terminal's configured interrupt, quit,  suspend,  and  flow
 220        control   characters  uninterpreted  to  the  application,  instead  of
 221        generating a signal or  acting  on  I/O  flow.   The  behavior  of  the
 222        terminal's   "Break"   key   (if   any)   depends  on  terminal  driver
 223        configuration parameters that <EM>curses</EM> does not  handle.   <STRONG>noraw</STRONG>  returns
 224        the terminal to normal ("cooked") mode.
 225
 226
 227 </PRE><H3><a name="h3-timeout_wtimeout">timeout, wtimeout</a></H3><PRE>
 228        <STRONG>wtimeout</STRONG>  configures  whether a <EM>curses</EM> input character reading function
 229        called on window <EM>win</EM> uses blocking or non-blocking reads.  If <EM>delay</EM>  is
 230        negative,  a blocking read is used, waiting indefinitely for input.  If
 231        <EM>delay</EM> is zero, a non-blocking read is used; an input character  reading
 232        function  returns <STRONG>ERR</STRONG> if no input is pending.  If <EM>delay</EM> is positive, an
 233        input character reading function blocks  for  <EM>delay</EM>  milliseconds,  and
 234        returns  <STRONG>ERR</STRONG>  if the delay elapses and there is still no input pending.
 235        <STRONG>timeout</STRONG> calls <STRONG>wtimeout</STRONG> on <STRONG>stdscr</STRONG>.
 236
 237
 238 </PRE><H3><a name="h3-typeahead">typeahead</a></H3><PRE>
 239        Normally, a <EM>curses</EM> library checks the terminal for input while updating
 240        the  screen.   If  any is found, the update is postponed until the next
 241        <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
 242        strokes.   The  library  tests the file descriptor corresponding to the
 243        <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
 244        called),  for  pending  input.  <STRONG>typeahead</STRONG> instructs <EM>curses</EM> to test file
 245        descriptor <EM>fd</EM> instead.  An <EM>fd</EM> of <STRONG>-1</STRONG> disables the check.
 246
 247
 248 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 249        <STRONG>timeout</STRONG> and <STRONG>wtimeout</STRONG> return no value.
 250
 251        <STRONG>cbreak</STRONG>, <STRONG>nocbreak</STRONG>, <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>,  <STRONG>halfdelay</STRONG>,  <STRONG>intrflush</STRONG>,  <STRONG>keypad</STRONG>,  <STRONG>meta</STRONG>,
 252        <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
 253        success and <STRONG>ERR</STRONG> on failure.
 254
 255        In <EM>ncurses</EM>, the functions in the previous paragraph return <STRONG>ERR</STRONG> if
 256
 257        <STRONG>o</STRONG>   the terminal is not initialized or
 258
 259        <STRONG>o</STRONG>   <EM>win</EM> is <STRONG>NULL</STRONG> (except  for  <STRONG>intrflush</STRONG>  and  <STRONG>meta</STRONG>,  which  ignore  its
 260            value).
 261
 262        Further, <STRONG>halfdelay</STRONG> returns <STRONG>ERR</STRONG> if <EM>delay</EM> is outside the range 1..255.
 263
 264        See  section  "EXTENSIONS"  below  for  the return values of <STRONG>is_cbreak</STRONG>,
 265        <STRONG>is_echo</STRONG>, <STRONG>is_nl</STRONG>, and <STRONG>is_raw</STRONG>.
 266
 267
 268 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 269        <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>,
 270        <STRONG>noqiflush</STRONG>, <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, and <STRONG>wtimeout</STRONG> may be implemented as macros.
 271
 272        <STRONG>noraw</STRONG>  and  <STRONG>nocbreak</STRONG> follow historical practice in that they attempt to
 273        restore normal ("cooked") mode from raw and cbreak modes, respectively.
 274        Mixing  <STRONG>raw</STRONG>/<STRONG>noraw</STRONG>  calls  with  <STRONG>cbreak</STRONG>/<STRONG>nocbreak</STRONG> calls leads to terminal
 275        driver control states that are hard to predict or understand; doing  so
 276        is not recommended.
 277
 278
 279 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 280        <EM>ncurses</EM>  provides  four  "is_" functions corresponding to <STRONG>cbreak</STRONG>, <STRONG>echo</STRONG>,
 281        <STRONG>nl</STRONG>, and <STRONG>raw</STRONG>, permitting their states to be queried by the application.
 282
 283                             <STRONG>Query</STRONG>       <STRONG>Set</STRONG>      <STRONG>Reset</STRONG>
 284                             ------------------------------
 285                             is_cbreak   cbreak   nocbreak
 286                             is_echo     echo     noecho
 287                             is_nl       nl       nonl
 288                             is_raw      raw      noraw
 289
 290        In each case, the function returns
 291
 292        <STRONG>1</STRONG>    if the flag is set,
 293
 294        <STRONG>0</STRONG>    if the flag is reset, or
 295
 296        <STRONG>-1</STRONG>   if the library is not initialized.
 297
 298
 299 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 300        Applications employing <EM>ncurses</EM> extensions should condition their use on
 301        the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro.
 302
 303        Except  as  noted in section "EXTENSIONS" above, X/Open Curses, Issue 4
 304        describes these functions.  It specifies no error conditions for them.
 305
 306        SVr4 <EM>curses</EM> describes a successful return value  only  as  "an  integer
 307        value other than <STRONG>ERR</STRONG>".
 308
 309        <EM>ncurses</EM>  follows  X/Open Curses and the historical practice of System V
 310        <EM>curses</EM>, clearing the terminal driver's "echo"  flag  when  initializing
 311        the  screen.  BSD <EM>curses</EM> did not, but its <EM>raw</EM> function turned it off as
 312        a side effect.  For best portability, call <STRONG>echo</STRONG>  or  <STRONG>noecho</STRONG>  explicitly
 313        just  after  initialization,  even  if  your  program remains in normal
 314        ("cooked") mode.
 315
 316        X/Open Curses is ambiguous regarding whether  <EM>raw</EM>  should  disable  the
 317        carriage  return and line feed translation feature controlled by <EM>nl</EM> and
 318        <EM>nonl</EM>.  BSD <EM>curses</EM> did turn off these translations; System V <EM>curses</EM>  did
 319        not.   <EM>ncurses</EM>  does so, on the assumption that a programmer requesting
 320        raw input wants a clean (ideally,  8-bit  clean)  connection  that  the
 321        operating system will not alter.
 322
 323        When <STRONG>keypad</STRONG> is first enabled, <EM>ncurses</EM> loads the key definitions for the
 324        current terminal description.  If  the  terminal  description  includes
 325        extended  string  capabilities,  for example, by using the <STRONG>-x</STRONG> option of
 326        <STRONG><A HREF="tic.1m.html">tic(1)</A></STRONG>, then <EM>ncurses</EM> also defines keys for the capabilities whose names
 327        begin  with  "k".  Corresponding key codes are generated and (depending
 328        on previous  loads  of  terminal  descriptions)  may  differ  from  one
 329        execution  of  a  program  to  the  next.   The generated key codes are
 330        recognized by <STRONG><A HREF="curs_util.3x.html">keyname(3x)</A></STRONG>, which then returns a name beginning with "k"
 331        denoting  the <EM>terminfo</EM> capability name rather than "K", used for <EM>curses</EM>
 332        key names.  On the other hand, an application can use <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> to
 333        bind  a  specific  key  to  a  string of the programmer's choice.  This
 334        feature  enables  an  application  to  check  for  its  presence   with
 335        <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG>, and reassign the key code to match its own needs.
 336
 337        Low-level applications can use <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG> to obtain the definition of
 338        any string capability.  <EM>curses</EM> applications  use  the  input  character
 339        reading function to obtain key codes from input and rely upon the order
 340        in which the string capabilities are loaded.  Multiple  key  capability
 341        strings  can  have  the  same  value,  but  the input character reading
 342        function can report only one key  code.   Most  <EM>curses</EM>  implementations
 343        (including  <EM>ncurses</EM>)  load  key definitions in the order they appear in
 344        the <STRONG>strfnames</STRONG> array of string capability names; see <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>.
 345        The  last  capability read using a particular definition determines the
 346        key code to be reported.  In  <EM>ncurses</EM>,  extended  capabilities  can  be
 347        interpreted  as key definitions.  These are loaded after the predefined
 348        keys, and if a capability's value is the same as  a  previously  loaded
 349        key definition, the later definition is the one used.
 350
 351
 352 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 353        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>.
 354
 355        SVr2 (1984) featured a new terminal driver, extending the <EM>curses</EM> API to
 356        support it with <EM>cbreak</EM>, <EM>nocbreak</EM>, <EM>intrflush</EM>, <EM>keypad</EM>, <EM>meta</EM>, <EM>nodelay</EM>, and
 357        <EM>typeahead</EM>.
 358
 359        SVr3  (1987)  added  <EM>halfdelay</EM>,  <EM>notimeout</EM>,  and <EM>wtimeout</EM>.  <EM>qiflush</EM> and
 360        <EM>noqiflush</EM> appeared in SVr3.1 (1987), at which point <EM>intrflush</EM> became  a
 361        wrapper  for  either  of these functions, depending on the value of its
 362        Boolean argument.  SVr3.1 also added <EM>timeout</EM>.
 363
 364        <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>.
 365
 366        Formerly, <EM>ncurses</EM> used  <EM>nl</EM>  and  <EM>nonl</EM>  to  control  the  conversion  of
 367        newlines  to  carriage  return/line  feed  on  output as well as input.
 368        X/Open Curses documents the use of  these  functions  only  for  input.
 369        This  difference arose from converting the <EM>pcurses</EM> source (1986), which
 370        used <STRONG>ioctl(2)</STRONG> calls and the <EM>sgttyb</EM> structure,  to  <EM>termios</EM>  (the  POSIX
 371        terminal  API).   In  the former, both input and output were controlled
 372        via a single option "CRMOD", while the latter separates these features.
 373        Because  that  conversion  interferes with output optimization, <EM>ncurses</EM>
 374        6.2 (2020) amended <EM>nl</EM> and <EM>nonl</EM> to eliminate their effect on output.
 375
 376
 377 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 378        <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>,
 379        <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG>termios(3)</STRONG>
 380
 381
 382
 383 ncurses 6.5                       2024-06-01                   <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
 384 </PRE>
 385 <div class="nav">
 386 <ul>
 387 <li><a href="#h2-NAME">NAME</a></li>
 388 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 389 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 390 <ul>
 391 <li><a href="#h3-cbreak_nocbreak">cbreak, nocbreak</a></li>
 392 <li><a href="#h3-echo_noecho">echo, noecho</a></li>
 393 <li><a href="#h3-halfdelay">halfdelay</a></li>
 394 <li><a href="#h3-intrflush">intrflush</a></li>
 395 <li><a href="#h3-keypad">keypad</a></li>
 396 <li><a href="#h3-meta">meta</a></li>
 397 <li><a href="#h3-nl_nonl">nl, nonl</a></li>
 398 <li><a href="#h3-nodelay">nodelay</a></li>
 399 <li><a href="#h3-notimeout">notimeout</a></li>
 400 <li><a href="#h3-qiflush_noqiflush">qiflush, noqiflush</a></li>
 401 <li><a href="#h3-raw_noraw">raw, noraw</a></li>
 402 <li><a href="#h3-timeout_wtimeout">timeout, wtimeout</a></li>
 403 <li><a href="#h3-typeahead">typeahead</a></li>
 404 </ul>
 405 </li>
 406 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 407 <li><a href="#h2-NOTES">NOTES</a></li>
 408 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 409 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 410 <li><a href="#h2-HISTORY">HISTORY</a></li>
 411 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 412 </ul>
 413 </div>
 414 </BODY>
 415 </HTML>