S6-FIFODIR(7)

NAME
s6-fifodir - rendez-vous point between the notifier of certain events and its listeners

DESCRIPTION
An s6-fifodir is implemented via a directory in the filesystem. No data is stored; it is appropriate to create fifodirs in a RAM filesystem.

  C API
For the notifier:

•   You can create fifodirs via the ftrigw_fifodir_create() function in s6-ftrigw(7).

•   You can send an event to a fifodir via the ftrigw_notify() function in the notifier part of s6-ftrigw(7).

•   You can clean up a fifodir via the ftrigw_clean() function in s6-ftrigw(7).

•   You can destroy fifodirs via the rm_rf() function in libstddjb[1].

For a listener:

•   You can subscribe to a fifodir via the ftrigr_subscribe() function in the listener part of the s6-ftrigr(7).

•   Other functions in s6-ftrigr(7) allow you to receive and handle events synchronously or asynchronously.

  Unix API
For the notifier:

•   You can create fifodirs with the s6-mkfifodir(8) command.

•   You can send an event to a fifodir with the s6-ftrig-notify(8) command.

•   You can clean up a fifodir with the s6-cleanfifodir(8) 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(8) command.

•   You can subscribe to a fifodir, then trigger a program, then wait for an event, with the s6-ftrig-listen1(8) and s6-ftrig-listen(8) 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.

IMPLEMENTATION NOTES

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

SEE ALSO
[1] https://skarnet.org/software/skalibs/libstddjb/djbunix.html

This man page is ported from the authoritative documentation at: https://skarnet.org/software/s6/fifodir.html

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