(libc.info.gz) Noncanonical Input

Info Catalog

(libc.info.gz) Special Characters

(libc.info.gz) Terminal Modes

 
 17.4.10 Noncanonical Input
 --------------------------
 
 In noncanonical input mode, the special editing characters such as
 ERASE and KILL are ignored.  The system facilities for the user to edit
 input are disabled in noncanonical mode, so that all input characters
 (unless they are special for signal or flow-control purposes) are passed
 to the application program exactly as typed.  It is up to the
 application program to give the user ways to edit the input, if
 appropriate.
 
    Noncanonical mode offers special parameters called MIN and TIME for
 controlling whether and how long to wait for input to be available.  You
 can even use them to avoid ever waiting--to return immediately with
 whatever input is available, or with no input.
 
    The MIN and TIME are stored in elements of the `c_cc' array, which
 is a member of the `struct termios' structure.  Each element of this
 array has a particular role, and each element has a symbolic constant
 that stands for the index of that element.  `VMIN' and `VMAX' are the
 names for the indices in the array of the MIN and TIME slots.
 
  -- Macro: int VMIN
      This is the subscript for the MIN slot in the `c_cc' array.  Thus,
      `TERMIOS.c_cc[VMIN]' is the value itself.
 
      The MIN slot is only meaningful in noncanonical input mode; it
      specifies the minimum number of bytes that must be available in the
      input queue in order for `read' to return.
 
  -- Macro: int VTIME
      This is the subscript for the TIME slot in the `c_cc' array.  Thus,
      `TERMIOS.c_cc[VTIME]' is the value itself.
 
      The TIME slot is only meaningful in noncanonical input mode; it
      specifies how long to wait for input before returning, in units of
      0.1 seconds.
 
    The MIN and TIME values interact to determine the criterion for when
 `read' should return; their precise meanings depend on which of them
 are nonzero.  There are four possible cases:
 
    * Both TIME and MIN are nonzero.
 
      In this case, TIME specifies how long to wait after each input
      character to see if more input arrives.  After the first character
      received, `read' keeps waiting until either MIN bytes have arrived
      in all, or TIME elapses with no further input.
 
      `read' always blocks until the first character arrives, even if
      TIME elapses first.  `read' can return more than MIN characters if
      more than MIN happen to be in the queue.
 
    * Both MIN and TIME are zero.
 
      In this case, `read' always returns immediately with as many
      characters as are available in the queue, up to the number
      requested.  If no input is immediately available, `read' returns a
      value of zero.
 
    * MIN is zero but TIME has a nonzero value.
 
      In this case, `read' waits for time TIME for input to become
      available; the availability of a single byte is enough to satisfy
      the read request and cause `read' to return.  When it returns, it
      returns as many characters as are available, up to the number
      requested.  If no input is available before the timer expires,
      `read' returns a value of zero.
 
    * TIME is zero but MIN has a nonzero value.
 
      In this case, `read' waits until at least MIN bytes are available
      in the queue.  At that time, `read' returns as many characters as
      are available, up to the number requested.  `read' can return more
      than MIN characters if more than MIN happen to be in the queue.
 
    What happens if MIN is 50 and you ask to read just 10 bytes?
 Normally, `read' waits until there are 50 bytes in the buffer (or, more
 generally, the wait condition described above is satisfied), and then
 reads 10 of them, leaving the other 40 buffered in the operating system
 for a subsequent call to `read'.
 
    *Portability note:* On some systems, the MIN and TIME slots are
 actually the same as the EOF and EOL slots.  This causes no serious
 problem because the MIN and TIME slots are used only in noncanonical
 input and the EOF and EOL slots are used only in canonical input, but it
 isn't very clean.  The GNU library allocates separate slots for these
 uses.
 
  -- Function: void cfmakeraw (struct termios *TERMIOS-P)
      This function provides an easy way to set up `*TERMIOS-P' for what
      has traditionally been called "raw mode" in BSD.  This uses
      noncanonical input, and turns off most processing to give an
      unmodified channel to the terminal.
 
      It does exactly this:
             TERMIOS-P->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP
                                           |INLCR|IGNCR|ICRNL|IXON);
             TERMIOS-P->c_oflag &= ~OPOST;
             TERMIOS-P->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);
             TERMIOS-P->c_cflag &= ~(CSIZE|PARENB);
             TERMIOS-P->c_cflag |= CS8;
 

Info Catalog

(libc.info.gz) Special Characters

(libc.info.gz) Terminal Modes