From 81c7a02ec870ef3dba9f8b8f8dbecbd119e5ea47 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Sat, 31 Dec 2016 10:55:56 +0000
Subject:  Fifodir doc clarification (thanks Buck Evans)

---
 doc/fifodir.html | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/doc/fifodir.html b/doc/fifodir.html
index 7dbddfa..eccdf5b 100644
--- a/doc/fifodir.html
+++ b/doc/fifodir.html
@@ -29,12 +29,14 @@ create fifodirs in a RAM filesystem.
 
 <h3> C API </h3>
 
+<h4> For the notifier </h4>
+
 <ul>
  <li> You can create fifodirs via the
 <tt>ftrigw_fifodir_create()</tt> function in
 <a href="libs6/ftrigw.html">libftrig</a>. </li>
  <li> You can send an event to a fifodir via the
-<tt>ftrigw_notify()</tt> function in 
+<tt>ftrigw_notify()</tt> function in the notifier part of the
 <a href="libs6/ftrigw.html">libftrig</a>. </li>
  <li> You can clean up a fifodir via the
 <tt>ftrigw_clean()</tt> function in
@@ -44,8 +46,19 @@ create fifodirs in a RAM filesystem.
 <a href="http://skarnet.org/software/skalibs/doc/libstddjb/djbunix.html">libstddjb</a>. </li>
 </ul>
 
+<h4> For a listener </h4>
+
+<ul>
+ <li> You can subscribe to a fifodir via the <tt>ftrigr_subscribe()</tt>
+function in the listener part of the <a href="libs6/ftrigr.html">libftrig</a>. </li>
+ <li> Other functions in the <a href="libs6/ftrigr.html">libftrig</a> allow
+you to receive and handle events synchronously or asynchronously. </li>
+</ul>
+
 <h3> Unix API </h3>
 
+<h4> For the notifier </h4>
+
 <ul>
  <li> You can create fifodirs with the
 <a href="s6-mkfifodir.html">s6-mkfifodir</a> command. </li>
@@ -55,6 +68,20 @@ create fifodirs in a RAM filesystem.
 <a href="s6-cleanfifodir.html">s6-cleanfifodir</a> command. </li>    
  <li> You can destroy fifodirs with the <tt>rm -rf</tt> command. </li>
 </ul>  
+
+<h4> For a listener </h4>
+
+<ul>
+ <li> You can subscribe to a fifodir and wait for an event, or a series
+or events, with the
+<a href="s6-ftrig-wait.html">s6-ftrig-wait</a> command. </li>
+ <li> You can subscribe to a fifodir, then trigger a program, then
+wait for an event, with the
+<a href="s6-ftrig-listen1.html">s6-ftrig-listen1</a> and
+<a href="s6-ftrig-listen.html">s6-ftrig-listen</a> commands. This
+makes it possible to only send a notification after you're sure
+a notifier is actually listening, in order to prevent race conditions. </li>
+</ul>
     
 <h2> Internals and Unix permissions </h2>
 
@@ -71,6 +98,15 @@ Karrmann. </li>
  <li> To unsubscribe, a listener unlinks his named pipe from the directory. </li>
 </ul>  
 
+<p>
+ Note that in the s6 implementation of fifodirs, there are a few additional
+details: for instance, the named pipes created in a fifodir by a listener
+follow a strict naming convention, for efficiency and safety reasons. If
+you are using fifodirs, it is recommended that you use the provided C library
+functions or the <tt>s6-ftrig-*</tt> command line utilities instead of
+directly hacking into the fifodir internals.
+</p>
+
 <p>
 Fifodirs are created by, so they always originally have the same uid and gid as,
 their notifier. A notifier must be able to make his fifodir either publically
-- 
cgit v1.3.1