1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
<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 library interface</title>
<meta name="Description" content="s6: the s6-fdholder library interface" />
<meta name="Keywords" content="s6 fdholder file descriptor fd holding fd-passing library interface" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="index.html">libs6</a><br />
<a href="../">s6</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>fdholder</tt> library interface </h1>
<p>
The <tt>fdholder</tt> library provides an API for clients
wanting to communicate with a
<a href="../s6-fdholderd.html">s6-fdholderd</a> daemon.
</p>
<h2> Programming </h2>
<p>
Check the <tt>s6/fdholder.h</tt> header for the
exact function prototypes.
</p>
<h3> A programming example </h3>
<p>
The <tt>src/fdholder/s6-fdholder-*.c</tt> files in the s6 package,
for instance, illustrate how to use the fdholder library.
</p>
<h3> Synchronous functions with a specified maximum execution time </h3>
<p>
The explanation given
<a href="ftrigr.html#synctimed">there</a> applies here too: the
functions documented in this page are synchronous, but can return
early if the deadline is reached, in which case the connection to the
server should be closed immediately because no protocol consistency is
guaranteed.
</p>
<p>
The <a href="../s6-fdholderd.html">s6-fdholderd</a> server should be
very quick to answer queries, so this mechanism is provided as a simple
security against programming errors - for instance, connecting to the
wrong daemon.
</p>
<h3> Starting and ending a session </h3>
<pre>
s6_fdholder_t a = S6_FDHOLDER_ZERO ;
int fd = 6 ;
tain_now_g() ;
s6_fdholder_init(&a, fd) ;
(...)
s6_fdholder_free(&a) ;
</pre>
<p>
<tt>s6_fdholder_init</tt> assumes that <em>fd</em> is a socket already
connected to an s6-fdholderd daemon. The <em>a</em> structure must be
initialized to <tt>S6_FDHOLDER_ZERO</tt> before use.
</p>
<p>
<a href="//skarnet.org/software/skalibs/libstddjb/tai.html">tain_now_g()</a>
initializes a global variable that keeps track of the current time, for
use with later functions.
</p>
<p>
<tt>s6_fdholder_free</tt> frees the resources occupied by <em>a</em>.
It does not, however, close <em>fd</em>. You should manually close it
to end the connection to the server. Note that if your program has been
started by <a href="../s6-ipcclient.html">s6-ipcclient</a>, both fds 6
and 7 are open (and refer to the same socket), so you should close both.
</p>
<p>
Alternatively, if your connection to s6-fdholderd has not been created yet,
you can use the following functions:
</p>
<h4> <code> int s6_fdholder_start (s6_fdholder_t *a, char const *path, tain_t const *deadline, tain_t *stamp) </code> </h4>
<p>
Starts a session with a <a href="../s6-fdholderd.html">s6-fdholderd</a>
instance listening on <em>path</em>. <em>a</em> must be initialized to
S6_FDHOLDER_ZERO before calling this function. On success, returns nonzero
and <em>a</em> can be used as a handle for the next <tt>s6_fdholder_*</tt>
function calls. On failure, returns 0, and sets errno.
</p>
<h4> <code> void s6_fdholder_end (s6_fdholder_t *a) </code> </h4>
<p>
Ends the current session and frees all allocated resources. If needed,
<em>a</em> is immediately reusable for another <tt>s6_fdholder_start</tt> call.
</p>
<h3> Storing a fd </h3>
<pre>
int r ;
int fd ;
tain_t limit = TAIN_INFINITE ;
char const *id = "my_identifier" ;
r = s6_fdholder_store_g(&a, fd, id, &limit, &deadline) ;
</pre>
<p>
<tt>s6_fdholder_store</tt> (and its variant <tt>s6_fdholder_store_g</tt>
that uses the global timestamp variable) attempts to store a copy of
descriptor <em>fd</em> into s6-fdholderd, using identifier <em>id</em>,
with an expiration date of <em>limit</em>. In this example, <em>limit</em>
is TAIN_INFINITE, which means no expiration date. The operation should
return before <em>deadline</em>, else it will automatically return
0 ETIMEDOUT. The result is 1 on success and 0 on failure, with an
<a href="../s6-fdholder-errorcodes.html">appropriate</a> errno code.
</p>
<h3> Deleting a fd </h3>
<pre>
fd = s6_fdholder_delete_g(&a, id, &deadline) ;
</pre>
<p>
<tt>s6_fdholder_delete</tt> attempts to delete the file descriptor
identified by <em>id</em>. It returns 1 on success and 0 on failure,
with an
<a href="../s6-fdholder-errorcodes.html">appropriate</a> errno code.
</p>
<h3> Retrieving a fd </h3>
<pre>
fd = s6_fdholder_retrieve_g(&a, id, &deadline) ;
</pre>
<p>
<tt>s6_fdholder_retrieve</tt> attempts to retrieve the file descriptor
identified by <em>id</em>. It returns a valid fd number on success, and
-1 on failure, with an
<a href="../s6-fdholder-errorcodes.html">appropriate</a> errno code.
</p>
<p>
<tt>s6_fdholder_retrieve_delete()</tt> performs a retrieval and a
deletion at the same time, if the client is authorized to do so.
</p>
<h3> Listing the identifiers held by the server </h3>
<pre>
stralloc list = STRALLOC_ZERO ;
int n ;
n = s6_fdholder_list_g(&a, &list, &deadline) ;
</pre>
<p>
<tt>s6_fdholder_list</tt> gets the list of all identifiers currently
held by the server. It stores it into the
<a href="//skarnet.org/software/skalibs/libstddjb/stralloc.html">stralloc</a>
<em>list</em>, as a series of null-terminated strings, one after the other.
There are <em>n</em> such strings. The function returns <em>n</em> on
success, or -1 on failure, with an
<a href="../s6-fdholder-errorcodes.html">appropriate</a> errno code.
</p>
<h3> Reading a dump </h3>
<pre>
genalloc dump = GENALLOC_ZERO ;
r = s6_fdholder_getdump_g(&a, &dump, &deadline) ;
</pre>
<p>
<tt>s6_fdholder_getdump</tt> attempts to retrieve the whole set of
descriptors from the server.
It returns 1 on success, and 0 on failure, with an
<a href="../s6-fdholder-errorcodes.html">appropriate</a> errno code.
The set is stored into the
<a href="//skarnet.org/software/skalibs/libstddjb/genalloc.html">genalloc</a>
<em>dump</em>, which is to be interpreted as a stralloc containing an array
of <tt>s6_fdholder_fd_t</tt>.
</p>
<p>
<tt>genalloc_s(s6_fdholder_fd_t, &dump)</tt> is a pointer to this array, and
<tt>genalloc_len(s6_fdholder_fd_t, &dump)</tt> is the number of elements
in the array. A <tt>s6_fdholder_fd_t</tt> contains at least a descriptor
number, an identifier, and an expiration date, see the
<tt>s6/fdholder.h</tt> header file.
</p>
<h3> Writing a dump </h3>
<pre>
unsigned int dumplen ;
s6_fdholder_fd_t const *dumparray ;
r = s6_fdholder_setdump_g(&a, &dumparray, dumplen, &deadline) ;
</pre>
<p>
<tt>s6_fdholder_setdump</tt> attempts to send a set of descriptors to the
server. The descriptors are contained in the array <em>dumparray</em> of
length <em>dumplen</em>. The function
returns 1 on success, and 0 on failure, with an
<a href="../s6-fdholder-errorcodes.html">appropriate</a> errno code.
</p>
</body>
</html>
|
