tcgetattr() reads the current settings of a terminal into a struct termios variable. You give it a file descriptor pointing to the terminal (like STDIN_FILENO) and it fills in the structure.

Function signature:

#include <termios.h>

int tcgetattr(int fd, struct termios *termios_p);
/* Returns 0 on success, -1 on error */

fd — file descriptor of the terminal (e.g., STDIN_FILENO, STDOUT_FILENO, or an open terminal file).
termios_p — pointer to a struct termios that will be filled with the current settings.

tcsetattr() writes new settings back to the terminal driver. It has an extra argument — when — that controls when the change takes effect.

Function signature:

#include <termios.h>

int tcsetattr(int fd, int optional_actions, const struct termios *termios_p);
/* Returns 0 on success, -1 on error */

The optional_actions argument:

You should never build a termios structure from scratch and pass it to tcsetattr(). The reason: the structure has many fields and flags. If you build it from zero, you will accidentally reset things you didn’t mean to change.

The correct pattern is always:

1. Read current attributes into a local copy using tcgetattr()
2. Modify only the specific fields you want to change
3. Write the modified copy back using tcsetattr()

This guarantees a fully initialized structure is always passed to tcsetattr().

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

void errExit(const char *msg) {
    perror(msg);
    exit(EXIT_FAILURE);
}

int main(void) {
    struct termios tp;

    /* Step 1: Read current terminal attributes */
    if (tcgetattr(STDIN_FILENO, &tp) == -1)
        errExit("tcgetattr");

    /* Step 2: Modify — turn off ECHO flag */
    tp.c_lflag &= ~ECHO;

    /* Step 3: Write modified attributes back.
       TCSAFLUSH: wait for output to drain AND discard pending input.
       This is ideal when reading passwords. */
    if (tcsetattr(STDIN_FILENO, TCSAFLUSH, &tp) == -1)
        errExit("tcsetattr");

    printf("Echo is now OFF. Type something (it won't show):\n");

    char buf[128];
    fgets(buf, sizeof(buf), stdin);

    printf("You typed: %s\n", buf);

    /* Restore echo before exiting */
    tp.c_lflag |= ECHO;
    if (tcsetattr(STDIN_FILENO, TCSAFLUSH, &tp) == -1)
        errExit("tcsetattr restore");

    return 0;
}

Note: We use bitwise AND with NOT (&= ~ECHO) to clear the ECHO bit. To turn echo back on, we use bitwise OR (|= ECHO) to set the bit.

Partial success:

tcsetattr() returns success (0) if any of the requested changes were applied — even if not all were. It returns -1 only if none of the changes could be applied. So after calling tcsetattr(), if you want to confirm all changes were applied, call tcgetattr() again and compare.

Background process groups — SIGTTOU:

If a process in a background process group calls tcsetattr(), the terminal driver sends the signal SIGTTOU to the entire process group, suspending it. This is the kernel’s way of saying “background processes should not mess with the terminal.”

Orphaned process group — EIO:

If tcsetattr() is called from an orphaned process group (no parent that is a session leader), it fails with errno = EIO.

Older UNIX — ioctl():

In older UNIX systems, terminal attributes were controlled using ioctl() calls directly. The problem was that ioctl() cannot type-check its third argument. POSIX introduced tcgetattr()/tcsetattr() as cleaner, type-safe wrappers. On Linux, these functions internally call ioctl() anyway, but you get proper type checking at the C level.

A practical real-world use case: reading a password without showing it on screen.

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

#define MAX_PASS 64

int main(void) {
    struct termios old_tp, new_tp;
    char password[MAX_PASS];

    /* Save current terminal settings */
    if (tcgetattr(STDIN_FILENO, &old_tp) == -1) {
        perror("tcgetattr");
        exit(EXIT_FAILURE);
    }

    /* Copy and modify: disable echo and canonical mode */
    new_tp = old_tp;
    new_tp.c_lflag &= ~(ECHO | ECHOE | ECHOK | ECHONL);

    /* Apply new settings — TCSAFLUSH discards any type-ahead */
    if (tcsetattr(STDIN_FILENO, TCSAFLUSH, &new_tp) == -1) {
        perror("tcsetattr");
        exit(EXIT_FAILURE);
    }

    printf("Enter password: ");
    fflush(stdout);

    if (fgets(password, MAX_PASS, stdin) != NULL) {
        /* Remove trailing newline */
        password[strcspn(password, "\n")] = '\0';
    }

    printf("\n"); /* move to new line after user pressed Enter */

    /* Restore original terminal settings */
    if (tcsetattr(STDIN_FILENO, TCSAFLUSH, &old_tp) == -1) {
        perror("tcsetattr restore");
        exit(EXIT_FAILURE);
    }

    printf("Password entered (length=%zu). [Not shown]\n", strlen(password));

    /* In real code: verify password here, then clear it from memory */
    memset(password, 0, sizeof(password));

    return 0;
}