S6-FIFODIR(7)

📦 version 2.15.1.0, in nixpkgs unstable

✨ s6-fifodir — the manual, but make it a group chat ✨

okay so bestie, welcome to s6-fifodir(7), Miscellaneous Information Manual section 7. this is the whole vibe of a fifodir: it's literally the rendez-vous point 💫 between the notifier of certain events and its listeners. like a lil hangout spot where the notifier says "hey!! something happened!!" and everyone who's listening hears about it. iconic behavior honestly.

💖 NAME 💖

s6-fifodir — the rendez-vous point between the notifier of certain events and its listeners 🫶

🌸 DESCRIPTION 🌸

so an s6-fifodir is implemented via a directory in the filesystem. that's it. that's the whole thing. no data is stored in it — which means it is appropriate to create fifodirs in a RAM filesystem ✨ (yes, ram fs, because you're not storing anything, so why waste the disk, bestie).

🎀 C API 🎀

okay for the notifier side of things:

  • you can create fifodirs via the ftrigw_fifodir_create() function in s6-ftrigw(7) 🎀
  • you can send an event to a fifodir via the ftrigw_notify() function in the notifier part of s6-ftrigw(7) 📣
  • you can clean up a fifodir via the ftrigw_clean() function in s6-ftrigw(7) 🧹
  • you can destroy fifodirs via the rm_rf() function in libstddjb[1] 💀

and for a listener:

  • you can subscribe to a fifodir via the ftrigr_subscribe() function in the listener part of the s6-ftrigr(7) 🦋
  • other functions in s6-ftrigr(7) allow you to receive and handle events synchronously or asynchronously ⭐

🌈 Unix API 🌈

for the notifier:

for a listener:

  • you can subscribe to a fifodir and wait for an event, or a series or events, with the s6-ftrig-wait(8) command ⏳
  • you can subscribe to a fifodir, then trigger a program, then wait for an event, with the s6-ftrig-listen1(8) and s6-ftrig-listen(8) commands. this makes it possible to only send a notification after you're sure a notifier is actually listening, in order to prevent race conditions 🏁 no cap, that's the good stuff.

👑 IMPLEMENTATION NOTES 👑

  • notifiers and listeners agree on a fifodir 🤝
  • the fifodir directory is created by the notifier. it must be writable by listeners.
  • to subscribe, a listener atomically creates a named pipe (FIFO) in this directory and listens to the reading end. this named pipe must be writable by the notifier.
  • to send an event to listeners, the notifier writes the event byte to all the named pipes in the directory. credit for this idea goes to Stefan Karrmann 👏 periodt.
  • to unsubscribe, a listener unlinks his named pipe from the directory.
heads up bestie — note that in the s6 implementation of fifodirs, there are a few additional details: for instance, the named pipes created in a fifodir by a listener follow a strict naming convention, for efficiency and safety reasons. if you are using fifodirs, it is recommended that you use the provided C library functions or the s6-ftrig-* command line utilities instead of directly hacking into the fifodir internals 🙈

fifodirs are created by their notifier, so they always originally inherit its uid and gid. a notifier must be able to make his fifodir either publicly accessible (anyone can subscribe) or restricted (only a given group can subscribe).

🧚 a publicly accessible fifodir 🧚

it must have rights 1733:

  • anyone can create a fifo in that fifodir
  • only the notifier can see all the subscribers' fifos
  • a listener can only delete its own fifo
  • a notifier can delete any fifo for cleaning purposes

🍓 a restricted fifodir 🍓

it must have the gid g of the group of allowed listeners and have rights 3730. unless the notifier is root, it must be in the group of allowed listeners to be able to create such a fifodir.

  • only members of g can create a fifo in that fifodir
  • only the notifier can see all the subscribers' fifos
  • fifos are always created with gid g
  • a listener can only delete its own fifo
  • a notifier can delete any fifo for cleaning purposes

💅 and the named pipe itself 💅

a named pipe in a fifodir must always belong to its listener and have rights 0622:

  • only this listener can read on the fifo
  • anyone who has reading rights on the fifodir (i.e. only the notifier) can write to the fifo

the libftrig interface takes care of all the subtleties ✨ so like, let it.

🔥 SEE ALSO 🔥

this man page is ported from the authoritative documentation at: https://skarnet.org/software/s6/fifodir.html

💜 AUTHORS 💜

  • Laurent Bercot
  • Alexis <flexibeast@gmail.com> (man page port)

that's the whole page, bestie, you ate that 🫶✨ the Debian version of this dropped November 7, 2023 — the S6-FIFODIR(7) era, we love to see it 💅🎀 bye mwah 😘

📦 where this page comes from