s6: fifodirs
Keywords: s6 instant notification polling fifodir named pipe filesystem

s6
Software
skarnet.org

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