From 2d0e823aa9f574fa0291f716c8a7e45bafe464d3 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Wed, 3 Jul 2019 15:50:50 +0000 Subject: Update doc to reflect the removal of s6-fdholder-*c programs --- doc/libs6/s6-fdholder.html | 3 +- doc/s6-fdholder-delete.html | 35 ++++++++------ doc/s6-fdholder-deletec.html | 64 ------------------------- doc/s6-fdholder-getdump.html | 64 +++++++++++++++++-------- doc/s6-fdholder-getdumpc.html | 96 -------------------------------------- doc/s6-fdholder-list.html | 25 +++++++--- doc/s6-fdholder-listc.html | 69 --------------------------- doc/s6-fdholder-retrieve.html | 41 ++++++++-------- doc/s6-fdholder-retrievec.html | 69 --------------------------- doc/s6-fdholder-setdump.html | 30 +++++++----- doc/s6-fdholder-setdumpc.html | 67 -------------------------- doc/s6-fdholder-store.html | 32 +++++++------ doc/s6-fdholder-storec.html | 69 --------------------------- doc/s6-fdholder-transferdump.html | 47 +++++++++++++++---- doc/s6-fdholder-transferdumpc.html | 84 --------------------------------- doc/s6-fdholderd.html | 16 +++---- doc/upgrade.html | 2 +- 17 files changed, 188 insertions(+), 625 deletions(-) delete mode 100644 doc/s6-fdholder-deletec.html delete mode 100644 doc/s6-fdholder-getdumpc.html delete mode 100644 doc/s6-fdholder-listc.html delete mode 100644 doc/s6-fdholder-retrievec.html delete mode 100644 doc/s6-fdholder-setdumpc.html delete mode 100644 doc/s6-fdholder-storec.html delete mode 100644 doc/s6-fdholder-transferdumpc.html 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.

A programming example

- The src/fdholder/s6-fdholder-*c.c files in the s6 package, + The src/fdholder/s6-fdholder-*.c files in the s6 package, for instance, illustrate how to use the s6-fdholder library.

Synchronous functions with a specified maximum execution time

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.

s6-fdholder-delete executes into s6-ipcclient path -s6-fdholder-deletec id. -It does nothing else: it is just a convenience program. -The s6-ipcclient program connects -to a Unix socket at path, and the -s6-fdholder-deletec program -sends instruction to the server.
It should be used to connect to a -s6-fdholderd daemon, which will receive -the instruction to close and remove the file descriptor identified -by id.
It then exits 0.
s6-fdholder-delete connects to a +s6-fdholderd server process listening on +path.
It tells the server to close the file descriptor that has been +stored with identifier id.

Options

@@ -56,6 +49,18 @@ only here to protect users against programming errors (connecting to the wrong socket, for instance). +

Exit codes

+ +

0: success.
1: the server denied the operation. The meaning of the error messages +is explained here.
100: wrong usage.
111: system call failed - that includes attempting to connect to a +nonexistent socket, or one where no s6-fdholderd +daemon is listening.

Usage example

@@ -63,9 +68,9 @@ wrong socket, for instance).

- will tell a -s6-fdholderd daemon listening on the /service/fdholderd/s -socket to close the filedescriptor identified as MYSOCKET. +will tell a s6-fdholderd daemon listening on the +/service/fdholderd/s socket to close the file descriptor +dentified as MYSOCKET.

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 @@ - - - - - - s6: the s6-fdholder-deletec program - - - - - - -

-s6
-Software
-skarnet.org -

- -

The `s6-fdholder-deletec` program

- -

-s6-fdholder-deletec talks to a -fd-holding daemon on its open -descriptors 6 and 7, and tells it to close a file descriptor -it's currently holding. -

- -

Interface

- -

-     s6-fdholder-deletec [ -t timeout ] id
-

- -

s6-fdholder-deletec expects to talk to a listening -s6-fdholderd program on its descriptors 6 and 7.
It tells the server to close the file descriptor that has been -stored with identifier id.
It then exits 0, or 1 if the server returned an error.

- -

Options

- -

-t timeout : if the operation cannot be -processed in timeout 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.

- -

Notes

- -

s6-fdholder-deletec is the "internal" version of -s6-fdholder-delete. 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.
The error messages for the s6-fdholder suite are explained -here.

- - - 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.

s6-fdholder-getdump executes into s6-ipcclient path -s6-fdholder-getdumpc prog.... -It does nothing else: it is just a convenience program. -The s6-ipcclient program connects -to a Unix socket at path, and the -s6-fdholder-getdumpc program -gets the server's state over the socket.
It executes into prog... with as many more open -file descriptors as there were in the daemon, and information about those -file descriptors in the environment.
s6-fdholder-getdump connects to a +s6-fdholderd server process listening on +path.
It retrieves a copy of the whole set of file descriptors +stored in that daemon, including their identifiers and expiration dates.
It then executes into prog... with the additional open descriptors +and the additional environment variables.

Options

@@ -56,6 +53,43 @@ only here to protect users against programming errors (connecting to the wrong socket, for instance). +

Exit codes

+ +

On success, the program doesn't exit; instead, it execs into prog....
1: the server denied the operation. The meaning of the error messages +is explained here.
100: wrong usage.
111: system call failed - that includes attempting to connect to a +nonexistent socket, or one where no s6-fdholderd +daemon is listening.

+ +

Environment format

+ +

+ prog... is executed with the following environment variables +set: +

+ +

S6_FD# : contains the number n of file +descriptors retrieved from the server.
Then, for every i between 0 and n-1 inclusive: +
- S6_FD_i : contains the number of the ith +open file descriptor.
- S6_FDID_i : contains the identifier of the +ith open file descriptor.
- S6_FDLIMIT_i : contains the expiration date of +the ith open file descriptor, if applicable. That date is stored in +external TAI64N +format.

Usage example

@@ -73,16 +107,6 @@ program does the same thing more efficiently.
  Notes 
 
 
-  s6-fdholder-getdump really executes into s6-ipcclient
-s6-fdholder-getdumpc
-fdclose
-6 fdclose 7 prog..., so that prog... does not
-have a connection with the fd-holding daemon anymore. If you want to
-keep the server connection open for prog..., use
-s6-ipcclient s6-fdholder-getdumpc manually. 
-  The exact format of the environment given to prog...
-is described in the 
-s6-fdholder-getdumpc page. 
   Getting the whole state of a s6-fdholderd daemon requires specific
 privileges. Make sure you properly
 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 @@
-
-  
-    
-    
-    
-    s6: the s6-fdholder-getdumpc program
-    
-    
-    
-  
-
-
-
-s6

-Software

-skarnet.org
-
-
- The s6-fdholder-getdumpc program 
-
-
-s6-fdholder-getdumpc talks to a
-fd-holding daemon 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.
-
-
- Interface 
-
--     s6-fdholder-getdumpc [ -t timeout ] prog...
-
-
-
-  s6-fdholder-getdumpc expects to talk to a listening
-s6-fdholderd program on its descriptors 6 and 7. 
-  It retrieves a copy of the whole set of file descriptors
-stored in that daemon, including their identifiers and expiration dates. 
-  It then executes into prog... with the additional descriptors
-and environment. 
-
-
- Options 
-
-
-  -t timeout : if the operation cannot be
-processed in timeout 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. 
-
-
- Environment format 
-
-
- prog... is executed with the following environment variables
-set:
-
-
-
-  S6_FD# : contains the number n of file
-descriptors retrieved from the server. 
-  Then, for every i between 0 and n-1 inclusive:
- 
-   S6_FD_i : contains the number of the ith
-open file descriptor. 
-   S6_FDID_i : contains the identifier of the
-ith open file descriptor. 
-   S6_FDLIMIT_i : contains the expiration date of
-the ith open file descriptor, if applicable. That date is stored in
-external TAI64N
-format. 
-If the file descriptor is not supposed to expire, that environment variable
-is not defined. 
- 
 
-
-
- Notes 
-
-
-  s6-fdholder-getdumpc is the "internal" version of
-s6-fdholder-getdump. 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. 
-  Getting the whole state of a s6-fdholderd daemon requires specific
-privileges. Make sure you properly
-configure the s6-fdholderd
-access rights so your client can perform that operation. 
-  The error messages for the s6-fdholder suite are explained
-here. 
-
-
-
-
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 @@

s6-fdholder-list executes into s6-ipcclient path -s6-fdholder-listc id. It does nothing else: it is just a -convenience program. The s6-ipcclient program connects -to a Unix socket at path, and the -s6-fdholder-listc program transmits -the instruction over the socket, and gets and prints the result.
s6-fdholder-list connects to a +s6-fdholderd server process listening on +path.
It gets the list of identifiers corresponding to the currently held +file descriptors. It prints that list to stdout, one per line.

Options

-t timeout : if the operation cannot be +
-t timeout : if the operation cannot be processed in timeout 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).

Exit codes

+ +

0: success.
1: the server denied the operation. The meaning of the error messages +is explained here.
100: wrong usage.
111: system call failed - that includes attempting to connect to a +nonexistent socket, or one where no s6-fdholderd +daemon is listening.

+ 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 @@ - - - - - - s6: the s6-fdholder-listc program - - - - - - -

-s6
-Software
-skarnet.org -

- -

The `s6-fdholder-listc` program

- -

-s6-fdholder-listc talks to a -fd-holding daemon 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. -

- -

Interface

- -

-     s6-fdholder-listc [ -t timeout ]
-

- -

s6-fdholder-listc expects to talk to a listening -s6-fdholderd program on its descriptors 6 and 7.
It gets the list of identifiers corresponding to the currently held -file descriptors. It prints that list to stdout, one per line. -
It then exits 0, or 1 if the server returned an error.

- -

Options

- -

-t timeout : if the operation cannot be -processed in timeout 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.

- -

Notes

- -

s6-fdholder-listc is the "internal" version of -s6-fdholder-list. 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.
The error messages for the s6-fdholder suite are explained -here.
The list of identifiers is printed one per line; special -characters - such as newline - are quoted. The output can be -unquoted, for instance, by -s6-unquote-filter --d "".

- - - 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.

s6-fdholder-retrieve executes into s6-ipcclient path -s6-fdholder-retrievec id prog.... -It does nothing else: it is just a convenience program. -The s6-ipcclient program connects -to a Unix socket at path, and the -s6-fdholder-retrievec program -gets the file descriptor identified by id over the socket.
It should be used to connect to a -s6-fdholderd daemon, which will pass the -file descriptor to the client over the path socket.
It executes into prog... with the retrieved file -descriptor as prog...'s standard input.
s6-fdholder-retrieve connects to a +s6-fdholderd server process listening on +path.
It attempts to retrieve a copy of the file descriptor that has been +stored into that daemon under identifier id. +
It then executes into prog..., with the retrieved +file descriptor as standard input.

Options

@@ -61,6 +56,18 @@ only here to protect users against programming errors (connecting to the wrong socket, for instance). +

Exit codes

+ +

On success, the program doesn't exit; instead, it execs into prog....
1: the server denied the operation. The meaning of the error messages +is explained here.
100: wrong usage.
111: system call failed - that includes attempting to connect to a +nonexistent socket, or one where no s6-fdholderd +daemon is listening.

Usage example

@@ -80,19 +87,11 @@ connection.
  Notes 
 
 
-  s6-fdholder-retrieve really executes into s6-ipcclient
-s6-fdholder-retrievec
-fdclose
-6 fdclose 7 prog..., so that prog... does not
-have a connection with the fd-holding daemon anymore. If you want to
-keep the server connection open for prog..., use
-s6-ipcclient s6-fdholder-retrievec manually. 
   To execute prog with the newly retrieved file descriptor
 as number n while preserving stdin, use the following construct:
 fdmove n 0 s6-fdholder-retrieve path id
 fdswap
-0 n prog.... Be aware that n
-cannot be 6 or 7, internally used by s6-fdholder-retrieve. 
+0 n prog.... 
 
 
 
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 @@
-
-  
-    
-    
-    
-    s6: the s6-fdholder-retrievec program
-    
-    
-    
-  
-
-
-
-s6

-Software

-skarnet.org
-
-
- The s6-fdholder-retrievec program 
-
-
-s6-fdholder-retrievec talks to a
-fd-holding daemon on its open
-descriptors 6 and 7, and retrieves a file descriptor from it,
-then executes a program.
-
-
- Interface 
-
--     s6-fdholder-retrievec [ -D ] [ -t timeout ] id prog...
-
-
-
-  s6-fdholder-retrievec expects to talk to a listening
-s6-fdholderd program on its descriptors 6 and 7. 
-  It attempts to retrieve a copy of the file descriptor that has been
-stored into that daemon under identifier id.
- 
 It then executes into prog..., with the retrieved
-file descriptor as standard input. 
-
-
- Options 
-
-
-  -D : 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
-configuration. 
-  -t timeout : if the operation cannot be
-processed in timeout 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. 
-
-
- Notes 
-
-
- s6-fdholder-retrievec is the "internal" version of
-s6-fdholder-retrieve. 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. 
-  The error messages for the s6-fdholder suite are explained
-here. 
-
-
-
-
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.

s6-fdholder-setdump executes into s6-ipcclient path -s6-fdholder-setdumpc id. It does nothing else: it is just a -convenience program. The s6-ipcclient program connects -to a Unix socket at path, and the -s6-fdholder-setdumpc program transmits the -file descriptors over the socket.
It should be used to connect to a -s6-fdholderd daemon, which will store the set of -file descriptors.
s6-fdholder-setdump connects to a +s6-fdholderd server process listening on +path.
It attempts to pass a complete state - i.e. a set of file descriptors +with identifiers and expiration dates - to the server.

Options

@@ -53,14 +49,26 @@ only here to protect users against programming errors (connecting to the wrong socket, for instance). +

Exit codes

+ +

0: success.
1: the server denied the operation. The meaning of the error messages +is explained here.
100: wrong usage.
111: system call failed - that includes attempting to connect to a +nonexistent socket, or one where no s6-fdholderd +daemon is listening.

Notes

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 s6-fdholder-setdump program; also, s6-fdholder-setdump 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 -s6-fdholder-getdumpc.

s6-fdholder-getdump

Getting the whole state of a s6-fdholderd daemon requires specific privileges. Make sure you properly 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 @@ - - - - - - s6: the s6-fdholder-setdumpc program - - - - - - -
-s6
-Software
-skarnet.org -
- -
The s6-fdholder-setdumpc program
- -
-s6-fdholder-setdumpc talks to a -fd-holding daemon 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. -
- -
Interface
- -
```
-     s6-fdholder-setdumpc [ -t timeout ]
-
```
- -
- s6-fdholder-setdumpc expects to talk to a listening -s6-fdholderd program on its descriptors 6 and 7.
- It attempts to pass a complete state - i.e. a set of file descriptors -with identifiers and expiration dates - to s6-fdholderd.
- It then exits 0, or 1 if the server returned an error.
- -
Options
- -
- -t timeout : if the operation cannot be -processed in timeout 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.
- -
Notes
- -
- The error messages for the s6-fdholder suite are explained -here.
- The format of the environment variables where s6-fdholder-setdumpc -gets its information from is the same as the one set by -s6-fdholder-getdumpc.
- Getting the whole state of a s6-fdholderd daemon requires specific -privileges. Make sure you properly -configure the s6-fdholderd -access rights so your client can perform that operation.
- - - 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.
- s6-fdholder-store executes into s6-ipcclient path -s6-fdholder-storec id. It does nothing else: it is just a -convenience program. The s6-ipcclient program connects -to a Unix socket at path, and the -s6-fdholder-storec program transmits the desired -file descriptor over the socket.
- It should be used to connect to a -s6-fdholderd daemon, which will store the -file descriptor given by the user.
- s6-fdholder-store connects to a +s6-fdholderd server process listening on +path.
- It attempts to pass a copy of its standard input, or of its descriptor +fd, to the server, with identifier id.
Options
- -d fd : store descriptor number fd. -By default, fd is 0 (i.e. the program's stdin will be stored). -s6-fdholder-store replaces its stdin with fd before executing into -s6-ipcclient s6-fdholder-storec.
- -T fdtimeout : the descriptor is stored with an expiration time of fdtimeout milliseconds, which means the s6-fdholderd daemon will close and get rid of the descriptor after that time. By default, fdtimeout is 0, which means infinite - no expiration time.
- -t timeout : if the operation cannot be +
- -t timeout : if the operation cannot be processed in timeout 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).
+
Exit codes
+ +
- 0: success.
- 1: the server denied the operation. The meaning of the error messages +is explained here.
- 100: wrong usage.
- 111: system call failed - that includes attempting to connect to a +nonexistent socket, or one where no s6-fdholderd +daemon is listening.
+
Usage example
```
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 @@
-
-  
-    
-    
-    
-    s6: the s6-fdholder-storec program
-    
-    
-    
-  
-
-
-
-s6

-Software

-skarnet.org
-
-
- The s6-fdholder-storec program 
-
-
-s6-fdholder-storec talks to a
-fd-holding daemon on its open
-descriptors 6 and 7, and passes it a copy of its standard
-input.
-
-
- Interface 
-
--     s6-fdholder-storec [ -T fdtimeout ] [ -t timeout ] id
-
-
-
-  s6-fdholder-storec expects to talk to a listening
-s6-fdholderd program on its descriptors 6 and 7. 
-  It attempts to pass a copy of its fd 0 (standard input) to s6-fdholderd,
-with identifier id. 
-  It then exits 0, or 1 if the server returned an error. 
-
-
- Options 
-
-
-  -T fdtimeout : the descriptor is stored with
-an expiration time of fdtimeout milliseconds, which means the
-s6-fdholderd daemon will close and get rid of
-the descriptor after that time. By default, fdtimeout is 0, which
-means infinite - no expiration time. 
- -t timeout : if the operation cannot be
-processed in timeout 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. 
-
-
- Notes 
-
-
- s6-fdholder-storec is the "internal" version of
-s6-fdholder-store. 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. 
-  The error messages for the s6-fdholder suite are explained
-here. 
-
-
-
-
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.
 
```
- s6-fdholder-transferdump executes into a more complex command line -involving two -s6-ipcclient invocations and ending with -s6-fdholder-transferdumpc. It -is just a convenience program: the real transfer is performed by -s6-fdholder-transferdumpc.
- The file descriptor transfer will occur from the -s6-fdholderd daemon listening on -pathfrom to the one listening on pathto.
- s6-fdholder-transferdump connects to a +s6-fdholderd server process listening on +pathfrom and gets the whole set of file descriptors from +this server, with their identifiers and (when relevant) expiration +dates.
- It then connects to a different instance of +s6-fdholderd, listening on pathto, +and stores the set of file descriptors to it. The set is +added to the second server, which keeps the descriptors +it was already holding.
Options
@@ -55,5 +56,33 @@ only here to protect users against programming errors (connecting to the wrong socket, for instance).

Exit codes

+ +

0: success.
1: the source server denied the operation. The meaning of the error messages +is explained here.
2: the destination server denied the operation. The meaning of the error messages +is explained here.
100: wrong usage.
111: system call failed - that includes attempting to connect to a +nonexistent socket, or one where no s6-fdholderd +daemon is listening.

+ +

Notes

+ +

Dumping the entire state of s6-fdholderd +requires special authorizations. Make sure the s6-fdholderd instances are +configured to accept +dump-getting and dump-setting requests from your client.
A typical use case of +s6-fdholder-transferdump 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.

+ 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 @@ - - - - - - s6: the s6-fdholder-transferdumpc program - - - - - - -

-s6
-Software
-skarnet.org -

- -

The `s6-fdholder-transferdumpc` program

- -

-s6-fdholder-transferdumpc talks to two -fd-holding daemons: 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. -

- -

Interface

- -

-     s6-fdholder-transferdumpc [ -t timeoutfrom ] [ -T timeoutto ]
-

- -

s6-fdholder-transferdumpc expects to talk to a listening -s6-fdholderd program on its descriptor 0 and -to another one on its descriptor 1.
It gets the entire set of file descriptors from the first -server, with their identifiers and possibly expiration dates.
It stores that set into the second server. The set is -added to the second server, which keeps the descriptors -it was already holding.
It then exits 0, or 1 if a server returned an error.

- -

Options

- -

-t timeoutfrom : if the set-retrieving -operation cannot be processed in timeoutfrom 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.
-T timeoutto : same thing with the -set-storing operation.

- -

Notes

- -

s6-fdholder-transferdumpc is the "internal" version of -s6-fdholder-transferdump. It simply -expects to be run with file descriptors already open to both -servers; s6-fdholder-transferdump -takes care of all the plumbing.
The error messages for the s6-fdholder suite are explained -here.
Dumping the entire state of s6-fdholderd -requires special authorizations. Make sure the s6-fdholderd instances are -configured to accept -dump-getting and dump-setting requests from your client.
A typical use case of -s6-fdholder-transferdump 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.

- - - 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.

Possible operations include:

Storing a file descriptor
Retrieving a file descriptor
Deleting a file descriptor
Listing stored file descriptor +
Storing a file descriptor
Retrieving a file descriptor
Deleting a file descriptor
Listing stored file descriptor identifiers
Getting the whole server state
Setting the whole server state, +
Getting the whole server state
Setting the whole server state, or more accurately adding a set of file descriptors to the already existing state

@@ -117,12 +117,12 @@ changes in the filesystem are automatically picked up.

Every file descriptor is stored in the s6-fdholderd daemon via the -s6-fdholder-storec program, with +s6-fdholder-store program, with an identifier. That identifier is a zero-terminated character string, containing 1 to 255 characters.
Any non-null character can be used in an identifier. Non-printable or special characters will be quoted when printed by -s6-fdholder-listc. However, it is +s6-fdholder-list. 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.
New functionality added to s6-log. Its syntax has been extended; some options are now marked as obsolescent.
Access control instated in s6-fdholderd -for listing

listing

in 2.1.0.1

-- cgit v1.2.3

A programming example

Synchronous functions with a specified maximum execution time

Options

Exit codes

Usage example

The s6-fdholder-deletec program

Interface

Options

Notes

Options

Exit codes

Environment format

Usage example

Notes

The s6-fdholder-getdumpc program

Interface

Options

Environment format

Notes

Options

Exit codes

The s6-fdholder-listc program

Interface

Options

Notes

Options

Exit codes

Usage example

Notes

The s6-fdholder-retrievec program

Interface

Options

Notes

Options

Exit codes

Notes

The s6-fdholder-setdumpc program

Interface

Options

Notes

Options

Exit codes

Usage example

The s6-fdholder-storec program

Interface

Options

Notes

Options

Exit codes

Notes

The s6-fdholder-transferdumpc program

Interface

Options

Notes

in 2.1.0.1

The `s6-fdholder-deletec` program

The `s6-fdholder-getdumpc` program

The `s6-fdholder-listc` program

The `s6-fdholder-retrievec` program

The `s6-fdholder-setdumpc` program

The `s6-fdholder-storec` program

The `s6-fdholder-transferdumpc` program