From 90b12bd71bb9fc79a4640b9112c13ef529d0196a Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Fri, 5 Dec 2014 22:26:11 +0000 Subject: Initial commit --- doc/libftrigw.html | 115 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 doc/libftrigw.html (limited to 'doc/libftrigw.html') diff --git a/doc/libftrigw.html b/doc/libftrigw.html new file mode 100644 index 0000000..d804976 --- /dev/null +++ b/doc/libftrigw.html @@ -0,0 +1,115 @@ + + + + + s6: the ftrigw library interface + + + + + + +

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

+ +

Compiling

+ + + +

Linking

+ + + +

Programming

+ +

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

+ +

Creating a fifodir

+ +
+char const *path = "/var/lib/myservice/fifodir" ;
+int 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 take out +the trash. +

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

+ + + -- cgit v1.2.3