GNU C Library (libc) Programming Guide

Previous: Special Characters, Up: 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: int 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;
     