ftrigw.html (2994B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>s6: the ftrigw library interface</title> 7 <meta name="Description" content="s6: the ftrigw library interface" /> 8 <meta name="Keywords" content="s6 ftrig notification notifier writer libftrigw ftrigw library interface" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">libs6</a><br /> 15 <a href="../">s6</a><br /> 16 <a href="//skarnet.org/software/">Software</a><br /> 17 <a href="//skarnet.org/">skarnet.org</a> 18 </p> 19 20 <h1> The <tt>ftrigw</tt> library interface </h1> 21 22 <p> 23 The <tt>ftrigw</tt> library provides an API for notifiers, i.e. 24 programs that want to regularly announce what they're doing. 25 </p> 26 27 <p> 28 Notifiers should create a fifodir in a hardcoded place in the 29 filesystem, and document its location. Listeners will then be 30 able to subscribe to that fifodir, and receive the events. 31 </p> 32 33 <h2> Programming </h2> 34 35 <p> 36 Check the <tt>s6/ftrigw.h</tt> header for the 37 exact function prototypes. 38 </p> 39 40 <h3> Creating a fifodir </h3> 41 42 <pre> 43 char const *path = "/var/lib/myservice/fifodir" ; 44 gid_t gid = -1 ; 45 int forceperms = 0 ; 46 int r = ftrigw_fifodir_make(path, gid, forceperms) ; 47 </pre> 48 49 <p> 50 <tt>ftrigw_fifodir_make</tt> creates a fifodir at the <tt>path</tt> location. 51 It returns 0, and sets errno, if an error occurs. 52 It returns 1 if it succeeds. <br /> 53 If a fifodir, owned by the user, already exists at <tt>path</tt>, and 54 <tt>forceperms</tt> is zero, then <tt>ftrigw_fifodir_make</tt> immediately 55 returns a success. If <tt>forceperms</tt> is nonzero, then 56 it tries to adjust <tt>path</tt>'s permissions before returning. 57 </p> 58 59 <p> 60 If <tt>gid</tt> is negative, then <tt>path</tt> is created "public". 61 Any listener will be able to subscribe to <tt>path</tt>. 62 If <tt>gid</tt> is nonnegative, then <tt>path</tt> is created "private". 63 Only processes belonging to group <tt>gid</tt> will be able to 64 subscribe to <tt>path</tt>. 65 </p> 66 67 <h3> Sending an event </h3> 68 69 <pre> 70 char event = 'a' ; 71 r = ftrigw_notify(path, event) ; 72 </pre> 73 74 <p> 75 <tt>ftrigw_notify</tt> sends <tt>event</tt> to all the processes that are 76 currently subscribed to <tt>path</tt>. 77 It returns -1 if an error occurs, or the number of successfully notified 78 processes. 79 </p> 80 81 <h3> Cleaning up </h3> 82 83 <p> 84 When stray KILL signals hit <a href="s6-ftrigrd.html">s6-ftrigrd</a> processes, 85 1. it's a sign of incorrect system administration, 2. they can leave 86 unused named pipes in the fifodir. It's the fifodir's owner's job, i.e. 87 the notifier's job, to periodically do some housecleaning and remove 88 those unused pipes. 89 </p> 90 91 <pre> 92 r = ftrigw_clean(path) ; 93 </pre> 94 95 <p> 96 <tt>ftrigw_clean</tt> cleans <tt>path</tt>. It returns 0, and sets errno, 97 if it encounters an error. It returns 1 if it succeeds. 98 </p> 99 100 </body> 101 </html>