s6-fdholder-getdump.html (4174B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>s6: the s6-fdholder-getdump program</title> 7 <meta name="Description" content="s6: the s6-fdholder-getdump program" /> 8 <meta name="Keywords" content="s6 s6-fdholder fd-holding fd-holder fd dump retrieval unix socket activation" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">s6</a><br /> 15 <a href="//skarnet.org/software/">Software</a><br /> 16 <a href="//skarnet.org/">skarnet.org</a> 17 </p> 18 19 <h1> The <tt>s6-fdholder-getdump</tt> program </h1> 20 21 <p> 22 <tt>s6-fdholder-getdump</tt> connects to a 23 <a href="s6-fdholderd.html">fd-holding daemon</a> listening on a 24 Unix domain socket, and retrieves its entire state: file descriptors with 25 their identifiers and expiration dates. It then executes a program with 26 those file descriptors still open, and the state stored in the 27 environment. 28 </p> 29 30 <h2> Interface </h2> 31 32 <pre> 33 s6-fdholder-getdump [ -t <em>timeout</em> ] <em>path</em> <em>prog...</em> 34 </pre> 35 36 <ul> 37 <li> <tt>s6-fdholder-getdump</tt> connects to a 38 <a href="s6-fdholderd.html">s6-fdholderd</a> server process listening on 39 <em>path</em>. </li> 40 <li> It retrieves a copy of the whole set of file descriptors 41 stored in this daemon, including their identifiers and expiration dates. </li> 42 <li> It then executes into <em>prog...</em> with the additional open descriptors 43 and the additional environment variables. </li> 44 </ul> 45 46 <h2> Options </h2> 47 48 <ul> 49 <li> <tt>-t <em>timeout</em></tt> : if the operation cannot be 50 processed in <em>timeout</em> milliseconds, then fail with an error message. 51 Communications with the server should be near-instant, so this option is 52 only here to protect users against programming errors (connecting to the 53 wrong socket, for instance). </li> 54 </ul> 55 56 <h2> Exit codes </h2> 57 58 <ul> 59 <li> On success, the program doesn't exit; instead, it execs into <em>prog...</em>. </li> 60 <li> 1: the server denied the operation. The meaning of the error messages 61 is explained <a href="s6-fdholder-errorcodes.html">here</a>. </li> 62 <li> 100: wrong usage. </li> 63 <li> 111: system call failed - this includes attempting to connect to a 64 nonexistent socket, or one where no <a href="s6-fdholderd.html">s6-fdholderd</a> 65 daemon is listening. </li> 66 </ul> 67 68 <h2> Environment format </h2> 69 70 <p> 71 <em>prog...</em> is executed with the following environment variables 72 set: 73 </p> 74 75 <ul> 76 <li> <tt>S6_FD#</tt> : contains the number <em>n</em> of file 77 descriptors retrieved from the server. </li> 78 <li> Then, for every <em>i</em> between 0 and <em>n</em>-1 inclusive: 79 <ul> 80 <li> <tt>S6_FD_<em>i</em></tt> : contains the number of the <em>i</em>th 81 open file descriptor. </li> 82 <li> <tt>S6_FDID_<em>i</em></tt> : contains the identifier of the 83 <em>i</em>th open file descriptor. </li> 84 <li> <tt>S6_FDLIMIT_<em>i</em></tt> : contains the expiration date of 85 the <em>i</em>th open file descriptor, if applicable. This date is stored in 86 <a href="https://cr.yp.to/libtai/tai64.html#tai64n">external TAI64N 87 format</a>.<br /> 88 If the file descriptor is not supposed to expire, this environment variable 89 is not defined. </li> 90 </ul> </li> 91 </ul> 92 93 <h2> Usage example </h2> 94 95 <pre> 96 s6-fdholder-getdump /service/fdholderd/s s6-fdholder-setdump /service/fdholderd-2/s 97 </pre> 98 99 <p> 100 will get the state of the s6-fdholderd daemon listening on the <tt>/service/fdholderd/s</tt> 101 socket, and transmit it to the other s6-fdholderd daemon listening on the 102 <tt>/service/fdholderd-2/s</tt> socket. Note that in this precise case, 103 the <a href="s6-fdholder-transferdump.html">s6-fdholder-transferdump</a> 104 program does the same thing more efficiently. 105 </p> 106 107 <h2> Notes </h2> 108 109 <ul> 110 <li> Getting the whole state of an s6-fdholderd daemon requires specific 111 privileges. Make sure you properly 112 <a href="s6-fdholderd.html#configuration">configure the s6-fdholderd 113 access rights</a> so your client can perform that operation. </li> 114 </ul> 115 116 </body> 117 </html>