S6-FTRIGRD(8)

📦 version 2.15.1.0, in nixpkgs unstable

💅 s6-ftrigrd — the helper that babysits your subscriptions

okay so real talk, this is a page from the System Manager's Manual, and it's about s6-ftrigrd, a helper program that manages a whole set of subscriptions to s6-fifodir(7)s plus regular expressions on events. yes bestie, both. at the same time. she's multi-talented. 🎀

✨ SYNOPSIS ✨

s6-ftrigrd

that's it. that's the whole synopsis. no flags, no args, no drama. 💅

🌸 DESCRIPTION 🌸

okay so here's the tea: s6-ftrigrd takes orders from its client program — the client controls it via s6-ftrigr(7) — and then it notifies that client when the desired events actually happen. it is not meant to be called directly. like, do not just run this at your shell and expect a good time, bestie. it's got main character energy but it needs direction. 😭

here's how she gets launched, depending on what your client does:

  • if the client program uses ftrigr_startf(), it spawns an instance of s6-ftrigrd as a child. in that case, s6-ftrigrd's stdin is a pipe reading from the client; its stdout is a pipe writing to the client; its stderr is the same as the client's; and there's an additional pipe from s6-ftrigrd to the client, used for asynchronous notifications. lots of pipes. plumbing queen. 🪠✨
  • if the client program uses ftrigr_start(), then it tries to connect to a Unix domain socket. an s6-ftrigrd local service should be listening on that socket — like, a Unix domain super-server such as s6-ipcserver(8) spawning an s6-ftrigrd program on every connection. then, boom, an s6-ftrigrd instance is created for the client. 🦋
  • when the client uses ftrigr_end(), or closes s6-ftrigrd's stdin in any way, s6-ftrigrd exits 0. clean exit, no tears, we love to see it. 💖

so what does she actually do all day? s6-ftrigrd handles the grunt work of creating fifos in a fifodir for a subscriber. iconic of her honestly. she also wakes up on every event, and compares the chain of events she received on a given fifodir with the client-provided regexp. if the chain of events matches the regexp, she notifies the client. that's the whole job. she ate. 👑

the connection management between the client and s6-ftrigrd is entirely done by the textclient library from skalibs[1]. not her problem, not her circus. 🤝

⚠️ okay important heads up: s6-ftrigrd is entirely asynchronous. she stores unread notifications into heap memory, and she can grow in size if there are a lot of events and the client fails to read them. that's your cue to not let her balloon, bestie. to avoid uncontrolled growth, make sure your client calls ftrigr_update() as soon as ftrigr_fd() becomes readable. fr fr, don't sleep on that. 😤

and there's a hard limit: an s6-ftrigrd instance can only handle up to FTRIGRD_MAX (defined in s6/ftrigr.h) subscriptions at once. by default, this number is 1000, which is more than enough for any reasonable system. a thousand subscriptions. she's booked and busy. 💀🌸

👀 SEE ALSO 👀

[1] https://skarnet.org/software/skalibs/

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

🫶 AUTHORS 🫶

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

and that's the whole page, bestie — no cap, every last detail kept intact. this Debian build is dated September 29, 2021, and it's S6-FTRIGRD(8) all the way down. go forth and subscribe responsibly ✨🦋💜

📦 where this page comes from