Canonical mode is the default for every terminal. It is sometimes called cooked mode — the terminal driver “cooks” raw input before handing it to your program.

How it works:

• The terminal driver collects characters as the user types them, building up a line in its internal buffer.
• Line editing is enabled — the user can press Backspace to fix mistakes, Ctrl+U to erase the whole line, and Ctrl+W to erase the last word, all before pressing Enter.
• When the user presses Enter, a newline character is added, and the complete line is made available for the application to read.
• A read() call blocks until a complete line is available, then returns at most one line at a time.

Canonical mode is ideal for shell commands, text prompts, and any situation where the user is expected to type a whole line before anything happens. A basic shell like bash reads user commands in canonical mode.

Noncanonical mode turns off line buffering and line editing in the terminal driver. Characters are delivered to the application as soon as they are typed — without waiting for Enter.

When is noncanonical mode used?

• vi / vim — each keystroke (j, k, :, etc.) must be processed immediately without Enter.
• more / less — pressing Space or q acts immediately.
• Interactive menus — press ‘1’ to select option 1, no Enter needed.
• Games — movement keys must respond instantly.
• Serial port communication — in embedded systems, raw bytes from a microcontroller must be received without line-buffering interference.

In noncanonical mode, the application is responsible for all editing and interpretation. Programs that use noncanonical mode usually also disable echoing so that raw keystrokes are not printed on screen.

Noncanonical mode is also called raw mode, though strictly speaking “raw mode” often implies also disabling signal generation (no SIGINT from Ctrl+C).

In canonical mode (and by default in noncanonical mode), the terminal driver interprets certain key combinations as special characters:

Programs that switch to noncanonical mode typically disable signal generation (by clearing the ISIG flag in c_lflag) so that Ctrl+C is received as a plain byte (0x03) rather than generating SIGINT. This is exactly what vim does.

The terminal driver maintains two FIFO queues in the kernel:

Key points about these queues:

Echoing: When a user types a character, the terminal driver also places a copy in the output queue. That is why you see what you type — the kernel echoes it, not the application. Programs that read passwords typically turn echoing off.

POSIX defines two limits for terminal input queues:

• MAX_INPUT — maximum number of bytes that can be stored in the terminal’s input queue.
• MAX_CANON — maximum number of bytes in a single line of input in canonical mode.

You can query these using sysconf():

#include <stdio.h>
#include <unistd.h>

int main(void)
{
    long max_input = sysconf(_SC_MAX_INPUT);
    long max_canon = sysconf(_SC_MAX_CANON);

    printf("MAX_INPUT  = %ld\n", max_input);
    printf("MAX_CANON  = %ld\n", max_canon);

    return 0;
}

On Linux, both return 255, but the actual kernel limit is 4096 bytes. The POSIX values are just what the kernel reports via the API; the internal buffer is larger.

You can also check how many unread bytes are in the input queue right now using ioctl():

#include <stdio.h>
#include <sys/ioctl.h>
#include <unistd.h>

int main(void)
{
    int unread_bytes;

    /* FIONREAD = "how many bytes can be read without blocking?" */
    if (ioctl(STDIN_FILENO, FIONREAD, &unread_bytes) == -1) {
        perror("ioctl FIONREAD");
        return 1;
    }

    printf("Unread bytes in input queue: %d\n", unread_bytes);
    return 0;
}

FIONREAD is useful when you want to check if data is available without actually blocking on a read() call. Note: this is a Linux extension, not specified in POSIX/SUSv3.

The following example shows the difference clearly. It reads one character in both canonical and noncanonical mode.

/* demo_modes.c
 * Demonstrates the difference between canonical and noncanonical terminal input.
 * Compile: gcc demo_modes.c -o demo_modes
 * Run: ./demo_modes
 */
#include <stdio.h>
#include <unistd.h>
#include <termios.h>
#include <string.h>

/* Save original settings so we can restore them */
static struct termios original_termios;

/* Switch terminal to noncanonical (raw) mode */
void enter_raw_mode(void)
{
    struct termios raw;

    /* Get current attributes */
    tcgetattr(STDIN_FILENO, &original_termios);

    raw = original_termios;

    /* ICANON flag controls canonical vs noncanonical mode.
     * Clearing it enables noncanonical mode.
     * ECHO controls whether typed chars are echoed. Clearing hides them. */
    raw.c_lflag &= ~(ICANON | ECHO);

    /* MIN=1: block until at least 1 character is available */
    raw.c_cc[VMIN]  = 1;
    /* TIME=0: no timeout */
    raw.c_cc[VTIME] = 0;

    /* Apply immediately (TCSANOW) */
    tcsetattr(STDIN_FILENO, TCSANOW, &raw);
}

/* Restore original terminal settings */
void exit_raw_mode(void)
{
    tcsetattr(STDIN_FILENO, TCSANOW, &original_termios);
}

int main(void)
{
    char buf[128];
    int  n;

    /* --- Part 1: Canonical mode (default) --- */
    printf("=== CANONICAL MODE ===\n");
    printf("Type some text and press Enter: ");
    fflush(stdout);

    n = read(STDIN_FILENO, buf, sizeof(buf) - 1);
    buf[n] = '\0';
    printf("read() got %d bytes: [%s]\n\n", n, buf);

    /* --- Part 2: Noncanonical mode --- */
    printf("=== NONCANONICAL MODE ===\n");
    printf("Press any key (no Enter needed): ");
    fflush(stdout);

    enter_raw_mode();

    n = read(STDIN_FILENO, buf, 1);   /* reads ONE char immediately */

    exit_raw_mode();

    printf("\nread() got %d byte(s): ASCII code = %d (char = '%c')\n",
           n, (unsigned char)buf[0],
           (buf[0] >= 32 && buf[0] < 127) ? buf[0] : '?');

    printf("\nTerminal restored to canonical mode.\n");
    return 0;
}

Sample run:

=== CANONICAL MODE ===
Type some text and press Enter: Hello World
read() got 12 bytes: [Hello World
]

=== NONCANONICAL MODE ===
Press any key (no Enter needed): 
read() got 1 byte(s): ASCII code = 106 (char = 'j')

Terminal restored to canonical mode.

Notice that in canonical mode, the Enter key is included in the returned string (as \n). In noncanonical mode, pressing ‘j’ immediately returned — no Enter needed.

By default, the terminal driver echoes every character you type back to the output queue, so you can see what you are typing. This echo happens inside the kernel — your application does not do it.

The most common reason to disable echo is reading passwords. Here is a minimal example:

#include <stdio.h>
#include <string.h>
#include <termios.h>
#include <unistd.h>

int read_password(const char *prompt, char *buf, int maxlen)
{
    struct termios old, noecho;
    int n;

    /* Print the prompt */
    printf("%s", prompt);
    fflush(stdout);

    /* Save current terminal settings */
    tcgetattr(STDIN_FILENO, &old);
    noecho = old;

    /* Clear the ECHO flag to stop echoing */
    noecho.c_lflag &= ~ECHO;

    /* Apply new settings immediately */
    tcsetattr(STDIN_FILENO, TCSANOW, &noecho);

    /* Read one line (still in canonical mode, just without echo) */
    n = read(STDIN_FILENO, buf, maxlen - 1);
    if (n > 0) {
        buf[n] = '\0';
        /* Strip trailing newline */
        if (buf[n-1] == '\n') buf[n-1] = '\0';
    }

    /* Restore original settings */
    tcsetattr(STDIN_FILENO, TCSANOW, &old);

    /* Print newline since the Enter key was not echoed */
    printf("\n");
    return (n > 0) ? 0 : -1;
}

int main(void)
{
    char password[128];

    if (read_password("Password: ", password, sizeof(password)) == 0) {
        printf("You entered: [%s]\n", password);
    }
    return 0;
}

This is essentially what getpass() (a legacy POSIX function) does internally.