From 2d0e823aa9f574fa0291f716c8a7e45bafe464d3 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Wed, 3 Jul 2019 15:50:50 +0000
Subject:  Update doc to reflect the removal of s6-fdholder-*c programs

---
 doc/s6-fdholder-getdump.html | 64 ++++++++++++++++++++++++++++++--------------
 1 file changed, 44 insertions(+), 20 deletions(-)

(limited to 'doc/s6-fdholder-getdump.html')

diff --git a/doc/s6-fdholder-getdump.html b/doc/s6-fdholder-getdump.html
index d715cf6..46bb2b6 100644
--- a/doc/s6-fdholder-getdump.html
+++ b/doc/s6-fdholder-getdump.html
@@ -34,16 +34,13 @@ environment.
 </pre>
 
 <ul>
- <li> s6-fdholder-getdump executes into <tt><a href="s6-ipcclient.html">s6-ipcclient</a> <em>path</em>
-<a href="s6-fdholder-getdumpc.html">s6-fdholder-getdumpc</a> <em>prog...</em></tt>.
-It does nothing else: it is just a convenience program.
-The <a href="s6-ipcclient.html">s6-ipcclient</a> program connects
-to a Unix socket at <em>path</em>, and the
-<a href="s6-fdholder-getdumpc.html">s6-fdholder-getdumpc</a> program
-gets the server's state over the socket. </li>
- <li> It executes into <em>prog...</em> with as many more open
-file descriptors as there were in the daemon, and information about those
-file descriptors in the environment. </li>
+ <li> <tt>s6-fdholder-getdump</tt> connects to a
+<a href="s6-fdholderd.html">s6-fdholderd</a> server process listening on
+<em>path</em>. </li>
+ <li> It retrieves a copy of the whole set of file descriptors
+stored in that daemon, including their identifiers and expiration dates. </li>
+ <li> It then executes into <em>prog...</em> with the additional open descriptors
+and the additional environment variables. </li>
 </ul>
 
 <h2> Options </h2>
@@ -56,6 +53,43 @@ only here to protect users against programming errors (connecting to the
 wrong socket, for instance). </li>
 </ul>
 
+<h2> Exit codes </h2>
+
+<ul>
+ <li> On success, the program doesn't exit; instead, it execs into <em>prog...</em>. </li>
+ <li> 1: the server denied the operation. The meaning of the error messages
+is explained <a href="s6-fdholder-errorcodes.html">here</a>. </li>
+ <li> 100: wrong usage. </li>
+ <li> 111: system call failed - that includes attempting to connect to a
+nonexistent socket, or one where no <a href="s6-fdholderd.html">s6-fdholderd</a>
+daemon is listening. </li>
+</ul>
+
+<h2> Environment format </h2>
+
+<p>
+ <em>prog...</em> is executed with the following environment variables
+set:
+</p>
+
+<ul>
+ <li> <tt>S6_FD#</tt>&nbsp;: contains the number <em>n</em> of file
+descriptors retrieved from the server. </li>
+ <li> Then, for every <em>i</em> between 0 and <em>n</em>-1 inclusive:
+ <ul>
+  <li> <tt>S6_FD_<em>i</em></tt>&nbsp;: contains the number of the <em>i</em>th
+open file descriptor. </li>
+  <li> <tt>S6_FDID_<em>i</em></tt>&nbsp;: contains the identifier of the
+<em>i</em>th open file descriptor. </li>
+  <li> <tt>S6_FDLIMIT_<em>i</em></tt>&nbsp;: contains the expiration date of
+the <em>i</em>th open file descriptor, if applicable. That date is stored in
+<a href="http://cr.yp.to/libtai/tai64.html#tai64n">external TAI64N
+format</a>. </li>
+If the file descriptor is not supposed to expire, that environment variable
+is not defined. </li>
+ </ul> </li>
+</ul>
+
 <h2> Usage example </h2>
 
 <pre>
@@ -73,16 +107,6 @@ program does the same thing more efficiently.
 <h2> Notes </h2>
 
 <ul>
- <li> s6-fdholder-getdump really executes into <tt>s6-ipcclient
-s6-fdholder-getdumpc
-<a href="//skarnet.org/software/execline/fdclose.html">fdclose</a>
-6 fdclose 7 <em>prog...</em></tt>, so that <em>prog...</em> does not
-have a connection with the fd-holding daemon anymore. If you want to
-keep the server connection open for <em>prog...</em>, use
-<tt>s6-ipcclient s6-fdholder-getdumpc</tt> manually. </li>
- <li> The exact format of the environment given to <em>prog...</em>
-is described in the 
-<a href="s6-fdholder-getdumpc.html">s6-fdholder-getdumpc</a> page. </li>
  <li> Getting the whole state of a s6-fdholderd daemon requires specific
 privileges. Make sure you properly
 <a href="s6-fdholderd.html#configuration">configure the s6-fdholderd
-- 
cgit v1.2.3