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.