Section 18.11. Noncanonical Mode

18.11. Noncanonical Mode

Noncanonical mode is specified by turning off the ICANON flag in the c_lflag field of the termios structure. In noncanonical mode, the input data is not assembled into lines. The following special characters (Section 18.3) are not processed: ERASE, KILL, EOF, NL, EOL, EOL2, CR, REPRINT, STATUS, and WERASE.

As we said, canonical mode is easy: the system returns up to one line at a time. But with noncanonical mode, how does the system know when to return data to us? If it returned one byte at a time, overhead would be excessive. (Recall Figure 3.5, which showed the overhead in reading one byte at a time. Each time we doubled the amount of data returned, we halved the system call overhead.) The system can't always return multiple bytes at a time, since sometimes we don't know how much data to read until we start reading it.

The solution is to tell the system to return when either a specified amount of data has been read or after a given amount of time has passed. This technique uses two variables in the c_cc array in the termios structure: MIN and TIME. These two elements of the array are indexed by the names VMIN and VTIME.

MIN specifies the minimum number of bytes before a read returns. TIME specifies the number of tenths of a second to wait for data to arrive. There are four cases.

Case A: MIN > 0, TIME > 0

TIME specifies an interbyte timer that is started only when the first byte is received. If MIN bytes are received before the timer expires, read returns MIN bytes. If the timer expires before MIN bytes are received, read returns the bytes received. (At least one byte is returned if the timer expires, because the timer is not started until the first byte is received.) In this case, the caller blocks until the first byte is received. If data is already available when read is called, it is as if the data had been received immediately after the read.

Case B: MIN > 0, TIME == 0

The read does not return until MIN bytes have been received. This can cause a read to block indefinitely.

Case C: MIN == 0, TIME > 0

TIME specifies a read timer that is started when read is called. (Compare this to case A, in which a nonzero TIME represented an interbyte timer that was not started until the first byte was received.) The read returns when a single byte is received or when the timer expires. If the timer expires, read returns 0.

Case D: MIN == 0, TIME == 0

If some data is available, read returns up to the number of bytes requested. If no data is available, read returns 0 immediately.

Realize in all these cases that MIN is only a minimum. If the program requests more than MIN bytes of data, it's possible to receive up to the requested amount. This also applies to cases C and D, in which MIN is 0.

Figure 18.19 summarizes the four cases for noncanonical input. In this figure, nbytes is the third argument to read (the maximum number of bytes to return).

Figure 18.19. Four cases for noncanonical input

Be aware that POSIX.1 allows the subscripts VMIN and VTIME to have the same values as VEOF and VEOL, respectively. Indeed, Solaris does this for backward compatibility with older versions of System V. This creates a portability problem, however. In going from noncanonical to canonical mode, we must now restore VEOF and VEOL also. If VMIN equals VEOF and we don't restore their values, when we set VMIN to its typical value of 1, the end-of-file character becomes Control-A. The easiest way around this problem is to save the entire termios structure when going into noncanonical mode and restore it when going back to canonical mode.

Example

The program in Figure 18.20 defines the tty_cbreak and tty_raw functions that set the terminal in cbreak mode and raw mode. (The terms cbreak and raw come from the Version 7 terminal driver.) We can reset the terminal to its original state (the state before either of these functions was called) by calling the function tty_reset.

If we've called tty_cbreak, we need to call tty_reset before calling tty_raw. The same goes for calling tty_cbreak after calling tty_raw. This improves the chances that the terminal will be left in a usable state if we encounter any errors.

Two additional functions are also provided: tty_atexit can be established as an exit handler to ensure that the terminal mode is reset by exit, and tty_termios returns a pointer to the original canonical mode termios structure.

Our definition of cbreak mode is the following:

• Noncanonical mode. As we mentioned at the beginning of this section, this mode turns off some input character processing. It does not turn off signal handling, so the user can always type one of the terminal-generated signals. Be aware that the caller should catch these signals, or there's a chance that the signal will terminate the program, and the terminal will be left in cbreak mode.

  As a general rule, whenever we write a program that changes the terminal mode, we should catch most signals. This allows us to reset the terminal mode before terminating.

• Echo off.

• One byte at a time input. To do this, we set MIN to 1 and TIME to 0. This is case B from Figure 18.19. A read won't return until at least one byte is available.

We define raw mode as follows:

• Noncanonical mode. We also turn off processing of the signal-generating characters (ISIG) and the extended input character processing (IEXTEN). Additionally, we disable a BREAK character from generating a signal, by turning off BRKINT.

• Echo off.

• We disable the CR-to-NL mapping on input (ICRNL), input parity detection (INPCK), the stripping of the eighth bit on input (ISTRIP), and output flow control (IXON).

• Eight-bit characters (CS8), and parity checking is disabled (PARENB).

• All output processing is disabled (OPOST).

• One byte at a time input (MIN = 1, TIME = 0).

The program in Figure 18.21 tests raw and cbreak modes.

Running the program in Figure 18.21, we can see what happens with these two terminal modes:

 $ ./a.out Enter raw mode characters, terminate with DELETE                                                  4                                                    33                                                      133                                                         61                                                           70                                                             176                           type DELETE Enter cbreak mode characters, terminate with SIGINT 1                         type Control-A 10                        type backspace signal caught             type interrupt key 

In raw mode, the characters entered were Control-D (04) and the special function key F7. On the terminal being used, this function key generated five characters: ESC (033), [ (0133), 1 (061), 8 (070), and ^~ (0176). Note that with the output processing turned off in raw mode (~OPOST), we do not get a carriage return output after each character. Also note that special-character processing is disabled in cbreak mode (so, for example, Control-D, the end-of-file character, and backspace aren't handled specially), whereas the terminal-generated signals are still processed.

Figure 18.20. Set terminal mode to cbreak or raw

 #include "apue.h" #include <termios.h> #include <errno.h> static struct termios       save_termios; static int                  ttysavefd = -1; static enum { RESET, RAW, CBREAK } ttystate = RESET; int tty_cbreak(int fd) /* put terminal into a cbreak mode */ {     int              err;     struct termios   buf;     if (ttystate != RESET) {         errno = EINVAL;         return(-1);     }     if (tcgetattr(fd, &buf) < 0)         return(-1);     save_termios = buf; /* structure copy */     /*      * Echo off, canonical mode off.      */     buf.c_lflag &= ~(ECHO | ICANON);     /*      * Case B: 1 byte at a time, no timer.      */     buf.c_cc[VMIN] = 1;     buf.c_cc[VTIME] = 0;     if (tcsetattr(fd, TCSAFLUSH, &buf) < 0)         return(-1);     /*      * Verify that the changes stuck. tcsetattr can return 0 on      * partial success.      */     if (tcgetattr(fd, &buf) < 0) {         err = errno;         tcsetattr(fd, TCSAFLUSH, &save_termios);         errno = err;         return(-1);     }     if ((buf.c_lflag & (ECHO | ICANON)) || buf.c_cc[VMIN] != 1 ||       buf.c_cc[VTIME] != 0) {         /*          * Only some of the changes were made. Restore the          * original settings.          */         tcsetattr(fd, TCSAFLUSH, &save_termios);         errno = EINVAL;         return(-1);     }     ttystate = CBREAK;     ttysavefd = fd;     return(0); } int tty_raw(int fd)     /* put terminal into a raw mode */ {     int             err;     struct termios  buf;     if (ttystate != RESET) {         errno = EINVAL;         return(-1);     }     if (tcgetattr(fd, &buf) < 0)         return(-1);     save_termios = buf; /* structure copy */     /*      * Echo off, canonical mode off, extended input      * processing off, signal chars off.      */     buf.c_lflag &= ~(ECHO | ICANON | IEXTEN | ISIG);     /*      * No SIGINT on BREAK, CR-to-NL off, input parity      * check off, don't strip 8th bit on input, output      * flow control off.      */     buf.c_iflag &= ~(BRKINT | ICRNL | INPCK | ISTRIP | IXON);     /*      * Clear size bits, parity checking off.      */     buf.c_cflag &= ~(CSIZE | PARENB);     /*      * Set 8 bits/char.      */     buf.c_cflag |= CS8;     /*      * Output processing off.      */     buf.c_oflag &= ~(OPOST);     /*      * Case B: 1 byte at a time, no timer.      */     buf.c_cc[VMIN] = 1;     buf.c_cc[VTIME] = 0;     if (tcsetattr(fd, TCSAFLUSH, &buf) < 0)         return(-1);     /*      * Verify that the changes stuck. tcsetattr can return 0 on      * partial success.      */     if (tcgetattr(fd, &buf) < 0) {         err = errno;         tcsetattr(fd, TCSAFLUSH, &save_termios);         errno = err;         return(-1);     }     if ((buf.c_lflag & (ECHO | ICANON | IEXTEN | ISIG)) ||       (buf.c_iflag & (BRKINT | ICRNL | INPCK | ISTRIP | IXON)) ||       (buf.c_cflag & (CSIZE | PARENB | CS8)) != CS8 ||       (buf.c_oflag & OPOST) || buf.c_cc[VMIN] != 1 ||       buf.c_cc[VTIME] != 0) {         /*          * Only some of the changes were made. Restore the          * original settings.          */         tcsetattr(fd, TCSAFLUSH, &save_termios);         errno = EINVAL;         return(-1);     }     ttystate = RAW;     ttysavefd = fd;     return(0); } int tty_reset(int fd)      /* restore terminal's mode */ {     if (ttystate == RESET)         return(0);     if (tcsetattr(fd, TCSAFLUSH, &save_termios) < 0)         return(-1);     ttystate = RESET;     return(0); } void tty_atexit(void)        /* can be set up by atexit(tty_atexit) */ {     if (ttysavefd >= 0)         tty_reset(ttysavefd); } struct termios * tty_termios(void)       /* let caller see original tty state */ {     return(&save_termios); }

Figure 18.21. Test raw and cbreak terminal modes

 #include "apue.h" static void sig_catch(int signo) {     printf("signal caught\n");     tty_reset(STDIN_FILENO);     exit(0); } int main(void) {     int    i;     char   c;     if (signal(SIGINT, sig_catch) == SIG_ERR)   /* catch signals */         err_sys("signal(SIGINT) error");     if (signal(SIGQUIT, sig_catch) == SIG_ERR)         err_sys("signal(SIGQUIT) error");     if (signal(SIGTERM, sig_catch) == SIG_ERR)         err_sys("signal(SIGTERM) error");     if (tty_raw(STDIN_FILENO) < 0)         err_sys("tty_raw error");     printf("Enter raw mode characters, terminate with DELETE\n");     while ((i = read(STDIN_FILENO, &c, 1)) == 1) {         if ((c &= 255) == 0177)     /* 0177 = ASCII DELETE */             break;         printf("%o\n", c);     }     if (tty_reset(STDIN_FILENO) < 0)         err_sys("tty_reset error");     if (i <= 0)         err_sys("read error");     if (tty_cbreak(STDIN_FILENO) < 0)         err_sys("tty_cbreak error");     printf("\nEnter cbreak mode characters, terminate with SIGINT\n");     while ((i = read(STDIN_FILENO, &c, 1)) == 1) {         c &= 255;         printf("%o\n", c);     }     if (tty_reset(STDIN_FILENO) < 0)         err_sys("tty_reset error");     if (i <= 0)         err_sys("read error");     exit(0); }