The s6-ftrigrd program

s6-ftrigrd is a helper program that manages a set of subscriptions to fifodirs as well as regular expressions on events. It takes orders from its client program that controls it via the ftrigr library, and notifies it when desired events happen.

Interface

s6-ftrigrd is not meant to be called directly.

If the client program uses ftrigr_startf(), it spawns an instance of s6-ftrigrd as a child. 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.
If the client program uses ftrigr_start(), then it tries to connect to a Unix domain socket. A ftrigrd service should be listening to that socket, i.e. a Unix domain superserver such as s6-ipcserver spawning a s6-ftrigrd program on every connection. Then a s6-ftrigrd instance is created for the client: its stdin and stdout are the socket, its stderr is normally logged by the service's logger, and there's also an additional pipe from s6-ftrigrd to the client, used for asynchronous notifications. Such a pipe can exist thanks to some Unix black magic (the libancillary, if you must know).
When the client uses ftrigr_end(), or closes s6-ftrigrd's stdin in any way, s6-ftrigrd exits 0.

s6-ftrigrd handles the grunt work of creating fifos in a fifodir for a subscriber. It also wakes up on every event, and compares the chain of events it received on a given fifodir with the client-provided regexp. If the chain of events matches the regexp, it notifies the client.

Notes

The connection management between the client and s6-ftrigrd is entirely done by the skaclient library. The protocol uses netstrings for message boundaries.

s6-ftrigrd is entirely asynchronous. It stores unread notifications into heap memory; it can grow in size if there are a lot of events and the client fails to read them. To avoid uncontrolled growth, make sure your client calls ftrigr_update() as soon as ftrigr_fd() becomes readable.