s6: the s6-ftrigrd program
Keywords: s6 command s6-ftrigrd program internal libexec fifodir regexp subscribe notification listener

libs6
s6
Software
skarnet.org

# 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. An ftrigrd local service should be listening to that socket, i.e. a Unix domain super-server such as s6-ipcserver spawning an s6-ftrigrd program on every connection. Then 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.

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 textclient library from skalibs.

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.

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.