commit 2d0e823aa9f574fa0291f716c8a7e45bafe464d3
parent 1d69f26f58e72ceaab5aeda7df874faf7b46a5f3
Author: Laurent Bercot <ska-skaware@skarnet.org>
Date: Wed, 3 Jul 2019 15:50:50 +0000
Update doc to reflect the removal of s6-fdholder-*c programs
Diffstat:
17 files changed, 188 insertions(+), 625 deletions(-)
diff --git a/doc/libs6/s6-fdholder.html b/doc/libs6/s6-fdholder.html
@@ -35,11 +35,10 @@ exact function prototypes.
<h3> A programming example </h3>
<p>
- The <tt>src/fdholder/s6-fdholder-*c.c</tt> files in the s6 package,
+ The <tt>src/fdholder/s6-fdholder-*.c</tt> files in the s6 package,
for instance, illustrate how to use the s6-fdholder library.
</p>
-
<h3> Synchronous functions with a specified maximum execution time </h3>
<p>
diff --git a/doc/s6-fdholder-delete.html b/doc/s6-fdholder-delete.html
@@ -32,18 +32,11 @@ daemon storage.
</pre>
<ul>
- <li> s6-fdholder-delete executes into <tt><a href="s6-ipcclient.html">s6-ipcclient</a> <em>path</em>
-<a href="s6-fdholder-deletec.html">s6-fdholder-deletec</a> <em>id</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-deletec.html">s6-fdholder-deletec</a> program
-sends instruction to the server. </li>
- <li> It should be used to connect to a
-<a href="s6-fdholderd.html">s6-fdholderd</a> daemon, which will receive
-the instruction to close and remove the file descriptor identified
-by <em>id</em>. </li>
- <li> It then exits 0. </li>
+ <li> <tt>s6-fdholder-delete</tt> connects to a
+<a href="s6-fdholderd.html">s6-fdholderd</a> server process listening on
+<em>path</em>. </li>
+ <li> It tells the server to close the file descriptor that has been
+stored with identifier <em>id</em>. </li>
</ul>
<h2> Options </h2>
@@ -56,6 +49,18 @@ only here to protect users against programming errors (connecting to the
wrong socket, for instance). </li>
</ul>
+<h2> Exit codes </h2>
+
+<ul>
+ <li> 0: success. </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> Usage example </h2>
<pre>
@@ -63,9 +68,9 @@ wrong socket, for instance). </li>
</pre>
<p>
- will tell a
-s6-fdholderd daemon listening on the <tt>/service/fdholderd/s</tt>
-socket to close the filedescriptor identified as MYSOCKET.
+will tell a s6-fdholderd daemon listening on the
+<tt>/service/fdholderd/s</tt> socket to close the file descriptor
+dentified as MYSOCKET.
</p>
</body>
diff --git a/doc/s6-fdholder-deletec.html b/doc/s6-fdholder-deletec.html
@@ -1,64 +0,0 @@
-<html>
- <head>
- <meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
- <meta http-equiv="Content-Language" content="en" />
- <title>s6: the s6-fdholder-deletec program</title>
- <meta name="Description" content="s6: the s6-fdholder-deletec program" />
- <meta name="Keywords" content="s6 s6-fdholder fd-holding fd-holder fd delete deletion unix socket activation" />
- <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
- </head>
-<body>
-
-<p>
-<a href="index.html">s6</a><br />
-<a href="//skarnet.org/software/">Software</a><br />
-<a href="//skarnet.org/">skarnet.org</a>
-</p>
-
-<h1> The <tt>s6-fdholder-deletec</tt> program </h1>
-
-<p>
-<tt>s6-fdholder-deletec</tt> talks to a
-<a href="s6-fdholderd.html">fd-holding daemon</a> on its open
-descriptors 6 and 7, and tells it to close a file descriptor
-it's currently holding.
-</p>
-
-<h2> Interface </h2>
-
-<pre>
- s6-fdholder-deletec [ -t <em>timeout</em> ] <em>id</em>
-</pre>
-
-<ul>
- <li> s6-fdholder-deletec expects to talk to a listening
-<a href="s6-fdholderd.html">s6-fdholderd</a> program on its descriptors 6 and 7. </li>
- <li> It tells the server to close the file descriptor that has been
-stored with identifier <em>id</em>. </li>
- <li> It then exits 0, or 1 if the server returned an error. </li>
-</ul>
-
-<h2> Options </h2>
-
-<ul>
-<li> <tt>-t <em>timeout</em></tt> : if the operation cannot be
-processed in <em>timeout</em> milliseconds, then fail with an error message.
-Communications with the server should be near-instant, so this option is
-only here to protect users against programming errors. </li>
-</ul>
-
-<h2> Notes </h2>
-
-<ul>
- <li>s6-fdholder-deletec is the "internal" version of
-<a href="s6-fdholder-delete.html">s6-fdholder-delete</a>. It simply
-expects to be run as a UCSPI client, i.e. talking to the server
-over descriptors 6 and 7, instead of connecting to the server
-itself. </li>
- <li> The error messages for the s6-fdholder suite are explained
-<a href="s6-fdholder-errorcodes.html">here</a>. </li>
-</ul>
-
-</body>
-</html>
diff --git 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> : 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> : contains the number of the <em>i</em>th
+open file descriptor. </li>
+ <li> <tt>S6_FDID_<em>i</em></tt> : contains the identifier of the
+<em>i</em>th open file descriptor. </li>
+ <li> <tt>S6_FDLIMIT_<em>i</em></tt> : 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
diff --git a/doc/s6-fdholder-getdumpc.html b/doc/s6-fdholder-getdumpc.html
@@ -1,96 +0,0 @@
-<html>
- <head>
- <meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
- <meta http-equiv="Content-Language" content="en" />
- <title>s6: the s6-fdholder-getdumpc program</title>
- <meta name="Description" content="s6: the s6-fdholder-getdumpc program" />
- <meta name="Keywords" content="s6 s6-fdholder fd-holding fd-holder fd retrieval unix socket activation" />
- <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
- </head>
-<body>
-
-<p>
-<a href="index.html">s6</a><br />
-<a href="//skarnet.org/software/">Software</a><br />
-<a href="//skarnet.org/">skarnet.org</a>
-</p>
-
-<h1> The <tt>s6-fdholder-getdumpc</tt> program </h1>
-
-<p>
-<tt>s6-fdholder-getdumpc</tt> talks to a
-<a href="s6-fdholderd.html">fd-holding daemon</a> on its open
-descriptors 6 and 7, and retrieves its whole state,
-then executes a program with as many more file descriptors open
-as were given by the daemon, plus a modified environment to
-describe the retrieved state.
-</p>
-
-<h2> Interface </h2>
-
-<pre>
- s6-fdholder-getdumpc [ -t <em>timeout</em> ] <em>prog...</em>
-</pre>
-
-<ul>
- <li> s6-fdholder-getdumpc expects to talk to a listening
-<a href="s6-fdholderd.html">s6-fdholderd</a> program on its descriptors 6 and 7. </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 descriptors
-and environment. </li>
-</ul>
-
-<h2> Options </h2>
-
-<ul>
- <li> <tt>-t <em>timeout</em></tt> : if the operation cannot be
-processed in <em>timeout</em> milliseconds, then fail with an error message.
-Communications with the server should be near-instant, so this option is
-only here to protect users against programming errors. </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> : 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> : contains the number of the <em>i</em>th
-open file descriptor. </li>
- <li> <tt>S6_FDID_<em>i</em></tt> : contains the identifier of the
-<em>i</em>th open file descriptor. </li>
- <li> <tt>S6_FDLIMIT_<em>i</em></tt> : 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> Notes </h2>
-
-<ul>
- <li> s6-fdholder-getdumpc is the "internal" version of
-<a href="s6-fdholder-getdump.html">s6-fdholder-getdump</a>. It simply
-expects to be run as a UCSPI client, i.e. talking to the server
-over descriptors 6 and 7, instead of connecting to the server
-itself. </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
-access rights</a> so your client can perform that operation. </li>
- <li> The error messages for the s6-fdholder suite are explained
-<a href="s6-fdholder-errorcodes.html">here</a>. </li>
-</ul>
-
-</body>
-</html>
diff --git a/doc/s6-fdholder-list.html b/doc/s6-fdholder-list.html
@@ -30,23 +30,34 @@
</pre>
<ul>
- <li> s6-fdholder-list executes into <tt><a href="s6-ipcclient.html">s6-ipcclient</a> <em>path</em>
-<a href="s6-fdholder-listc.html">s6-fdholder-listc</a> <em>id</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-listc.html">s6-fdholder-listc</a> program transmits
-the instruction over the socket, and gets and prints the result. </li>
+ <li> <tt>s6-fdholder-list</tt> connects to a
+<a href="s6-fdholderd.html">s6-fdholderd</a> server process listening on
+<em>path</em>. </li>
+ <li> It gets the list of identifiers corresponding to the currently held
+file descriptors. It prints that list to stdout, one per line. </li>
</ul>
<h2> Options </h2>
<ul>
-<li> <tt>-t <em>timeout</em></tt> : if the operation cannot be
+ <li> <tt>-t <em>timeout</em></tt> : if the operation cannot be
processed in <em>timeout</em> milliseconds, then fail with an error message.
Communications with the server should be near-instant, so this option is
only here to protect users against programming errors (connecting to the
wrong socket, for instance). </li>
</ul>
+<h2> Exit codes </h2>
+
+<ul>
+ <li> 0: success. </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>
+
</body>
</html>
diff --git a/doc/s6-fdholder-listc.html b/doc/s6-fdholder-listc.html
@@ -1,69 +0,0 @@
-<html>
- <head>
- <meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
- <meta http-equiv="Content-Language" content="en" />
- <title>s6: the s6-fdholder-listc program</title>
- <meta name="Description" content="s6: the s6-fdholder-listc program" />
- <meta name="Keywords" content="s6 s6-fdholder fd-holding fd-holder fd list unix socket activation" />
- <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
- </head>
-<body>
-
-<p>
-<a href="index.html">s6</a><br />
-<a href="//skarnet.org/software/">Software</a><br />
-<a href="//skarnet.org/">skarnet.org</a>
-</p>
-
-<h1> The <tt>s6-fdholder-listc</tt> program </h1>
-
-<p>
-<tt>s6-fdholder-listc</tt> talks to a
-<a href="s6-fdholderd.html">fd-holding daemon</a> on its open
-descriptors 6 and 7. It prints on stdout the list of identifiers
-of all the fd currently held by the daemon, one per line.
-</p>
-
-<h2> Interface </h2>
-
-<pre>
- s6-fdholder-listc [ -t <em>timeout</em> ]
-</pre>
-
-<ul>
- <li> s6-fdholder-listc expects to talk to a listening
-<a href="s6-fdholderd.html">s6-fdholderd</a> program on its descriptors 6 and 7. </li>
- <li> It gets the list of identifiers corresponding to the currently held
-file descriptors. It prints that list to stdout, one per line.
- <li> It then exits 0, or 1 if the server returned an error. </li>
-</ul>
-
-<h2> Options </h2>
-
-<ul>
-<li> <tt>-t <em>timeout</em></tt> : if the operation cannot be
-processed in <em>timeout</em> milliseconds, then fail with an error message.
-Communications with the server should be near-instant, so this option is
-only here to protect users against programming errors. </li>
-</ul>
-
-<h2> Notes </h2>
-
-<ul>
- <li>s6-fdholder-listc is the "internal" version of
-<a href="s6-fdholder-list.html">s6-fdholder-list</a>. It simply
-expects to be run as a UCSPI client, i.e. talking to the server
-over descriptors 6 and 7, instead of connecting to the server
-itself. </li>
- <li> The error messages for the s6-fdholder suite are explained
-<a href="s6-fdholder-errorcodes.html">here</a>. </li>
- <li> The list of identifiers is printed one per line; special
-characters - such as newline - are quoted. The output can be
-unquoted, for instance, by
-<tt><a href="//skarnet.org/software/s6-portable-utils/s6-unquote-filter.html">s6-unquote-filter</a>
--d ""</tt>. </li>
-</ul>
-
-</body>
-</html>
diff --git a/doc/s6-fdholder-retrieve.html b/doc/s6-fdholder-retrieve.html
@@ -33,18 +33,13 @@ program's standard input.
</pre>
<ul>
- <li> s6-fdholder-retrieve executes into <tt><a href="s6-ipcclient.html">s6-ipcclient</a> <em>path</em>
-<a href="s6-fdholder-retrievec.html">s6-fdholder-retrievec</a> <em>id</em> <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-retrievec.html">s6-fdholder-retrievec</a> program
-gets the file descriptor identified by <em>id</em> over the socket. </li>
- <li> It should be used to connect to a
-<a href="s6-fdholderd.html">s6-fdholderd</a> daemon, which will pass the
-file descriptor to the client over the <em>path</em> socket. </li>
- <li> It executes into <em>prog...</em> with the retrieved file
-descriptor as <em>prog...</em>'s standard input. </li>
+ <li> <tt>s6-fdholder-retrieve</tt> connects to a
+<a href="s6-fdholderd.html">s6-fdholderd</a> server process listening on
+<em>path</em>. </li>
+ <li> It attempts to retrieve a copy of the file descriptor that has been
+stored into that daemon under identifier <em>id</em>.
+ <li> It then executes into <em>prog...</em>, with the retrieved
+file descriptor as standard input. </li>
</ul>
<h2> Options </h2>
@@ -61,6 +56,18 @@ 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> Usage example </h2>
<pre>
@@ -80,19 +87,11 @@ connection.
<h2> Notes </h2>
<ul>
- <li> s6-fdholder-retrieve really executes into <tt>s6-ipcclient
-s6-fdholder-retrievec
-<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-retrievec</tt> manually. </li>
<li> To execute <em>prog</em> with the newly retrieved file descriptor
as number <em>n</em> while preserving stdin, use the following construct:
<tt>fdmove <em>n</em> 0 s6-fdholder-retrieve <em>path</em> <em>id</em>
<a href="//skarnet.org/software/execline/fdswap.html">fdswap</a>
-0 <em>n</em> <em>prog...</em></tt>. Be aware that <em>n</em>
-cannot be 6 or 7, internally used by s6-fdholder-retrieve. </li>
+0 <em>n</em> <em>prog...</em></tt>. </li>
</ul>
</body>
diff --git a/doc/s6-fdholder-retrievec.html b/doc/s6-fdholder-retrievec.html
@@ -1,69 +0,0 @@
-<html>
- <head>
- <meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
- <meta http-equiv="Content-Language" content="en" />
- <title>s6: the s6-fdholder-retrievec program</title>
- <meta name="Description" content="s6: the s6-fdholder-retrievec program" />
- <meta name="Keywords" content="s6 s6-fdholder fd-holding fd-holder fd retrieval unix socket activation" />
- <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
- </head>
-<body>
-
-<p>
-<a href="index.html">s6</a><br />
-<a href="//skarnet.org/software/">Software</a><br />
-<a href="//skarnet.org/">skarnet.org</a>
-</p>
-
-<h1> The <tt>s6-fdholder-retrievec</tt> program </h1>
-
-<p>
-<tt>s6-fdholder-retrievec</tt> talks to a
-<a href="s6-fdholderd.html">fd-holding daemon</a> on its open
-descriptors 6 and 7, and retrieves a file descriptor from it,
-then executes a program.
-</p>
-
-<h2> Interface </h2>
-
-<pre>
- s6-fdholder-retrievec [ -D ] [ -t <em>timeout</em> ] <em>id</em> <em>prog...</em>
-</pre>
-
-<ul>
- <li> s6-fdholder-retrievec expects to talk to a listening
-<a href="s6-fdholderd.html">s6-fdholderd</a> program on its descriptors 6 and 7. </li>
- <li> It attempts to retrieve a copy of the file descriptor that has been
-stored into that daemon under identifier <em>id</em>.
- <li> It then executes into <em>prog...</em>, with the retrieved
-file descriptor as standard input. </li>
-</ul>
-
-<h2> Options </h2>
-
-<ul>
- <li> <tt>-D</tt> : delete the file descriptor from the server's
-storage after retrieval. This option requires writing rights over the
-given identifier as well as reading rights: check the server's
-<a href="s6-fdholderd.html#configuration">configuration</a>. </li>
- <li> <tt>-t <em>timeout</em></tt> : if the operation cannot be
-processed in <em>timeout</em> milliseconds, then fail with an error message.
-Communications with the server should be near-instant, so this option is
-only here to protect users against programming errors. </li>
-</ul>
-
-<h2> Notes </h2>
-
-<ul>
- <li>s6-fdholder-retrievec is the "internal" version of
-<a href="s6-fdholder-retrieve.html">s6-fdholder-retrieve</a>. It simply
-expects to be run as a UCSPI client, i.e. talking to the server
-over descriptors 6 and 7, instead of connecting to the server
-itself. </li>
- <li> The error messages for the s6-fdholder suite are explained
-<a href="s6-fdholder-errorcodes.html">here</a>. </li>
-</ul>
-
-</body>
-</html>
diff --git a/doc/s6-fdholder-setdump.html b/doc/s6-fdholder-setdump.html
@@ -32,15 +32,11 @@ that daemon.
</pre>
<ul>
- <li> s6-fdholder-setdump executes into <tt><a href="s6-ipcclient.html">s6-ipcclient</a> <em>path</em>
-<a href="s6-fdholder-setdumpc.html">s6-fdholder-setdumpc</a> <em>id</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-setdumpc.html">s6-fdholder-setdumpc</a> program transmits the
-file descriptors over the socket. </li>
- <li> It should be used to connect to a
-<a href="s6-fdholderd.html">s6-fdholderd</a> daemon, which will store the set of
-file descriptors. </li>
+ <li> <tt>s6-fdholder-setdump</tt> connects to a
+<a href="s6-fdholderd.html">s6-fdholderd</a> server process listening on
+<em>path</em>. </li>
+ <li> It attempts to pass a complete state - i.e. a set of file descriptors
+with identifiers and expiration dates - to the server. </li>
</ul>
<h2> Options </h2>
@@ -53,14 +49,26 @@ only here to protect users against programming errors (connecting to the
wrong socket, for instance). </li>
</ul>
+<h2> Exit codes </h2>
+
+<ul>
+ <li> 0: success. </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> Notes </h2>
<ul>
<li> The file descriptors to transmit to the server should of course be
-already open in the s6-fdholder-setdump program; also, s6-fdholder-setdump
+already open in the <tt>s6-fdholder-setdump</tt> program; also, <tt>s6-fdholder-setdump</tt>
should have certain environment variables that describe that set of file
descriptors. The format of the environment is the same as the one set by
-<a href="s6-fdholder-getdumpc.html">s6-fdholder-getdumpc</a>. </li>
+<a href="s6-fdholder-getdump.html">s6-fdholder-getdump</a>. </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
diff --git a/doc/s6-fdholder-setdumpc.html b/doc/s6-fdholder-setdumpc.html
@@ -1,67 +0,0 @@
-<html>
- <head>
- <meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
- <meta http-equiv="Content-Language" content="en" />
- <title>s6: the s6-fdholder-setdumpc program</title>
- <meta name="Description" content="s6: the s6-fdholder-setdumpc program" />
- <meta name="Keywords" content="s6 s6-fdholder fd-holding fd-holder fd dump storage unix socket activation" />
- <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
- </head>
-<body>
-
-<p>
-<a href="index.html">s6</a><br />
-<a href="//skarnet.org/software/">Software</a><br />
-<a href="//skarnet.org/">skarnet.org</a>
-</p>
-
-<h1> The <tt>s6-fdholder-setdumpc</tt> program </h1>
-
-<p>
-<tt>s6-fdholder-setdumpc</tt> talks to a
-<a href="s6-fdholderd.html">fd-holding daemon</a> on its open
-descriptors 6 and 7, and transmits it a set of file descriptors
-together with a list of identifiers and expiration dates found
-in its environment.
-</p>
-
-<h2> Interface </h2>
-
-<pre>
- s6-fdholder-setdumpc [ -t <em>timeout</em> ]
-</pre>
-
-<ul>
- <li> s6-fdholder-setdumpc expects to talk to a listening
-<a href="s6-fdholderd.html">s6-fdholderd</a> program on its descriptors 6 and 7. </li>
- <li> It attempts to pass a complete state - i.e. a set of file descriptors
-with identifiers and expiration dates - to s6-fdholderd. </li>
- <li> It then exits 0, or 1 if the server returned an error. </li>
-</ul>
-
-<h2> Options </h2>
-
-<ul>
-<li> <tt>-t <em>timeout</em></tt> : if the operation cannot be
-processed in <em>timeout</em> milliseconds, then fail with an error message.
-Communications with the server should be near-instant, so this option is
-only here to protect users against programming errors. </li>
-</ul>
-
-<h2> Notes </h2>
-
-<ul>
- <li> The error messages for the s6-fdholder suite are explained
-<a href="s6-fdholder-errorcodes.html">here</a>. </li>
- <li> The format of the environment variables where s6-fdholder-setdumpc
-gets its information from is the same as the one set by
-<a href="s6-fdholder-getdumpc.html">s6-fdholder-getdumpc</a>. </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
-access rights</a> so your client can perform that operation. </li>
-</ul>
-
-</body>
-</html>
diff --git a/doc/s6-fdholder-store.html b/doc/s6-fdholder-store.html
@@ -32,36 +32,42 @@ descriptors for the daemon to hold.
</pre>
<ul>
- <li> s6-fdholder-store executes into <tt><a href="s6-ipcclient.html">s6-ipcclient</a> <em>path</em>
-<a href="s6-fdholder-storec.html">s6-fdholder-storec</a> <em>id</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-storec.html">s6-fdholder-storec</a> program transmits the desired
-file descriptor over the socket. </li>
- <li> It should be used to connect to a
-<a href="s6-fdholderd.html">s6-fdholderd</a> daemon, which will store the
-file descriptor given by the user. </li>
+ <li> <tt>s6-fdholder-store</tt> connects to a
+<a href="s6-fdholderd.html">s6-fdholderd</a> server process listening on
+<em>path</em>. </li>
+ <li> It attempts to pass a copy of its standard input, or of its descriptor
+<em>fd</em>, to the server, with identifier <em>id</em>. </li>
</ul>
<h2> Options </h2>
<ul>
<li> <tt>-d <em>fd</em></tt> : store descriptor number <em>fd</em>.
-By default, <em>fd</em> is 0 (i.e. the program's stdin will be stored).
-s6-fdholder-store replaces its stdin with <em>fd</em> before executing into
-<tt>s6-ipcclient <a href="s6-fdholder-storec.html">s6-fdholder-storec</a></tt>. </li>
+By default, <em>fd</em> is 0 (i.e. the program's stdin will be stored). </li>
<li> <tt>-T <em>fdtimeout</em></tt> : the descriptor is stored with
an expiration time of <em>fdtimeout</em> milliseconds, which means the
<a href="s6-fdholderd.html">s6-fdholderd</a> daemon will close and get rid of
the descriptor after that time. By default, <em>fdtimeout</em> is 0, which
means infinite - no expiration time. </li>
-<li> <tt>-t <em>timeout</em></tt> : if the operation cannot be
+ <li> <tt>-t <em>timeout</em></tt> : if the operation cannot be
processed in <em>timeout</em> milliseconds, then fail with an error message.
Communications with the server should be near-instant, so this option is
only here to protect users against programming errors (connecting to the
wrong socket, for instance). </li>
</ul>
+<h2> Exit codes </h2>
+
+<ul>
+ <li> 0: success. </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> Usage example </h2>
<pre>
diff --git a/doc/s6-fdholder-storec.html b/doc/s6-fdholder-storec.html
@@ -1,69 +0,0 @@
-<html>
- <head>
- <meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
- <meta http-equiv="Content-Language" content="en" />
- <title>s6: the s6-fdholder-storec program</title>
- <meta name="Description" content="s6: the s6-fdholder-storec program" />
- <meta name="Keywords" content="s6 s6-fdholder fd-holding fd-holder fd storage unix socket activation" />
- <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
- </head>
-<body>
-
-<p>
-<a href="index.html">s6</a><br />
-<a href="//skarnet.org/software/">Software</a><br />
-<a href="//skarnet.org/">skarnet.org</a>
-</p>
-
-<h1> The <tt>s6-fdholder-storec</tt> program </h1>
-
-<p>
-<tt>s6-fdholder-storec</tt> talks to a
-<a href="s6-fdholderd.html">fd-holding daemon</a> on its open
-descriptors 6 and 7, and passes it a copy of its standard
-input.
-</p>
-
-<h2> Interface </h2>
-
-<pre>
- s6-fdholder-storec [ -T fdtimeout ] [ -t <em>timeout</em> ] <em>id</em>
-</pre>
-
-<ul>
- <li> s6-fdholder-storec expects to talk to a listening
-<a href="s6-fdholderd.html">s6-fdholderd</a> program on its descriptors 6 and 7. </li>
- <li> It attempts to pass a copy of its fd 0 (standard input) to s6-fdholderd,
-with identifier <em>id</em>. </li>
- <li> It then exits 0, or 1 if the server returned an error. </li>
-</ul>
-
-<h2> Options </h2>
-
-<ul>
- <li> <tt>-T <em>fdtimeout</em></tt> : the descriptor is stored with
-an expiration time of <em>fdtimeout</em> milliseconds, which means the
-<a href="s6-fdholderd.html">s6-fdholderd</a> daemon will close and get rid of
-the descriptor after that time. By default, <em>fdtimeout</em> is 0, which
-means infinite - no expiration time. </li>
-<li> <tt>-t <em>timeout</em></tt> : if the operation cannot be
-processed in <em>timeout</em> milliseconds, then fail with an error message.
-Communications with the server should be near-instant, so this option is
-only here to protect users against programming errors. </li>
-</ul>
-
-<h2> Notes </h2>
-
-<ul>
- <li>s6-fdholder-storec is the "internal" version of
-<a href="s6-fdholder-store.html">s6-fdholder-store</a>. It simply
-expects to be run as a UCSPI client, i.e. talking to the server
-over descriptors 6 and 7, instead of connecting to the server
-itself. </li>
- <li> The error messages for the s6-fdholder suite are explained
-<a href="s6-fdholder-errorcodes.html">here</a>. </li>
-</ul>
-
-</body>
-</html>
diff --git a/doc/s6-fdholder-transferdump.html b/doc/s6-fdholder-transferdump.html
@@ -31,15 +31,16 @@ transfers the content of the first one to the second one.
</pre>
<ul>
- <li> s6-fdholder-transferdump executes into a more complex command line
-involving two
-<a href="s6-ipcclient.html">s6-ipcclient</a> invocations and ending with
-<a href="s6-fdholder-transferdumpc.html">s6-fdholder-transferdumpc</a>. It
-is just a convenience program: the real transfer is performed by
-<a href="s6-fdholder-transferdumpc.html">s6-fdholder-transferdumpc</a>. </li>
- <li> The file descriptor transfer will occur from the
-<a href="s6-fdholderd.html">s6-fdholderd</a> daemon listening on
-<em>pathfrom</em> to the one listening on <em>pathto</em>. </li>
+ <li> <tt>s6-fdholder-transferdump</tt> connects to a
+<a href="s6-fdholderd.html">s6-fdholderd</a> server process listening on
+<em>pathfrom</em> and gets the whole set of file descriptors from
+this server, with their identifiers and (when relevant) expiration
+dates. </li>
+ <li> It then connects to a different instance of
+<a href="s6-fdholderd.html">s6-fdholderd</a>, listening on <em>pathto</em>,
+and stores the set of file descriptors to it. The set is
+<em>added</em> to the second server, which keeps the descriptors
+it was already holding. </li>
</ul>
<h2> Options </h2>
@@ -55,5 +56,33 @@ only here to protect users against programming errors (connecting to the
wrong socket, for instance). </li>
</ul>
+<h2> Exit codes </h2>
+
+<ul>
+ <li> 0: success. </li>
+ <li> 1: the source server denied the operation. The meaning of the error messages
+is explained <a href="s6-fdholder-errorcodes.html">here</a>. </li>
+ <li> 2: the destination 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> Notes </h2>
+
+<ul>
+ <li> Dumping the entire state of <a href="s6-fdholderd.html">s6-fdholderd</a>
+requires special authorizations. Make sure the s6-fdholderd instances are
+<a href="s6-fdholderd.html#configuration">configured</a> to accept
+dump-getting and dump-setting requests from your client. </li>
+ <li> A typical use case of
+<a href="s6-fdholder-transferdump.html">s6-fdholder-transferdump</a> is
+when the main fd-holding daemon needs to upgrade, or restart for some reason.
+Transferring the file descriptors into another, temporary fd-holding daemon
+instance allows it to restart without losing the descriptors. </li>
+</ul>
+
</body>
</html>
diff --git a/doc/s6-fdholder-transferdumpc.html b/doc/s6-fdholder-transferdumpc.html
@@ -1,84 +0,0 @@
-<html>
- <head>
- <meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
- <meta http-equiv="Content-Language" content="en" />
- <title>s6: the s6-fdholder-transferdumpc program</title>
- <meta name="Description" content="s6: the s6-fdholder-transferdumpc program" />
- <meta name="Keywords" content="s6 s6-fdholder fd-holding fd-holder fd dump transfer unix socket activation" />
- <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
- </head>
-<body>
-
-<p>
-<a href="index.html">s6</a><br />
-<a href="//skarnet.org/software/">Software</a><br />
-<a href="//skarnet.org/">skarnet.org</a>
-</p>
-
-<h1> The <tt>s6-fdholder-transferdumpc</tt> program </h1>
-
-<p>
-<tt>s6-fdholder-transferdumpc</tt> talks to two
-<a href="s6-fdholderd.html">fd-holding daemons</a>: the source of the
-transfer on its
-standard input, and the destination of the transfer on its standard output,
-both being
-open Unix domain sockets. It retrieves the entire storage state of
-the source daemon and dumps it into the destination daemon.
-</p>
-
-<h2> Interface </h2>
-
-<pre>
- s6-fdholder-transferdumpc [ -t <em>timeoutfrom</em> ] [ -T timeoutto ]
-</pre>
-
-<ul>
- <li> s6-fdholder-transferdumpc expects to talk to a listening
-<a href="s6-fdholderd.html">s6-fdholderd</a> program on its descriptor 0 and
-to another one on its descriptor 1. </li>
- <li> It gets the entire set of file descriptors from the first
-server, with their identifiers and possibly expiration dates. </li>
- <li> It stores that set into the second server. The set is
-<em>added</em> to the second server, which keeps the descriptors
-it was already holding. </li>
- <li> It then exits 0, or 1 if a server returned an error. </li>
-</ul>
-
-<h2> Options </h2>
-
-<ul>
-<li> <tt>-t <em>timeoutfrom</em></tt> : if the set-retrieving
-operation cannot be processed in <em>timeoutfrom</em> milliseconds, then
-fail with an error message.
-Communications with the server should be near-instant, so this option is
-only here to protect users against programming errors. </li>
-<li> <tt>-T <em>timeoutto</em></tt> : same thing with the
-set-storing operation. </li>
-</ul>
-
-<h2> Notes </h2>
-
-<ul>
- <li> s6-fdholder-transferdumpc is the "internal" version of
-<a href="s6-fdholder-transferdump.html">s6-fdholder-transferdump</a>. It simply
-expects to be run with file descriptors already open to both
-servers; <a href="s6-fdholder-transferdump.html">s6-fdholder-transferdump</a>
-takes care of all the plumbing. </li>
- <li> The error messages for the s6-fdholder suite are explained
-<a href="s6-fdholder-errorcodes.html">here</a>. </li>
- <li> Dumping the entire state of <a href="s6-fdholderd.html">s6-fdholderd</a>
-requires special authorizations. Make sure the s6-fdholderd instances are
-<a href="s6-fdholderd.html#configuration">configured</a> to accept
-dump-getting and dump-setting requests from your client. </li>
- <li> A typical use case of
-<a href="s6-fdholder-transferdump.html">s6-fdholder-transferdump</a> and
-s6-fdholder-transferdumpc is when the main fd-holding daemon needs to
-upgrade, or restart for some reason. Transferring the file descriptors
-into another, temporary fd-holding daemon instance allows it to
-restart without losing the descriptors. </li>
-</ul>
-
-</body>
-</html>
diff --git a/doc/s6-fdholderd.html b/doc/s6-fdholderd.html
@@ -47,13 +47,13 @@ lost; if they need to be preserved, the admin should make sure to
one operation, then disconnect. </li>
<li> Possible operations include:
<ul>
- <li> <a href="s6-fdholder-storec.html">Storing a file descriptor</a> </li>
- <li> <a href="s6-fdholder-retrievec.html">Retrieving a file descriptor</a> </li>
- <li> <a href="s6-fdholder-deletec.html">Deleting a file descriptor</a> </li>
- <li> <a href="s6-fdholder-listc.html">Listing stored file descriptor
+ <li> <a href="s6-fdholder-store.html">Storing a file descriptor</a> </li>
+ <li> <a href="s6-fdholder-retrieve.html">Retrieving a file descriptor</a> </li>
+ <li> <a href="s6-fdholder-delete.html">Deleting a file descriptor</a> </li>
+ <li> <a href="s6-fdholder-list.html">Listing stored file descriptor
identifiers</a> </li>
- <li> <a href="s6-fdholder-getdumpc.html">Getting the whole server state</a> </li>
- <li> <a href="s6-fdholder-setdumpc.html">Setting the whole server state</a>,
+ <li> <a href="s6-fdholder-getdump.html">Getting the whole server state</a> </li>
+ <li> <a href="s6-fdholder-setdump.html">Setting the whole server state</a>,
or more accurately adding a set of file descriptors to the already existing
state </li>
</ul> </li>
@@ -117,12 +117,12 @@ changes in the filesystem are automatically picked up. </li>
<ul>
<li> Every file descriptor is stored in the s6-fdholderd daemon via the
-<a href="s6-fdholder-storec.html">s6-fdholder-storec</a> program, with
+<a href="s6-fdholder-store.html">s6-fdholder-store</a> program, with
an <em>identifier</em>. That identifier is a zero-terminated character
string, containing 1 to 255 characters. </li>
<li> Any non-null character can be used in an identifier. Non-printable or
special characters will be quoted when printed by
-<a href="s6-fdholder-listc.html">s6-fdholder-listc</a>. However, it is
+<a href="s6-fdholder-list.html">s6-fdholder-list</a>. However, it is
recommended to only use reasonable characters in identifiers: clients
should be able to know at a glance what file descriptor is represented by
an identifier. Identifiers have no special meaning to the server. </li>
diff --git a/doc/upgrade.html b/doc/upgrade.html
@@ -362,7 +362,7 @@ dependencies is part of the bugfix.) </li>
<li> New functionality added to <a href="s6-log.html">s6-log</a>. Its
syntax has been extended; some options are now marked as obsolescent. </li>
<li> Access control instated in <a href="s6-fdholderd.html">s6-fdholderd</a>
-for <a href="s6-fdholder-listc.html">listing</a> </li>
+for <a href="s6-fdholder-list.html">listing</a> </li>
</ul>
<h2> in 2.1.0.1 </h2>
