fifodir.html (5500B)
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: fifodirs</title> 7 <meta name="Description" content="s6: fifodirs" /> 8 <meta name="Keywords" content="s6 instant notification polling fifodir named pipe filesystem" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">s6</a><br /> 15 <a href="//skarnet.org/software/">Software</a><br /> 16 <a href="//skarnet.org/">skarnet.org</a> 17 </p> 18 19 <h1> Fifodirs </h1> 20 21 <p> 22 A <em>fifodir</em> is a rendez-vous point between the <em>notifier</em> 23 of certain events and its <em>listeners</em>. It is implemented via a 24 directory in the filesystem. No data is stored; it is appropriate to 25 create fifodirs in a RAM filesystem. 26 </p> 27 28 <h2> Manipulating fifodirs </h2> 29 30 <h3> C API </h3> 31 32 <h4> For the notifier </h4> 33 34 <ul> 35 <li> You can create fifodirs via the 36 <tt>ftrigw_fifodir_create()</tt> function in 37 <a href="libs6/ftrigw.html">libftrig</a>. </li> 38 <li> You can send an event to a fifodir via the 39 <tt>ftrigw_notify()</tt> function in the notifier part of the 40 <a href="libs6/ftrigw.html">libftrig</a>. </li> 41 <li> You can clean up a fifodir via the 42 <tt>ftrigw_clean()</tt> function in 43 <a href="libs6/ftrigw.html">libftrig</a>. </li> 44 <li> You can destroy fifodirs via the 45 <tt>rm_rf()</tt> function in 46 <a href="//skarnet.org/software/skalibs/libstddjb/djbunix.html">libstddjb</a>. </li> 47 </ul> 48 49 <h4> For a listener </h4> 50 51 <ul> 52 <li> You can subscribe to a fifodir via the <tt>ftrigr_subscribe()</tt> 53 function in the listener part of the <a href="libs6/ftrigr.html">libftrig</a>. </li> 54 <li> Other functions in the <a href="libs6/ftrigr.html">libftrig</a> allow 55 you to receive and handle events synchronously or asynchronously. </li> 56 </ul> 57 58 <h3> Unix API </h3> 59 60 <h4> For the notifier </h4> 61 62 <ul> 63 <li> You can create fifodirs with the 64 <a href="s6-mkfifodir.html">s6-mkfifodir</a> command. </li> 65 <li> You can send an event to a fifodir with the 66 <a href="s6-ftrig-notify.html">s6-ftrig-notify</a> command. </li> 67 <li> You can clean up a fifodir with the 68 <a href="s6-cleanfifodir.html">s6-cleanfifodir</a> command. </li> 69 <li> You can destroy fifodirs with the <tt>rm -rf</tt> command. </li> 70 </ul> 71 72 <h4> For a listener </h4> 73 74 <ul> 75 <li> You can subscribe to a fifodir and wait for an event, or a series 76 or events, with the 77 <a href="s6-ftrig-wait.html">s6-ftrig-wait</a> command. </li> 78 <li> You can subscribe to a fifodir, then trigger a program, then 79 wait for an event, with the 80 <a href="s6-ftrig-listen1.html">s6-ftrig-listen1</a> and 81 <a href="s6-ftrig-listen.html">s6-ftrig-listen</a> commands. This 82 makes it possible to only send a notification after you're sure 83 a notifier is actually listening, in order to prevent race conditions. </li> 84 </ul> 85 86 <h2> Internals and Unix permissions </h2> 87 88 <ul> 89 <li> Notifiers and listeners agree on a fifodir. </li> 90 <li> The fifodir directory is created by the notifier. It must be writable 91 by listeners. </li> 92 <li> To subscribe, a listener atomically creates a named pipe (FIFO) in this 93 directory and listens to the reading end. This named pipe must be writable 94 by the notifier. </li> 95 <li> To send an event to listeners, the notifier writes the event byte to 96 all the named pipes in the directory. Credit for this idea goes to Stefan 97 Karrmann. </li> 98 <li> To unsubscribe, a listener unlinks his named pipe from the directory. </li> 99 </ul> 100 101 <p> 102 Note that in the s6 implementation of fifodirs, there are a few additional 103 details: for instance, the named pipes created in a fifodir by a listener 104 follow a strict naming convention, for efficiency and safety reasons. If 105 you are using fifodirs, it is recommended that you use the provided C library 106 functions or the <tt>s6-ftrig-*</tt> command line utilities instead of 107 directly hacking into the fifodir internals. 108 </p> 109 110 <p> 111 Fifodirs are created by their notifier, so they always originally inherit its 112 uid and gid. A notifier must be able to make his fifodir either publicly 113 accessible (anyone can subscribe) or restricted (only a given group can 114 subscribe). 115 </p> 116 117 <p> 118 A publicly accessible fifodir must have rights 1733: 119 </p> 120 121 <ul> 122 <li> Anyone can create a fifo in that fifodir </li> 123 <li> Only the notifier can see all the subscribers' fifos </li> 124 <li> A listener can only delete its own fifo </li> 125 <li> A notifier can delete any fifo for cleaning purposes </li> 126 </ul> 127 128 <p> 129 A restricted fifodir must have the gid <em>g</em> of the group of allowed 130 listeners and have rights 3730. Unless the notifier is root, it 131 must be in the group of allowed listeners to be able to create 132 such a fifodir. 133 </p> 134 135 <ul> 136 <li> Only members of <em>g</em> can create a fifo in that fifodir </li> 137 <li> Only the notifier can see all the subscribers' fifos </li> 138 <li> Fifos are always created with gid <em>g</em> </li> 139 <li> A listener can only delete its own fifo </li> 140 <li> A notifier can delete any fifo for cleaning purposes </li> 141 </ul> 142 143 <p> 144 A named pipe in a fifodir must always belong to its listener and have 145 rights 0622: 146 </p> 147 148 <ul> 149 <li> Only this listener can read on the fifo </li> 150 <li> Anyone who has reading rights on the fifodir (i.e. only the notifier) 151 can write to the fifo </li> 152 </ul> 153 154 <p> 155 The <a href="ftrig.html">libftrig</a> interface takes care of all 156 the subtleties. 157 </p> 158 159 </body> 160 </html>