NG_DEVICE(4)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💜 NG_DEVICE(4) — like, the device netgraph node type, bestie

okay so this is a page from the Kernel Interfaces Manual, and it's all about the netgraph node type literally called ng_device. pull up a chair 🎀

✨ SYNOPSIS ✨

#include <netgraph/ng_device.h>

that's it, that's the include. iconic. 💅

🌸 DESCRIPTION 🌸

so a device node is two things at once — it's a netgraph node and it's a system device interface. main character energy fr fr. ✨

when a device node gets created, a brand-new device entry pops into existence, and you can get at it with all the regular file operators you already know and love: open(2), close(2), read(2), write(2), etc. no cap. 🫶

and the naming? super simple:

  • the first node ever created is /dev/ngd0
  • then /dev/ngd1, /dev/ngd2, etc. just keep counting up 💫

🦋 HOOKS 🦋

a device node has a single hook, and its name is literally whatever you want — arbitrary name, your call, go off. 🎀

the data flow is giving very much two-way street:

  • all data coming in over the hook gets presented to the device for read(2) 💖
  • all data coming in from the device entry via write(2) gets forwarded to the hook 💖

symmetry! we love to see it. 😭

👑 CONTROL MESSAGES 👑

the device node supports the generic control messages, plus these two:

  • NGM_DEVICE_GET_DEVNAME — hands you back the device name that corresponds to the node. cute and useful. 🌸
  • NGM_DEVICE_ETHERALIGN — applies the system ETHER_ALIGN offset to mbufs sent out the node's hook, but only if you're running on an architecture that requires strict alignment. you want this when the data you're injecting via the device node ultimately ends up being fed into the protocol stack as ethernet packets (e.g., via an ng_eiface(4) node). 🧚
real talk: NGM_DEVICE_ETHERALIGN is the lowkey hero here — if your arch is strict about alignment and you skip it, that's a whole vibe check you don't wanna fail 💀

⭐ SHUTDOWN ⭐

this node shuts down when it receives a NGM_SHUTDOWN control message, or when the hook gets disconnected. periodt.

and when it goes? the associated device entry gets removed and becomes available for use by future device nodes. recycling! sustainability! 🌈

🔥 SEE ALSO 🔥

💜 HISTORY 💜

the device node type was first implemented in FreeBSD 5.0. vintage. 🎀

💅 AUTHORS 💅

  • Mark Santcroos <marks@ripe.net>
  • Gleb Smirnoff <glebius@FreeBSD.org>

and that's the whole page, bestie — go forth and open(2) something 🦋✨

this lil rewrite is from the Debian build, dated November 8, 2021 — mwah, love u, bye 💖🎀

📦 where this page comes from