summaryrefslogtreecommitdiff
path: root/doc/s6-fdholder-retrieve.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/s6-fdholder-retrieve.html')
-rw-r--r--doc/s6-fdholder-retrieve.html41
1 files changed, 20 insertions, 21 deletions
diff --git a/doc/s6-fdholder-retrieve.html b/doc/s6-fdholder-retrieve.html
index 821a949..a58d64e 100644
--- 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>