prefork-interp: protocol documentation

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/cprogs/prefork-interp.c b/cprogs/prefork-interp.c
index 8987dcf32b0c47415ff6c4fc1286af7c99825e22..de9e0af399a33d554857b8bc73f56d8c40352382 100644 (file)
--- a/cprogs/prefork-interp.c
+++ b/cprogs/prefork-interp.c
@@ -253,22 +253,23 @@
 
   2. Env var PREFORK_INTERP contains:
 
-         v1,SECS.NSECS[,...] LISTEN,CALL,WATCHE,WATCHI[,...][ ...]
+         v1,SECS.NSECS[,...] LISTEN,CALL,WATCHE,WATCHI[,...][ ???]
 
-     To parse it: split on ASCII space (or any whitespace), taking
-     first two words.  There may or may not be further "words".
-     Then split each of the first two words on comma,
-     again taking the initial items as specified.  The items are:
+     To parse it: treat as bytes and split on ASCII space, taking
+     the first two words.  (There may or may not be
+     further "words"; and if there are they might be binary data.)
+     Then split each of the first two words (which will contain only
+     ASCII printing characters) on comma.  Take the initial items:
 
         v1    Protocol version indicator - literal.  If something else,
-              fail (installation is incompatible somehow).
+              fail (means installation is incompatible somehow).
 
         SECS.NSECS
-              timestamp before script started running, as a decimal
-              time_t.  NSECS is exactly 9 digits.
-              To be used for auto reloading.
+              timestamp just before script started running, as a
+              decimal time_t.  NSECS is exactly 9 digits.
+              To be used for auto reloading (see below).
 
-     These items are file descriptors:
+     The 2nd word's items are file descriptors:
 
         LISTEN   listening socket                 nonblocking
         CALL     call socket for initial call     blocking
@@ -279,7 +280,7 @@
 
      1. Read and understand the PREFORK_INTERP env var.
         If it is not set, initialisation complete should simply return.
-        This allows simple synchronous operation.
+        (This allows simple synchronous operation.)
 
      2. Open syslog
      3. fork/exit (fork and have parent exit) (to make server)
@@ -340,10 +341,18 @@
       13. send SIGINT to the entire process group
       14. wait, blocking, for the executor child
       15. write the wait status, in 32-bit big-endian, to CALL
-          (this may generate SIGPIPE/EPIPE;
-          if so, die with SIGPIPE or exit 0; do treat that as failure)
+          (this may generate SIGPIPE/EPIPE; if so, die with SIGPIPE
+          or exit 0; do treat SIGPIPE/EPIPE as failure)
       16. exit 0
 
+     Errors detected in the service monitor should be sent to
+     syslog, or stderr, depending on whether this is the initial
+     service monitor (from part 3 step 5) or an accepted socket
+     service monitor (from part 4 step 9); this can be achieved
+     easily by having a global flag (set at part 3 step 6),
+     or perhaps using logger(8) and redirecting stderr (but
+     then be careful to ensure everyone gets only the necessary fds).
+
 ***************************************************************************
 \f
 */