Debian Codegraph @

upstream/debian-unstable/man3/sd_varlink_connect_address.3

raw
1 '\" t
2 .TH "SD_VARLINK_CONNECT_ADDRESS" "3" "" "systemd 261~rc3" "sd_varlink_connect_address"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_varlink_connect_address, sd_varlink_connect_exec, sd_varlink_connect_url, sd_varlink_connect_fd, sd_varlink_connect_fd_pair \- Create a Varlink connection object and connect it to a service
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-varlink\&.h>
29 .fi
30 .ft
31 .sp
32 .ft B
33 .nf
34 struct ucred; /* defined in <sys/socket\&.h> */
35 .fi
36 .ft
37 .HP \w'int\ sd_varlink_connect_address('u
38 .BI "int sd_varlink_connect_address(sd_varlink\ **" "ret" ", const\ char\ *" "address" ");"
39 .HP \w'int\ sd_varlink_connect_exec('u
40 .BI "int sd_varlink_connect_exec(sd_varlink\ **" "ret" ", const\ char\ *" "command" ", char\ **" "argv" ");"
41 .HP \w'int\ sd_varlink_connect_url('u
42 .BI "int sd_varlink_connect_url(sd_varlink\ **" "ret" ", const\ char\ *" "url" ");"
43 .HP \w'int\ sd_varlink_connect_fd('u
44 .BI "int sd_varlink_connect_fd(sd_varlink\ **" "ret" ", int\ " "fd" ");"
45 .HP \w'int\ sd_varlink_connect_fd_pair('u
46 .BI "int sd_varlink_connect_fd_pair(sd_varlink\ **" "ret" ", int\ " "input_fd" ", int\ " "output_fd" ", const\ struct\ ucred\ *" "override_ucred" ");"
47 .SH "DESCRIPTION"
48 .PP
49 These five functions allocate a new client\-side Varlink connection object and connect it to a Varlink service\&. They differ only in how the service to talk to is specified\&. On success, a reference to the new connection object is returned in
50 \fIret\fR; the caller owns this reference and must eventually release it with
51 \fBsd_varlink_unref\fR(3),
52 \fBsd_varlink_close_unref\fR(3)
53 or
54 \fBsd_varlink_flush_close_unref\fR(3)\&.
55 .PP
56 All five functions return immediately; none of them blocks waiting for the connection to be fully established\&. For socket\-based connections the actual
57 \fBconnect()\fR
58 may still be in progress when the function returns (see below); the connection object handles the completion transparently\&.
59 .PP
60 The returned connection object is not attached to any event loop\&. There are three ways to drive it: attach it to an
61 \fBsd-event\fR(3)
62 loop with
63 \fBsd_varlink_attach_event\fR(3); run its I/O manually via
64 \fBsd_varlink_process\fR(3)
65 and
66 \fBsd_varlink_wait\fR(3); or simply issue blocking method calls\&. In particular it is perfectly fine to follow any of these connection functions directly with a synchronous, blocking call such as
67 \fBsd_varlink_call\fR(3), which internally drives the connection (including completing a still\-pending
68 \fBconnect()\fR) and returns once the reply has been received\&. In that case no explicit event loop integration or manual processing is required\&.
69 .PP
70 \fBsd_varlink_connect_address()\fR
71 connects to an
72 \fBAF_UNIX\fR
73 stream socket whose address is given as a string in
74 \fIaddress\fR\&. The address must begin either with
75 "/"
76 (to reference a socket in the file system) or with
77 "@"
78 (to reference a socket in the abstract namespace, with the remainder of the string used as the abstract name)\&. It must be at least two characters long\&. No other forms are accepted (in particular, relative paths are refused)\&. Abstract namespace names that embed
79 \fBNUL\fR
80 bytes cannot be expressed through this interface\&. If a file system socket path is too long to fit into a
81 sockaddr_un
82 structure, the connection is established transparently via an
83 \fBO_PATH\fR
84 indirection, so overlong paths work\&.
85 .PP
86 \fBsd_varlink_connect_exec()\fR
87 forks off a child process and speaks the Varlink protocol with it over a connected
88 \fBAF_UNIX\fR
89 \fBSOCK_STREAM\fR
90 socket pair\&.
91 \fIcommand\fR
92 is the program to execute; it is looked up in
93 \fI$PATH\fR
94 in the usual way (i\&.e\&. via
95 \fBexecvp\fR(3))\&.
96 \fIargv\fR
97 is the argument vector (a
98 \fBNULL\fR\-terminated string array) to pass to the child as its
99 \fIargv[]\fR; if it is
100 \fBNULL\fR
101 or empty, an argument vector consisting of just
102 \fIcommand\fR
103 is synthesized\&. The connected socket is handed to the child as file descriptor 3 using the
104 \fBsd_listen_fds\fR(3)
105 protocol, i\&.e\&. the child is invoked with
106 \fI$LISTEN_FDS\fR
107 set to
108 "1",
109 \fI$LISTEN_FDNAMES\fR
110 set to
111 "varlink", and the appropriate
112 \fI$LISTEN_PID\fR
113 (and, where available,
114 \fI$LISTEN_PIDFDID\fR) variables\&. The
115 \fIcommand\fR
116 and
117 \fIargv\fR
118 strings are copied into the connection object, so the caller may free or modify them once the function returns\&.
119 .PP
120 \fBsd_varlink_connect_url()\fR
121 is a higher\-level interface that parses a service address string with a leading scheme and dispatches to the appropriate transport\&. Despite the name, these strings are
122 \fInot\fR
123 Internet URLs in the sense of the relevant RFCs\&. The following schemes are understood natively:
124 .PP
125 "unix:"\fIPATH\fR
126 .RS 4
127 Connects to an
128 \fBAF_UNIX\fR
129 socket, equivalent to passing
130 \fIPATH\fR
131 to
132 \fBsd_varlink_connect_address()\fR\&.
133 \fIPATH\fR
134 must either be an absolute, normalized file system path, or begin with
135 "@"
136 for an abstract namespace socket (for which no path normalization checks are applied)\&.
137 .RE
138 .PP
139 "exec:"\fIPATH\fR
140 .RS 4
141 Forks off the executable at
142 \fIPATH\fR, equivalent to passing it to
143 \fBsd_varlink_connect_exec()\fR
144 with no extra arguments\&.
145 \fIPATH\fR
146 must be an absolute, normalized path\&.
147 .RE
148 .PP
149 "ssh:"\fIHOST\fR":"\fIPATH\fR, "ssh\-unix:"\fIHOST\fR":"\fIPATH\fR
150 .RS 4
151 Connects to an
152 \fBAF_UNIX\fR
153 socket at the absolute, normalized path
154 \fIPATH\fR
155 on the remote SSH host
156 \fIHOST\fR\&. This relies on OpenSSH 9\&.4 or newer on the server side\&. Abstract namespace sockets are not supported for this transport\&.
157 "ssh:"
158 and
159 "ssh\-unix:"
160 are synonyms\&.
161 .RE
162 .PP
163 "ssh\-exec:"\fIHOST\fR":"\fICOMMAND\fR
164 .RS 4
165 Invokes
166 \fICOMMAND\fR
167 (a command line, split on whitespace with shell\-style quoting and unescaping) on the remote SSH host
168 \fIHOST\fR
169 and speaks the Varlink protocol over its standard input and output\&.
170 .RE
171 .PP
172 If the scheme is none of the above but is otherwise a syntactically valid URL scheme,
173 \fBsd_varlink_connect_url()\fR
174 looks for a
175 \fIbridge helper\fR
176 binary of that name in the directory configured via
177 \fI$SYSTEMD_VARLINK_BRIDGES_DIR\fR
178 (see below)\&. If found and executable, it is invoked like an
179 "exec:"
180 transport, with the complete, unmodified URL passed as its sole command line argument\&. This allows additional transports to be plugged in out of tree\&.
181 .PP
182 For the natively supported schemes, URL parameterization using
183 ";",
184 "?"
185 or
186 "#"
187 is rejected (these are reserved for possible future use)\&. A
188 "vsock:"
189 scheme is not currently supported\&.
190 .PP
191 \fBsd_varlink_connect_fd()\fR
192 turns an already existing, already connected file descriptor
193 \fIfd\fR
194 into a Varlink connection\&. The descriptor is used for both reading and writing\&. It may refer to a connected stream socket, but also to a pipe or other bidirectional file descriptor\&.
195 .PP
196 \fBsd_varlink_connect_fd_pair()\fR
197 is like
198 \fBsd_varlink_connect_fd()\fR, but accepts a separate
199 \fIinput_fd\fR
200 (used for reading from the peer) and
201 \fIoutput_fd\fR
202 (used for writing to the peer)\&. This is useful when the two directions are backed by different descriptors, for example a pair of pipes, or the standard output and standard input of a co\-process\&. The two descriptors may also be identical, which is exactly what
203 \fBsd_varlink_connect_fd()\fR
204 does internally\&. If
205 \fIoverride_ucred\fR
206 is non\-\fBNULL\fR, the peer credentials reported for the connection (as returned e\&.g\&. by
207 \fBsd_varlink_get_peer_uid\fR(3)) are taken from the supplied
208 ucred
209 structure instead of being queried from the socket via
210 \fBSO_PEERCRED\fR\&. This is primarily useful when the descriptors are not sockets (and hence carry no kernel\-supplied peer credentials), or when the credentials need to be overridden for other reasons\&. If
211 \fIoverride_ucred\fR
212 is
213 \fBNULL\fR, peer credentials are determined from the socket as usual\&.
214 .PP
215 \fBsd_varlink_connect_fd()\fR
216 and
217 \fBsd_varlink_connect_fd_pair()\fR
218 take over ownership of the descriptors passed to them: the descriptors are closed automatically when the connection object is freed, and the caller must not close them itself\&. On failure ownership remains with the caller\&.
219 .PP
220 The connection objects created by
221 \fBsd_varlink_connect_exec()\fR, and by the
222 "exec:",
223 "ssh:"/"ssh\-unix:",
224 "ssh\-exec:"
225 and bridge\-helper paths of
226 \fBsd_varlink_connect_url()\fR, are bound to the lifetime of the spawned child process\&. When such a connection object is freed, the associated child process is sent
227 \fBSIGTERM\fR
228 and reaped\&. The child is also configured to receive
229 \fBSIGTERM\fR
230 if the calling process dies\&.
231 .SH "RETURN VALUE"
232 .PP
233 On success, these functions return a non\-negative integer and store a pointer to the new connection object in
234 \fIret\fR\&. On failure, they return a negative errno\-style error code and leave
235 \fIret\fR
236 unchanged\&.
237 .SS "Errors"
238 .PP
239 Returned errors may indicate the following problems:
240 .PP
241 \fB\-EINVAL\fR
242 .RS 4
243 A required argument is
244 \fBNULL\fR, or the supplied address, command, or URL is malformed\&. This includes addresses that do not begin with
245 "/"
246 or
247 "@", abstract namespace names that do not fit into a
248 sockaddr_un
249 structure, and \(em for
250 \fBsd_varlink_connect_url()\fR
251 \(em file system paths that are not absolute or not normalized\&.
252 .RE
253 .PP
254 \fB\-EBADF\fR
255 .RS 4
256 For
257 \fBsd_varlink_connect_fd()\fR
258 and
259 \fBsd_varlink_connect_fd_pair()\fR: a supplied file descriptor is negative\&.
260 .RE
261 .PP
262 \fB\-EPROTONOSUPPORT\fR
263 .RS 4
264 For
265 \fBsd_varlink_connect_url()\fR: the URL contains no
266 ":"
267 separator, uses an unsupported scheme for which no bridge helper binary is available, or makes use of the reserved
268 ";",
269 "?"
270 or
271 "#"
272 URL parameterization characters with a natively supported scheme\&.
273 .RE
274 .PP
275 \fB\-ENOMEM\fR
276 .RS 4
277 Memory allocation failed\&.
278 .RE
279 .PP
280 In addition, these functions may propagate any error returned by the underlying system calls they use, such as
281 \fBsocket\fR(2),
282 \fBconnect\fR(2),
283 \fBfork\fR(2),
284 \fBpipe\fR(2)
285 and the various execution helpers\&.
286 .SH "NOTES"
287 .PP
288 Functions described here are available as a shared library, which can be compiled against and linked to with the
289 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
290 file\&.
291 .PP
292 The code described here uses
293 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
294 \fBsetenv\fR(3)
295 from a parallel thread\&. It is recommended to only do calls to
296 \fBsetenv()\fR
297 from an early phase of the program when no other threads have been started\&.
298 .SH "ENVIRONMENT"
299 .PP
300 \fI$SYSTEMD_SSH\fR
301 .RS 4
302 Used by the
303 "ssh:"/"ssh\-unix:"
304 and
305 "ssh\-exec:"
306 transports of
307 \fBsd_varlink_connect_url()\fR
308 to override the
309 \fBssh\fR
310 binary to invoke\&. May be a plain file name (looked up in
311 \fI$PATH\fR) or an absolute path\&.
312 .sp
313 Added in version 257\&.
314 .RE
315 .PP
316 \fI$SYSTEMD_VARLINK_BRIDGES_DIR\fR
317 .RS 4
318 Overrides the directory in which
319 \fBsd_varlink_connect_url()\fR
320 looks up bridge helper binaries for non\-native URL schemes\&. Defaults to
321 /usr/lib/systemd/varlink\-bridges/\&.
322 .sp
323 Added in version 257\&.
324 .RE
325 .SH "FILES"
326 .PP
327 /usr/lib/systemd/varlink\-bridges/
328 .RS 4
329 Default directory searched for bridge helper binaries when
330 \fBsd_varlink_connect_url()\fR
331 encounters a URL with a scheme that is not natively supported\&. See
332 \fBsd-varlink\fR(3)
333 for details\&.
334 .RE
335 .SH "HISTORY"
336 .PP
337 \fBsd_varlink_connect_address()\fR,
338 \fBsd_varlink_connect_exec()\fR,
339 \fBsd_varlink_connect_url()\fR,
340 \fBsd_varlink_connect_fd()\fR
341 and
342 \fBsd_varlink_connect_fd_pair()\fR
343 were added in version 257\&.
344 .SH "SEE ALSO"
345 .PP
346 \fBsystemd\fR(1), \fBsd-varlink\fR(3), \fBsd_varlink_attach_event\fR(3), \fBsd_varlink_call\fR(3), \fBsd_varlink_send\fR(3), \fBsd_varlink_is_connected\fR(3), \fBsd_listen_fds\fR(3), \fBvarlinkctl\fR(1)