From dddbfab568d42e443f102d35c84432824cc59fee Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Wed, 22 Mar 2017 21:37:30 +0000
Subject:  Fix case where s6-tls[cd] would sometimes not detect an application
 and remain there forever with its zombie, both condemned to err in limbo for
 all eternity, the living and the dead, hand in hand

---
 doc/libstls/index.html | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

(limited to 'doc/libstls/index.html')

diff --git a/doc/libstls/index.html b/doc/libstls/index.html
index 4c6819b..8b30b20 100644
--- a/doc/libstls/index.html
+++ b/doc/libstls/index.html
@@ -54,23 +54,28 @@ sysdeps directory. </li>
 
 <h3> Running the TLS/SSL engine </h3>
 
-<h4> <code> int stls_run (struct tls *ctx, int *fds, unsigned int verbosity, uint32_t options, tain_t const *tto) </code> </h4>
+<h4> <code> int stls_run (struct tls *ctx, int *fds, pid_t pid, unsigned int verbosity, uint32_t options, tain_t const *tto) </code> </h4>
 
 <p>
  This function runs a full-duplex TLS/SSL engine, reading/writing
 clear text from/to two file descriptors, and writing/reading
 ciphertext to/from two other file descriptors, until the
 connection is closed both ways (either with a SSL close, or
-with EOF).
+with EOF) or a given subprocess dies.
 </p>
 
 <ul>
  <li> <em>ctx</em> is a pointer to a fully initialized context,
 connected to <em>fds</em>[2] and <em>fds</em>[3]. The TLS
 handshake must already be completed. </li>
- <li> <em>fds</em> is an array of 4 file descriptors, in this
+ <li> <em>fds</em> is an array of 5 file descriptors, in this
 order: fd reading clear text, fd writing clear text, fd reading
-ciphertext, fd writing ciphertext. </li>
+ciphertext, fd writing ciphertext, selfpipe. </li>
+ <li> <em>pid</em> is the pid of the application subprocess.
+When a SIGCHLD is detected on the selfpipe, the newly deceased
+process is reaped, and if it was <em>pid</em>, then the function
+returns as soon as it doesn't have anything left to write to
+the network peer. </li>
  <li> <em>verbosity</em> defines the engine's verbosity: the
 higher the more verbose. This parameter is currently ignored. </li>
  <li> <em>options</em> is a bitfield.
@@ -101,10 +106,13 @@ if you don't want the engine to ever timeout. </li>
 
 <p>
  <tt>stls_run</tt> will make the process die with an appropriate error
-message if it encounters an error. If there were no problems and the
-SSL/TLS connection closed cleanly, it returns 0. All four descriptors
-in <em>fds</em> are closed when <tt>stls_run</tt> returns, but the
-caller should still free <em>ctx</em> itself.
+message if it encounters an unrecoverable error. If there were no problems and the
+SSL/TLS connection closed cleanly, it returns -1. If the application
+subprocess dies early, <tt>stls_run</tt> returns the <em>wstat</em>
+for that subprocess, i.e. the integer containing the information about
+its exit code or crash signal. No matter how <tt>stls_run</tt> returns,
+the first four descriptors in <em>fds</em> are closed, but the
+selfpipe is untouched and the caller should free <em>ctx</em> itself.
 </p>
 
 <h4> <code> int stls_s6tlsc (char const *const *argv, char const *const *envp, tain_t const *tto, uint32_t preoptions, uint32_t options, uid_t uid, gid_t gid, unsigned int verbosity, char const *servername, int *sfd) </code> </h4>
-- 
cgit v1.2.3