s6: the ftrigw library interface
Keywords: s6 ftrig notification notifier writer libftrigw ftrigw library interface

libs6
s6
Software
skarnet.org

# The `ftrigw` library interface

The `ftrigw` library provides an API for notifiers, i.e. programs that want to regularly announce what they're doing.

Notifiers should create a fifodir in a hardcoded place in the filesystem, and document its location. Listeners will then be able to subscribe to that fifodir, and receive the events.

## Programming

Check the `s6/ftrigw.h` header for the exact function prototypes.

### Creating a fifodir

    char const *path = "/var/lib/myservice/fifodir" ;
    gid_t gid = -1 ;
    int forceperms = 0 ;
    int r = ftrigw_fifodir_make(path, gid, forceperms) ;

`ftrigw_fifodir_make` creates a fifodir at the `path` location. It returns 0, and sets errno, if an error occurs. It returns 1 if it succeeds.
If a fifodir, owned by the user, already exists at `path`, and `forceperms` is zero, then `ftrigw_fifodir_make` immediately returns a success. If `forceperms` is nonzero, then it tries to adjust `path`'s permissions before returning.

If `gid` is negative, then `path` is created "public". Any listener will be able to subscribe to `path`. If `gid` is nonnegative, then `path` is created "private". Only processes belonging to group `gid` will be able to subscribe to `path`.

### Sending an event

    char event = 'a' ;
    r = ftrigw_notify(path, event) ;

`ftrigw_notify` sends `event` to all the processes that are currently subscribed to `path`. It returns -1 if an error occurs, or the number of successfully notified processes.

### Cleaning up

When stray KILL signals hit s6-ftrigrd processes, 1. it's a sign of incorrect system administration, 2. they can leave unused named pipes in the fifodir. It's the fifodir's owner's job, i.e. the notifier's job, to periodically do some housecleaning and remove those unused pipes.

    r = ftrigw_clean(path) ;

`ftrigw_clean` cleans `path`. It returns 0, and sets errno, if it encounters an error. It returns 1 if it succeeds.