STRUCT TTY_STRUCT(9)

💖 struct tty_struct(9) — Kernel API Manual 💖

okay so bestie, we're in struct tty_struct(9) territory, aka the Kernel API Manual page you did not know you needed but absolutely do. this is the whole vibe of a tty while it's open — every lock, every buffer, every little flag. it's giving backstage-pass-to-the-terminal. no cap.

✨ SYNOPSIS ✨

like, the literal shape of it. don't touch, just vibe:

struct tty_struct {
    struct kref kref;
    int index;
    struct device *dev;
    struct tty_driver *driver;
    struct tty_port *port;
    const struct tty_operations *ops;
    struct tty_ldisc *ldisc;
    struct ld_semaphore ldisc_sem;
    struct mutex atomic_write_lock;
    struct mutex legacy_mutex;
    struct mutex throttle_mutex;
    struct rw_semaphore termios_rwsem;
    struct mutex winsize_mutex;
    struct ktermios termios, termios_locked;
    char name[64];
    unsigned long flags;
    int count;
    unsigned int receive_room;
    struct winsize winsize;
    struct {
      spinlock_t lock;
      bool stopped;
      bool tco_stopped;
    } flow;
    struct {
      struct pid *pgrp;
      struct pid *session;
      spinlock_t lock;
      unsigned char pktstatus;
      bool packet;
    } ctrl;
    bool hw_stopped;
    bool closing;
    int flow_change;
    struct tty_struct *link;
    struct fasync_struct *fasync;
    wait_queue_head_t write_wait;
    wait_queue_head_t read_wait;
    wait_queue_head_t break_wait;
    struct work_struct hangup_work;
    void *disc_data;
    void *driver_data;
    spinlock_t files_lock;
    int write_cnt;
    u8 *write_buf;
    struct list_head tty_files;
    struct work_struct SAK_work;
 };

🎀 Members 🎀

grab a snack, we're going field by field. it's a lot. it's iconic. it's a journey.

• kref — reference counting handled by tty_kref_get and tty_kref_put; the way it works is when it hits zero the whole structure gets freed. 💀
• index — the index of this tty (think: so you can construct a name like tty12).
• dev — a class device, or NULL (like for ptys, serdev).
• driver — the struct tty_driver that operates this tty.
• port — the persistent storage for this device, aka struct tty_port.
• ops — the struct tty_operations of the driver for this tty (open, close, etc.).
• ldisc — the current line discipline for this tty (n_tty by default).
• ldisc_sem — protects line discipline changes (ldisc) — and bestie, lock the tty, not the pty.
• atomic_write_lock — protects against concurrent writers, i.e. it locks write_cnt, write_buf and similar.
• legacy_mutex — a leftover from history (BKL -> BTM -> legacy_mutex), protecting several operations on this tty. yes it's old. yes it's still here. 🫠
• throttle_mutex — protects against concurrent tty_throttle_safe and tty_unthrottle_safe (but not tty_unthrottle, mind you).
• termios_rwsem — protects termios and termios_locked.
• winsize_mutex — protects winsize.
• termios — the termios for the current tty, copied from/to driver.termios.
• termios_locked — locked termios (by the TIOCGLCKTRMIOS and TIOCSLCKTRMIOS ioctls).
• name — the name of the tty, constructed by tty_line_name (e.g. ttyS3).
• flags — bitwise OR of TTY_THROTTLED, TTY_IO_ERROR, ...
• count — count of open processes; when it hits zero it cancels all the work for this tty and drops a kref too (but it does not free this tty — important distinction, don't come for me).
• receive_room — bytes permitted to feed to ldisc without any being lost.
• winsize — the size of the terminal "window" (cf. winsize_mutex).
• flow — flow settings, grouped together 🫶
• flow.lock — lock for flow members.
• flow.stopped — tty stopped/started by stop_tty/start_tty.
• flow.tco_stopped — tty stopped/started by TCOOFF/TCOON ioctls (and heads up: it has precedence over flow.stopped).
• ctrl — control settings, also grouped together.
• ctrl.pgrp — the process group of this tty (setpgrp(2)).
• ctrl.session — the session of this tty (setsid(2)). Writes are protected by both ctrl.lock and legacy_mutex, and readers must use at least one of them. no skipping, iykyk.
• ctrl.lock — lock for ctrl members.
• ctrl.pktstatus — packet mode status (bitwise OR of TIOCPKT_ constants).
• ctrl.packet — packet mode enabled.
• hw_stopped — not controlled by the tty layer; it's under the driver's control for CTS handling.
• closing — when set during close, n_tty processes only START & STOP chars.
• flow_change — controls behavior of throttling, see tty_throttle_safe and tty_unthrottle_safe.
• link — link to another pty (master -> slave and vice versa) 🦋
• fasync — state for O_ASYNC (for SIGIO); managed by fasync_helper.
• write_wait — concurrent writers are waiting in this queue until they're allowed to write.
• read_wait — readers wait for data in this queue.
• break_wait — wait queue for timed breaks.
• hangup_work — normally a work to perform a hangup (do_tty_hangup); while freeing the tty, it's (re)used to release_one_tty.
• disc_data — pointer to ldisc's private data (e.g. to struct n_tty_data).
• driver_data — pointer to driver's private data (e.g. struct uart_state).
• files_lock — protects the tty_files list.
• write_cnt — count of bytes written in tty_write to write_buf.
• write_buf — temporary buffer used during tty_write to copy user data to.
• tty_files — list of (re)openers of this tty (i.e. linked struct tty_file_private).
• SAK_work — if the tty has a pending do_SAK, it is queued here.

🌸 Description 🌸

literally all of the state associated with a tty while the tty is open. that's the whole bit. Persistent storage for tty devices is referenced here as port, and it's documented over in struct tty_port. go read that one next, bestie, it's the sequel. 📖

🌈 SEE ALSO 🌈

• Kernel file ./include/linux/tty.h enum tty_struct_flags(9)
• tty_kref_get(9)
• tty_get_baud_rate(9)

and that's the page!! 🎀✨ this little beauty lives under ./include/linux and was last touched in October 2026 — so like, yeah, mwah, slay, go read your ttys responsibly 💅🫶