NG_TTY(4)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NG_TTY(4) — the netgraph node that's also a TTY hook 💖

okay bestie, sit down, hydrate, and let me tell you about ng_tty, a lil node type living in the Kernel Interfaces Manual. it's giving double life, it's giving multihyphenate, and honestly? iconic. 🎀

✨ SYNOPSIS ✨

so first things first, you gotta pull in the headers, like:

#include <sys/types.h>
#include <sys/ttycom.h>
#include <netgraph/ng_tty.h>

no cap, that's the whole vibe check right there. 🦋

🌸 DESCRIPTION 🌸

the tty node type is lowkey doing two jobs at once — it's a netgraph node type AND a TTY hook. main character energy fr fr. 👑

it has exactly one hook and that hook is named hook. yes, just hook. no notes, we love a minimalist.

here's the tea on how data flows:

  • bytes coming in on the tty device get sent out on this hook
  • frames coming in on hook get transmitted out on the tty device

and ngl, the node does zero modification to the data in either direction. it's just a pass-through bestie, no editing, no commentary. 💅

⚠️ important warning time: while the hook is installed on a tty, the normal read and write operations are unavailable — they'll return EIO. so like, don't be surprised, okay? 😭

incoming data gets delivered directly to ng_tty via the tty bypass hook as a buffer pointer and length, and that gets converted into an mbuf and handed off to the peer. cute, efficient, slay. ✨

🔥 the hot character (yes it's called that) 🔥

the node supports an optional "hot character". i know, i know, the name is a lot. 🙈

the deal is this: if the driver can't deliver data directly to the tty bypass hook, then each character gets input one at a time. so if the hot character is set to something non-zero and bypass mode isn't available, incoming data from the tty device gets queued up until that character is spotted.

why tho? because it avoids sending a whole bunch of mbufs that each contain like, three bytes. but the tradeoff — and this is the part where you gotta be careful — it introduces potentially infinite latency. yeah. infinite. not a typo. 💀

the default hot character is 0x7e, which is consistent with hook being connected to a ng_async(4) type node. 🫶

and just so we're clear: the hot character has no effect on the transmission of data. it's a receiving-side thing only, okay? periodt.

🎀 HOOKS 🎀

this node type supports the following hooks:

  • hook — tty(4) serial data contained in mbuf structures, with arbitrary inter-frame boundaries. that's it, that's the hook. one hook, one job, no drama. 🌈

👑 CONTROL MESSAGES 👑

this node type supports the generic control messages, plus these bad boys:

  • NGM_TTY_SET_HOTCHAR — takes an integer argument and sets the hot character from the lower 8 bits. a hot character of zero disables queueing, so that all received data is forwarded immediately. instant. no waiting. slay. ⭐
  • NGM_TTY_GET_HOTCHAR — returns an integer containing the current hot character in the lower eight bits. it's the read to the other one's write, we love a matching set. 💜
  • NGM_TTY_SET_TTY — takes an integer process ID and file descriptor of an open tty and registers the tty hooks. that's the setup step, bestie. 🔥

🦋 SHUTDOWN 🦋

this node shuts down when the corresponding device is closed. simple as that. goodbye, farewell, it's been real. 😭

💜 SEE ALSO 💜

go read those too, i'll wait. 🍓

⭐ HISTORY ⭐

the ng_tty node type was implemented in FreeBSD 4.0. vintage. retro. a classic. 🧚

🌈 AUTHORS 🌈

  • Archie Cobbs <archie@FreeBSD.org>
  • Andrew Thompson <thompsa@FreeBSD.org>

absolute legends, we stan. 👑

💀 BUGS 💀

okay so here's the messy part, and i need you to pay attention:

the serial driver code also has a notion of a "hot character". unfortunately, this value is statically defined in terms of the line discipline and cannot be changed. 😭

so therefore: if a hot character other than 0x7e (the default) is set for the ng_tty node, the node has no way to convey this information to the serial driver, and sub-optimal performance may result. that's the whole bug. two hot characters, no communication, it's giving situationship. 💅

anyway bestie, that's ng_tty — this page came from the Debian crew, dated December 25, 2008, so like, a lil vintage but still hitting. go forth and configure responsibly. mwah. 💖✨🎀

📦 where this page comes from