Fifodirs

A fifodir is a rendez-vous point between the notifier of certain events and its listeners. It is implemented via a directory in the filesystem. No data is stored; it is appropriate to create fifodirs in a RAM filesystem.

Manipulating fifodirs

C API

For the notifier

You can create fifodirs via the ftrigw_fifodir_create() function in libftrig.
You can send an event to a fifodir via the ftrigw_notify() function in the notifier part of the libftrig.
You can clean up a fifodir via the ftrigw_clean() function in libftrig.
You can destroy fifodirs via the rm_rf() function in libstddjb.

For a listener

You can subscribe to a fifodir via the ftrigr_subscribe() function in the listener part of the libftrig.
Other functions in the libftrig allow you to receive and handle events synchronously or asynchronously.

Unix API

For the notifier

You can create fifodirs with the s6-mkfifodir command.
You can send an event to a fifodir with the s6-ftrig-notify command.
You can clean up a fifodir with the s6-cleanfifodir command.
You can destroy fifodirs with the rm -rf command.

For a listener

You can subscribe to a fifodir and wait for an event, or a series or events, with the s6-ftrig-wait command.
You can subscribe to a fifodir, then trigger a program, then wait for an event, with the s6-ftrig-listen1 and s6-ftrig-listen 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.

Internals and Unix permissions

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.
To unsubscribe, a listener unlinks his named pipe from the directory.

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 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 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

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.