PLUMBER(4)

📦 version 0_git20260208, in alpine 3.24, arch rolling, nixos 26.05, nixpkgs unstable

🚰 plumber(4): file system for interprocess messaging 🚰

okay so this page is from the Kernel Interfaces Manual, and it's all about plumber, a user-level file server for plumb(7) messages. Think of it as the group chat dispatcher for programs: it receives messages, examines them, rewrites them, and sends them where they need to go 💅✨

✨ NAME ✨

  • plumber — file system for interprocess messaging.

🌸 SYNOPSIS 🌸

plumber [ -f ] [ -p plumbing ]

🦋 DESCRIPTION 🦋

The plumber is a user-level file server that receives, examines, rewrites, and dispatches plumb(7) messages between programs. Its whole personality is programmed by a plumbing file — default $HOME/lib/plumbing — in the format of plumb(7).

Its services are posted via 9pserve(4) as plumb, and they consist of two predefined files, plumb/send and plumb/rules, plus a set of output ports for dispatching messages to applications. Slay.

Programs use fswrite (see 9pclient(3)) to deliver messages to the send file, and fsread to receive them from the corresponding port. For example, sam(1)'s plumb menu item or the B command cause a message to be sent to plumb/send; sam in turn reads from — by convention — plumb/edit to receive messages about files to open. That's the vibe.

A copy of each message is sent to each client that has the corresponding port open. If none has it open, and the rule has a plumb client or plumb start rule, that rule is applied. A plumb client rule causes the specified command to be run and the message to be held for delivery when the port is opened. A plumb start rule runs the command but discards the message. If neither start nor client is specified and the port is not open, the message is discarded and a write error is returned to the sender. Oof, don't let that be you 😭.

The set of output ports is determined dynamically by the specification in the plumbing rules file: a port is created for each unique destination of a plumb to rule.

The set of rules currently active may be examined by reading the file plumb/rules; appending to this file adds new rules to the set, while creating it (opening it with OTRUNC) clears the rule set. Thus the rule set may be edited dynamically with a traditional text editor. However, ports are never deleted dynamically; if a new set of rules does not include a port that was defined in earlier rules, that port will still exist (although no new messages will be delivered there). Iconic but slightly unhinged, no cap.

The -f option causes the process to run in the foreground.

The synopsis also includes -p plumbing. The page doesn't give extra detail about what it does beyond showing it there, so I'm not gonna make up lore 🙈.

🎀 FILES 🎀

  • $HOME/lib/plumbing — default rules file.
  • /plumb — directory to search for files in include statements.
  • plumb — mount name for plumber(4).

🔥 SOURCE 🔥

/src/cmd/plumb

🌈 SEE ALSO 🌈

that's the whole PLUMBER(4) page, bestie — straight from the Kernel Interfaces Manual, with source at /src/cmd/plumb; the footer just gives the PLUMBER(4) tag, so no extra date/version deets to report 💜✨

📦 where this page comes from