ncurses 6.2 - patch 20201003
[ncurses.git] / doc / html / man / curs_inopts.3x.html
index 7aea80376f0d722b7dbb0e76788674b25d02c15c..a468d00a14f8242796a167cd2fc158993baf4a78 100644 (file)
@@ -1,6 +1,7 @@
 <!-- 
   ****************************************************************************
-  * Copyright (c) 1998-2016,2017 Free Software Foundation, Inc.              *
+  * Copyright 2018-2019,2020 Thomas E. Dickey                                *
+  * Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
   *                                                                          *
   * Permission is hereby granted, free of charge, to any person obtaining a  *
   * copy of this software and associated documentation files (the            *
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: curs_inopts.3x,v 1.25 2017/02/18 16:39:44 tom Exp @
+  * @Id: curs_inopts.3x,v 1.31 2020/10/03 21:54:26 tom Exp @
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
 <HEAD>
 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
-<meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
+<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
 <TITLE>curs_inopts 3x</TITLE>
-<link rev=made href="mailto:bug-ncurses@gnu.org">
+<link rel="author" href="mailto:bug-ncurses@gnu.org">
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 </HEAD>
 <BODY>
@@ -46,9 +47,9 @@
 
 
 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
-       <STRONG>cbreak</STRONG>, <STRONG>nocbreak</STRONG>, <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>keypad</STRONG>, <STRONG>meta</STRONG>,
-       <STRONG>nodelay</STRONG>, <STRONG>notimeout</STRONG>, <STRONG>raw</STRONG>, <STRONG>noraw</STRONG>, <STRONG>noqiflush</STRONG>, <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, <STRONG>wtimeout</STRONG>,
-       <STRONG>typeahead</STRONG> - <STRONG>curses</STRONG> input options
+       <STRONG>cbreak</STRONG>, <STRONG>nocbreak</STRONG>, <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>keypad</STRONG>, <STRONG>meta</STRONG>, <STRONG>nl</STRONG>,
+       <STRONG>nonl</STRONG>, <STRONG>nodelay</STRONG>, <STRONG>notimeout</STRONG>, <STRONG>raw</STRONG>, <STRONG>noraw</STRONG>, <STRONG>qiflush</STRONG>, <STRONG>noqiflush</STRONG>, <STRONG>timeout</STRONG>,
+       <STRONG>wtimeout</STRONG>, <STRONG>typeahead</STRONG> - <STRONG>curses</STRONG> input options
 
 
 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
 
        <STRONG>int</STRONG> <STRONG>cbreak(void);</STRONG>
        <STRONG>int</STRONG> <STRONG>nocbreak(void);</STRONG>
+
        <STRONG>int</STRONG> <STRONG>echo(void);</STRONG>
        <STRONG>int</STRONG> <STRONG>noecho(void);</STRONG>
-       <STRONG>int</STRONG> <STRONG>halfdelay(int</STRONG> <STRONG>tenths);</STRONG>
+
        <STRONG>int</STRONG> <STRONG>intrflush(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
        <STRONG>int</STRONG> <STRONG>keypad(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
        <STRONG>int</STRONG> <STRONG>meta(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
        <STRONG>int</STRONG> <STRONG>nodelay(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
+       <STRONG>int</STRONG> <STRONG>notimeout(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
+
+       <STRONG>int</STRONG> <STRONG>nl(void);</STRONG>
+       <STRONG>int</STRONG> <STRONG>nonl(void);</STRONG>
+
        <STRONG>int</STRONG> <STRONG>raw(void);</STRONG>
        <STRONG>int</STRONG> <STRONG>noraw(void);</STRONG>
-       <STRONG>void</STRONG> <STRONG>noqiflush(void);</STRONG>
+
        <STRONG>void</STRONG> <STRONG>qiflush(void);</STRONG>
-       <STRONG>int</STRONG> <STRONG>notimeout(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
+       <STRONG>void</STRONG> <STRONG>noqiflush(void);</STRONG>
+
+       <STRONG>int</STRONG> <STRONG>halfdelay(int</STRONG> <STRONG>tenths);</STRONG>
        <STRONG>void</STRONG> <STRONG>timeout(int</STRONG> <STRONG>delay);</STRONG>
        <STRONG>void</STRONG> <STRONG>wtimeout(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>delay);</STRONG>
+
        <STRONG>int</STRONG> <STRONG>typeahead(int</STRONG> <STRONG>fd);</STRONG>
 
 
@@ -82,7 +92,7 @@
        behavior is needed.
 
 
-</PRE><H3><a name="h3-cbreak">cbreak</a></H3><PRE>
+</PRE><H3><a name="h3-cbreak_nocbreak">cbreak/nocbreak</a></H3><PRE>
        Normally, the tty driver buffers typed characters until  a  newline  or
        carriage  return  is typed.  The <STRONG>cbreak</STRONG> routine disables line buffering
        and erase/kill character-processing (interrupt and flow control charac-
        The <STRONG>halfdelay</STRONG> routine is used for half-delay mode, which is similar  to
        <STRONG>cbreak</STRONG> mode in that characters typed by the user are immediately avail-
        able to the program.  However, after blocking for <EM>tenths</EM> tenths of sec-
-       onds,  ERR  is returned if nothing has been typed.  The value of <EM>tenths</EM>
+       onds,  <STRONG>ERR</STRONG>  is returned if nothing has been typed.  The value of <EM>tenths</EM>
        must be a number between 1 and 255.  Use <STRONG>nocbreak</STRONG> to  leave  half-delay
        mode.
 
 
 </PRE><H3><a name="h3-meta">meta</a></H3><PRE>
        Initially,  whether the terminal returns 7 or 8 significant bits on in-
-       put depends on the control mode of the tty driver [see <STRONG>termio(7)</STRONG>].   To
+       put depends on the control mode of the tty driver [see <STRONG>termios(3)</STRONG>].  To
        force  8  bits  to be returned, invoke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>TRUE</STRONG>); this is equiva-
        lent, under POSIX, to setting the CS8 flag on the terminal.  To force 7
        bits to be returned, invoke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>FALSE</STRONG>); this is equivalent, under
        <STRONG>FALSE</STRONG>) is called.
 
 
-</PRE><H3><a name="h3-nodelay">nodelay</a></H3><PRE>
+</PRE><H3><a name="h3-nl_nonl">nl/nonl</a></H3><PRE>
+       The <STRONG>nl</STRONG> and <STRONG>nonl</STRONG> routines control whether the underlying display  device
+       translates the return key into newline on input.
+
+
+</PRE><H3><a name="h3-nodelay_notimeout">nodelay/notimeout</a></H3><PRE>
        The <STRONG>nodelay</STRONG> option causes <STRONG>getch</STRONG> to be a non-blocking call.  If no input
-       is  ready,  <STRONG>getch</STRONG>  returns <STRONG>ERR</STRONG>.  If disabled (<EM>bf</EM> is <STRONG>FALSE</STRONG>), <STRONG>getch</STRONG> waits
+       is ready, <STRONG>getch</STRONG> returns <STRONG>ERR</STRONG>.  If disabled (<EM>bf</EM> is  <STRONG>FALSE</STRONG>),  <STRONG>getch</STRONG>  waits
        until a key is pressed.
 
-       While interpreting an input escape sequence, <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>  sets  a  timer
-       while  waiting  for  the  next  character.   If <STRONG>notimeout(</STRONG><EM>win</EM>, <STRONG>TRUE</STRONG>) is
-       called, then <STRONG>wgetch</STRONG> does not set a timer.  The purpose of  the  timeout
-       is  to differentiate between sequences received from a function key and
+       While  interpreting  an  input escape sequence, <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> sets a timer
+       while waiting for the  next  character.   If  <STRONG>notimeout(</STRONG><EM>win</EM>,  <STRONG>TRUE</STRONG>)  is
+       called,  then  <STRONG>wgetch</STRONG> does not set a timer.  The purpose of the timeout
+       is to differentiate between sequences received from a function key  and
        those typed by a user.
 
 
 </PRE><H3><a name="h3-raw_noraw">raw/noraw</a></H3><PRE>
-       The <STRONG>raw</STRONG> and <STRONG>noraw</STRONG> routines place the terminal into or out of raw  mode.
-       Raw  mode is similar to <STRONG>cbreak</STRONG> mode, in that characters typed are imme-
-       diately passed through to the user program.  The differences  are  that
-       in  raw mode, the interrupt, quit, suspend, and flow control characters
-       are all passed through uninterpreted, instead of generating  a  signal.
-       The  behavior  of the BREAK key depends on other bits in the tty driver
+       The  <STRONG>raw</STRONG> and <STRONG>noraw</STRONG> routines place the terminal into or out of raw mode.
+       Raw mode is similar to <STRONG>cbreak</STRONG> mode, in that characters typed are  imme-
+       diately  passed  through to the user program.  The differences are that
+       in raw mode, the interrupt, quit, suspend, and flow control  characters
+       are  all  passed through uninterpreted, instead of generating a signal.
+       The behavior of the BREAK key depends on other bits in the  tty  driver
        that are not set by <STRONG>curses</STRONG>.
 
 
-</PRE><H3><a name="h3-noqiflush">noqiflush</a></H3><PRE>
-       When the <STRONG>noqiflush</STRONG> routine is used, normal flush of  input  and  output
-       queues  associated  with the <STRONG>INTR</STRONG>, <STRONG>QUIT</STRONG> and <STRONG>SUSP</STRONG> characters will not be
-       done [see <STRONG>termio(7)</STRONG>].  When <STRONG>qiflush</STRONG>  is  called,  the  queues  will  be
-       flushed  when  these control characters are read.  You may want to call
-       <STRONG>noqiflush</STRONG> in a signal handler if you want output to continue as  though
+</PRE><H3><a name="h3-qiflush_noqiflush">qiflush/noqiflush</a></H3><PRE>
+       When  the  <STRONG>noqiflush</STRONG>  routine is used, normal flush of input and output
+       queues associated with the <STRONG>INTR</STRONG>, <STRONG>QUIT</STRONG> and <STRONG>SUSP</STRONG> characters will  not  be
+       done  [see  <STRONG>termios(3)</STRONG>].   When  <STRONG>qiflush</STRONG>  is called, the queues will be
+       flushed when these control characters are read.  You may want  to  call
+       <STRONG>noqiflush</STRONG>  in a signal handler if you want output to continue as though
        the interrupt had not occurred, after the handler exits.
 
 
 </PRE><H3><a name="h3-timeout_wtimeout">timeout/wtimeout</a></H3><PRE>
        The <STRONG>timeout</STRONG> and <STRONG>wtimeout</STRONG> routines set blocking or non-blocking read for
-       a given window.  If <EM>delay</EM> is negative, blocking  read  is  used  (i.e.,
-       waits  indefinitely  for  input).   If <EM>delay</EM> is zero, then non-blocking
+       a  given  window.   If  <EM>delay</EM> is negative, blocking read is used (i.e.,
+       waits indefinitely for input).  If <EM>delay</EM>  is  zero,  then  non-blocking
        read is used (i.e., read returns <STRONG>ERR</STRONG> if no input is waiting).  If <EM>delay</EM>
-       is  positive,  then read blocks for <EM>delay</EM> milliseconds, and returns <STRONG>ERR</STRONG>
-       if there is still no input.  Hence, these  routines  provide  the  same
-       functionality  as <STRONG>nodelay</STRONG>, plus the additional capability of being able
+       is positive, then read blocks for <EM>delay</EM> milliseconds, and  returns  <STRONG>ERR</STRONG>
+       if  there  is  still  no input.  Hence, these routines provide the same
+       functionality as <STRONG>nodelay</STRONG>, plus the additional capability of being  able
        to block for only <EM>delay</EM> milliseconds (where <EM>delay</EM> is positive).
 
 
 </PRE><H3><a name="h3-typeahead">typeahead</a></H3><PRE>
        The <STRONG>curses</STRONG> library does "line-breakout optimization" by looking for ty-
        peahead periodically while updating the screen.  If input is found, and
-       it is coming from a tty, the current  update  is  postponed  until  <STRONG>re-</STRONG>
-       <STRONG><A HREF="refresh.3x.html">fresh(3x)</A></STRONG>  or <STRONG>doupdate</STRONG> is called again.  This allows faster response to
-       commands typed in advance.  Normally, the input FILE pointer passed  to
+       it  is  coming  from  a  tty, the current update is postponed until <STRONG>re-</STRONG>
+       <STRONG><A HREF="refresh.3x.html">fresh(3x)</A></STRONG> or <STRONG>doupdate</STRONG> is called again.  This allows faster response  to
+       commands  typed in advance.  Normally, the input FILE pointer passed to
        <STRONG>newterm</STRONG>, or <STRONG>stdin</STRONG> in the case that <STRONG>initscr</STRONG> was used, will be used to do
        this typeahead checking.  The <STRONG>typeahead</STRONG> routine specifies that the file
-       descriptor  <EM>fd</EM>  is to be used to check for typeahead instead.  If <EM>fd</EM> is
+       descriptor <EM>fd</EM> is to be used to check for typeahead instead.  If  <EM>fd</EM>  is
        -1, then no typeahead checking is done.
 
 
 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
-       All routines that return an integer return  <STRONG>ERR</STRONG>  upon  failure  and  OK
+       All  routines  that  return  an  integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG>
        (SVr4 specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
-       completion, unless otherwise noted in the  preceding  routine  descrip-
+       completion,  unless  otherwise  noted in the preceding routine descrip-
        tions.
 
-       X/Open  does  not define any error conditions.  In this implementation,
-       functions with a window parameter will return an error if it  is  null.
+       X/Open does not define any error conditions.  In  this  implementation,
+       functions  with  a window parameter will return an error if it is null.
        Any function will also return an error if the terminal was not initial-
        ized.  Also,
 
               <STRONG>halfdelay</STRONG>
-                   returns an error if its  parameter  is  outside  the  range
+                   returns  an  error  if  its  parameter is outside the range
                    1..255.
 
 
        These functions are described in the XSI Curses standard, Issue 4.
 
        The ncurses library obeys the XPG4 standard and the historical practice
-       of the AT&amp;T curses implementations, in that the  echo  bit  is  cleared
-       when  curses  initializes the terminal state.  BSD curses differed from
-       this slightly; it left the echo bit on at initialization, but  the  BSD
-       <STRONG>raw</STRONG>  call  turned  it  off as a side-effect.  For best portability, set
-       echo or noecho explicitly just after initialization, even if your  pro-
+       of  the  AT&amp;T  curses  implementations, in that the echo bit is cleared
+       when curses initializes the terminal state.  BSD curses  differed  from
+       this  slightly;  it left the echo bit on at initialization, but the BSD
+       <STRONG>raw</STRONG> call turned it off as a side-effect.   For  best  portability,  set
+       <STRONG>echo</STRONG>  or <STRONG>noecho</STRONG> explicitly just after initialization, even if your pro-
        gram remains in cooked mode.
 
+       The XSI Curses standard is ambiguous on the  question  of  whether  <STRONG>raw</STRONG>
+       should  disable  the  CRLF translations controlled by <STRONG>nl</STRONG> and <STRONG>nonl</STRONG>.  BSD
+       curses did turn off these translations; AT&amp;T curses (at least  as  late
+       as  SVr1)  did not.  We chose to do so, on the theory that a programmer
+       requesting raw input wants a clean  (ideally  8-bit  clean)  connection
+       that the operating system will not alter.
+
        When <STRONG>keypad</STRONG> is first enabled, ncurses loads the key-definitions for the
        current terminal description.  If the terminal description includes ex-
        tended string capabilities, e.g., from using the <STRONG>-x</STRONG> option of <STRONG>tic</STRONG>, then
 
 
 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
-       Note that <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>meta</STRONG>, <STRONG>nodelay</STRONG>, <STRONG>notimeout</STRONG>,
-       <STRONG>noqiflush</STRONG>, <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, and <STRONG>wtimeout</STRONG> may be macros.
+       Note that <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>, <STRONG>noqiflush</STRONG>, <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, and <STRONG>wtimeout</STRONG> may be macros.
 
        The  <STRONG>noraw</STRONG>  and  <STRONG>nocbreak</STRONG> calls follow historical practice in that they
        attempt to restore to normal ("cooked") mode from raw and cbreak  modes
 
 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
        <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>,  <STRONG>de-</STRONG>
-       <STRONG><A HREF="define_key.3x.html">fine_key(3x)</A></STRONG>, <STRONG>termio(7)</STRONG>
+       <STRONG><A HREF="define_key.3x.html">fine_key(3x)</A></STRONG>, <STRONG>termios(3)</STRONG>
 
 
 
 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 <ul>
-<li><a href="#h3-cbreak">cbreak</a></li>
+<li><a href="#h3-cbreak_nocbreak">cbreak/nocbreak</a></li>
 <li><a href="#h3-echo_noecho">echo/noecho</a></li>
 <li><a href="#h3-halfdelay">halfdelay</a></li>
 <li><a href="#h3-intrflush">intrflush</a></li>
 <li><a href="#h3-keypad">keypad</a></li>
 <li><a href="#h3-meta">meta</a></li>
-<li><a href="#h3-nodelay">nodelay</a></li>
+<li><a href="#h3-nl_nonl">nl/nonl</a></li>
+<li><a href="#h3-nodelay_notimeout">nodelay/notimeout</a></li>
 <li><a href="#h3-raw_noraw">raw/noraw</a></li>
-<li><a href="#h3-noqiflush">noqiflush</a></li>
+<li><a href="#h3-qiflush_noqiflush">qiflush/noqiflush</a></li>
 <li><a href="#h3-timeout_wtimeout">timeout/wtimeout</a></li>
 <li><a href="#h3-typeahead">typeahead</a></li>
 </ul>