S6-FTRIGW(7)

NAME
s6-ftrigw - API for notifiers, i.e. programs that want to regularly announce what they're doing

DESCRIPTION
Notifiers should create an s6-fifodir(7) in a hardcoded place in the filesystem, and document its location. Listeners will then be able to subscribe to that s6-fifodir(7), and receive the events.

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 an s6-fifodir(7) at the path location. It returns 0, and sets errno, if an error occurs. It returns 1 if it succeeds.

If an s6-fifodir(7), owned by the user, already exists at path, and forceperms is zero, then ftrigw_fifodir_make() immediately returns 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(8) processes,

1.  it's a sign of incorrect system administration,

2.  they can leave unused named pipes in the s6-fifodir(7).

It's the s6-fifodir(7)' 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.

SEE ALSO
s6-accessrules(7), s6-fdholder(7), s6-ftrigr(7), s6-libs6(7), s6-s6lock(7)

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

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