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 de9e0af399a33d554857b8bc73f56d8c40352382..47ad3616a5e46b7bb7c7e546eb96deb9b31b8ae7 100644 (file)
--- a/cprogs/prefork-interp.c
+++ b/cprogs/prefork-interp.c
@@ -259,7 +259,7 @@
      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:
+     ASCII printing characters) on comma.  Take the first two items:
 
         v1    Protocol version indicator - literal.  If something else,
               fail (means installation is incompatible somehow).
@@ -276,6 +276,8 @@
         WATCHE   liveness watcher stderr          nonblocking
         WATCHI   liveness sentinel                unspecified
 
+        (any further descriptors should be ignored, not closed)
+
   3. Library should do the following:
 
      1. Read and understand the PREFORK_INTERP env var.
@@ -290,7 +292,7 @@
         and make a note to send all error messages to syslog
      7. Enter select loop, looking for the following:
 
-         * accept on LISTEN:
+        A. accept on LISTEN:
             i. see if we need to reload: is any file forming part
                of the program newer than the SECS.NSECS ?
                If so, log at LOG_INFO, and exit immediately
@@ -298,12 +300,13 @@
             ii. see if we can reap any children, possibly waiting
                for children if we are at our concurrency limit
                (limit should be configured through library, default 4)
+               Report child exit status if not zero or SIGPIPE.
             iii. fork service (monitor) child, using accepted fd
 
-         * WATCHE is readable:
-            * EOF:: log at LOG_INFO, and exit
-            * data to read: read what is available immediately,
-              log it as a message at LOG_ERR, and exit
+        B. WATCHE is readable:
+            * EOF: log at LOG_INFO, and exit
+            * data to read: read what is available immediately;
+              it will be an error message: log it at LOG_ERR, and exit
 
   4. service (monitor) child does the following:
 
@@ -340,9 +343,7 @@
       12. set SIGINT to ignored
       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 SIGPIPE/EPIPE as failure)
+      15. write the wait status, in 32-bit big-endian, to CAL
       16. exit 0
 
      Errors detected in the service monitor should be sent to
@@ -353,6 +354,10 @@
      or perhaps using logger(8) and redirecting stderr (but
      then be careful to ensure everyone gets only the necessary fds).
 
+     EOF on CALL, or EPIPE/SIGPIPE writing to it, are not errors.
+     In this case, exit zero or die with SIGPIPE, so parent
+     won't report error either (part 3 step 7(A)(ii)).
+
 ***************************************************************************
 \f
 */