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.