diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/libs6/s6-fdholder.html | 3 | ||||
| -rw-r--r-- | doc/s6-fdholder-delete.html | 35 | ||||
| -rw-r--r-- | doc/s6-fdholder-deletec.html | 64 | ||||
| -rw-r--r-- | doc/s6-fdholder-getdump.html | 64 | ||||
| -rw-r--r-- | doc/s6-fdholder-getdumpc.html | 96 | ||||
| -rw-r--r-- | doc/s6-fdholder-list.html | 25 | ||||
| -rw-r--r-- | doc/s6-fdholder-listc.html | 69 | ||||
| -rw-r--r-- | doc/s6-fdholder-retrieve.html | 41 | ||||
| -rw-r--r-- | doc/s6-fdholder-retrievec.html | 69 | ||||
| -rw-r--r-- | doc/s6-fdholder-setdump.html | 30 | ||||
| -rw-r--r-- | doc/s6-fdholder-setdumpc.html | 67 | ||||
| -rw-r--r-- | doc/s6-fdholder-store.html | 32 | ||||
| -rw-r--r-- | doc/s6-fdholder-storec.html | 69 | ||||
| -rw-r--r-- | doc/s6-fdholder-transferdump.html | 47 | ||||
| -rw-r--r-- | doc/s6-fdholder-transferdumpc.html | 84 | ||||
| -rw-r--r-- | doc/s6-fdholderd.html | 16 | ||||
| -rw-r--r-- | doc/upgrade.html | 2 |
17 files changed, 188 insertions, 625 deletions
diff --git a/doc/libs6/s6-fdholder.html b/doc/libs6/s6-fdholder.html index 0a2413b..6aabe39 100644 --- 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 index 7809ca2..89e29c7 100644 --- 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 deleted file mode 100644 index 3bc5a8a..0000000 --- a/doc/s6-fdholder-deletec.html +++ /dev/null @@ -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 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> : 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 deleted file mode 100644 index b2666f5..0000000 --- a/doc/s6-fdholder-getdumpc.html +++ /dev/null @@ -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 index d4c2f34..feea993 100644 --- 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 deleted file mode 100644 index 981a8d7..0000000 --- a/doc/s6-fdholder-listc.html +++ /dev/null @@ -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 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> diff --git a/doc/s6-fdholder-retrievec.html b/doc/s6-fdholder-retrievec.html deleted file mode 100644 index cd49b1b..0000000 --- a/doc/s6-fdholder-retrievec.html +++ /dev/null @@ -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 index 2baafd0..f5c30e9 100644 --- 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 deleted file mode 100644 index 2f65595..0000000 --- a/doc/s6-fdholder-setdumpc.html +++ /dev/null @@ -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 index 9a115f3..d0c3197 100644 --- 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 deleted file mode 100644 index d1ad564..0000000 --- a/doc/s6-fdholder-storec.html +++ /dev/null @@ -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 index 24ecd77..da74069 100644 --- 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 deleted file mode 100644 index 3f1cc22..0000000 --- a/doc/s6-fdholder-transferdumpc.html +++ /dev/null @@ -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 index 2c7e0d3..171b1c7 100644 --- 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 index c1aabc6..68f21ae 100644 --- 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> |