Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_set_watch_bind.3

raw
1 '\" t
2 .TH "SD_BUS_SET_WATCH_BIND" "3" "" "systemd 261~rc3" "sd_bus_set_watch_bind"
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_bus_set_watch_bind, sd_bus_get_watch_bind \- Control socket binding watching on bus connections
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-bus\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_bus_set_watch_bind('u
32 .BI "int sd_bus_set_watch_bind(sd_bus\ *" "bus" ", int\ " "b" ");"
33 .HP \w'int\ sd_bus_get_watch_bind('u
34 .BI "int sd_bus_get_watch_bind(sd_bus\ *" "bus" ");"
35 .SH "DESCRIPTION"
36 .PP
37 \fBsd_bus_set_watch_bind()\fR
38 may be used to enable or disable client\-side watching of server socket binding for a bus connection object\&. If the
39 \fIb\fR
40 is true, the feature is enabled, otherwise disabled (which is the default)\&. When enabled, and the selected bus address refers to an
41 AF_UNIX
42 socket in the file system which does not exist while the connection attempt is made an
43 \fBinotify\fR(7)
44 watch is installed on it, waiting for the socket to appear\&. As soon as the socket appears the connection is made\&. This functionality is useful in particular in early\-boot programs that need to run before the system bus is available, but want to connect to it the instant it may be connected to\&.
45 .PP
46 \fBsd_bus_get_watch_bind()\fR
47 may be used to query the current setting of this feature\&. It returns zero when the feature is disabled, and positive if enabled\&.
48 .PP
49 Note that no timeout is applied while we wait for the socket to appear\&. This means that any synchronous remote operation (such as
50 \fBsd_bus_call\fR(3),
51 \fBsd_bus_add_match\fR(3)
52 or
53 \fBsd_bus_request_name\fR(3)), that is used on a connection with this feature enabled that has not been established yet, might block forever if the socket is never created\&. However, asynchronous remote operations (such as
54 \fBsd_bus_send\fR(3),
55 \fBsd_bus_call_async\fR(3),
56 \fBsd_bus_add_match_async\fR(3)) do not block in this case, and safely enqueue the requested operations to be dispatched the instant the connection is set up\&.
57 .PP
58 Use
59 \fBsd_bus_is_ready\fR(3)
60 to determine whether the connection is fully established, i\&.e\&. whether the peer socket has been bound, connected to and authenticated\&. Use
61 \fBsd_bus_set_connected_signal\fR(3)
62 to be notified when the connection is fully established\&.
63 .SH "RETURN VALUE"
64 .PP
65 On success, these functions return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&.
66 .SS "Errors"
67 .PP
68 Returned errors may indicate the following problems:
69 .PP
70 \fB\-ECHILD\fR
71 .RS 4
72 The bus connection has been created in a different process, library or module instance\&.
73 .RE
74 .SH "NOTES"
75 .PP
76 Functions described here are available as a shared library, which can be compiled against and linked to with the
77 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
78 file\&.
79 .PP
80 The code described here uses
81 \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
82 \fBsetenv\fR(3)
83 from a parallel thread\&. It is recommended to only do calls to
84 \fBsetenv()\fR
85 from an early phase of the program when no other threads have been started\&.
86 .SH "EXAMPLE"
87 .PP
88 \fBExample\ \&1.\ \&Create a simple system service that publishes a property on the system bus and can reconnect when D\-Bus disconnects and reconnects\fR
89 .sp
90 .if n \{\
91 .RS 4
92 .\}
93 .nf
94 /* SPDX\-License\-Identifier: MIT\-0 */
95
96 /* A D\-Bus service that automatically reconnects when the system bus is
97 * restarted\&.
98 *
99 * Compile with \*(Aqcc sd_bus_service_reconnect\&.c $(pkg\-config \-\-libs \-\-cflags libsystemd)\*(Aq
100 *
101 * To allow the program to take ownership of the name \*(Aqorg\&.freedesktop\&.ReconnectExample\*(Aq,
102 * add the following as /etc/dbus\-1/system\&.d/org\&.freedesktop\&.ReconnectExample\&.conf
103 * and then reload the broker with \*(Aqsystemctl reload dbus\*(Aq:
104
105 <?xml version="1\&.0"?> <!\-\-*\-nxml\-*\-\->
106 <!DOCTYPE busconfig PUBLIC "\-//freedesktop//DTD D\-BUS Bus Configuration 1\&.0//EN"
107 "http://www\&.freedesktop\&.org/standards/dbus/1\&.0/busconfig\&.dtd">
108 <busconfig>
109 <policy user="root">
110 <allow own="org\&.freedesktop\&.ReconnectExample"/>
111 <allow send_destination="org\&.freedesktop\&.ReconnectExample"/>
112 <allow receive_sender="org\&.freedesktop\&.ReconnectExample"/>
113 </policy>
114
115 <policy context="default">
116 <allow send_destination="org\&.freedesktop\&.ReconnectExample"/>
117 <allow receive_sender="org\&.freedesktop\&.ReconnectExample"/>
118 </policy>
119 </busconfig>
120
121 *
122 * To get the property via busctl:
123 *
124 * $ busctl \-\-user get\-property org\&.freedesktop\&.ReconnectExample \e
125 * /org/freedesktop/ReconnectExample \e
126 * org\&.freedesktop\&.ReconnectExample \e
127 * Example
128 * s "example"
129 */
130
131 #include <errno\&.h>
132 #include <stdio\&.h>
133 #include <stdlib\&.h>
134 #include <systemd/sd\-bus\&.h>
135
136 #define _cleanup_(f) __attribute__((cleanup(f)))
137
138 static int log_error(int r, const char *str) {
139 fprintf(stderr, "%s failed: %s\en", str, strerror(\-r));
140 return r;
141 }
142
143 typedef struct object {
144 const char *example;
145 sd_bus **bus;
146 sd_event **event;
147 } object;
148
149 static int property_get(
150 sd_bus *bus,
151 const char *path,
152 const char *interface,
153 const char *property,
154 sd_bus_message *reply,
155 void *userdata,
156 sd_bus_error *error) {
157
158 object *o = userdata;
159
160 if (strcmp(property, "Example") == 0)
161 return sd_bus_message_append(reply, "s", o\->example);
162
163 return sd_bus_error_setf(error,
164 SD_BUS_ERROR_UNKNOWN_PROPERTY,
165 "Unknown property \*(Aq%s\*(Aq",
166 property);
167 }
168
169 /* https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_add_object\&.html */
170 static const sd_bus_vtable vtable[] = {
171 SD_BUS_VTABLE_START(0),
172 SD_BUS_PROPERTY(
173 "Example", "s",
174 property_get,
175 0,
176 SD_BUS_VTABLE_PROPERTY_CONST),
177 SD_BUS_VTABLE_END
178 };
179
180 static int setup(object *o);
181
182 static int on_disconnect(sd_bus_message *message, void *userdata, sd_bus_error *ret_error) {
183 int r;
184
185 r = setup((object *)userdata);
186 if (r < 0) {
187 object *o = userdata;
188 r = sd_event_exit(*o\->event, r);
189 if (r < 0)
190 return log_error(r, "sd_event_exit()");
191 }
192
193 return 1;
194 }
195
196 /* Ensure the event loop exits with a clear error if acquiring the well\-known
197 * service name fails */
198 static int request_name_callback(sd_bus_message *m, void *userdata, sd_bus_error *ret_error) {
199 int r;
200
201 if (!sd_bus_message_is_method_error(m, NULL))
202 return 1;
203
204 const sd_bus_error *error = sd_bus_message_get_error(m);
205
206 if (sd_bus_error_has_names(error, SD_BUS_ERROR_TIMEOUT, SD_BUS_ERROR_NO_REPLY))
207 return 1; /* The bus is not available, try again later */
208
209 fprintf(stderr, "Failed to request name: %s\en", error\->message);
210 object *o = userdata;
211 r = sd_event_exit(*o\->event, \-sd_bus_error_get_errno(error));
212 if (r < 0)
213 return log_error(r, "sd_event_exit()");
214
215 return 1;
216 }
217
218 static int setup(object *o) {
219 int r;
220
221 /* If we are reconnecting, then the bus object needs to be closed, detached
222 * from the event loop and recreated\&.
223 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_detach_event\&.html
224 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_close_unref\&.html
225 */
226 if (*o\->bus) {
227 r = sd_bus_detach_event(*o\->bus);
228 if (r < 0)
229 return log_error(r, "sd_bus_detach_event()");
230 *o\->bus = sd_bus_close_unref(*o\->bus);
231 }
232
233 /* Set up a new bus object for the system bus, configure it to wait for D\-Bus
234 * to be available instead of failing if it is not, and start it\&. All the
235 * following operations are asynchronous and will not block waiting for D\-Bus
236 * to be available\&.
237 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_new\&.html
238 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_set_address\&.html
239 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_set_bus_client\&.html
240 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_negotiate_creds\&.html
241 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_set_watch_bind\&.html
242 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_set_connected_signal\&.html
243 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_start\&.html
244 */
245 r = sd_bus_new(o\->bus);
246 if (r < 0)
247 return log_error(r, "sd_bus_new()");
248 r = sd_bus_set_address(*o\->bus, "unix:path=/run/dbus/system_bus_socket");
249 if (r < 0)
250 return log_error(r, "sd_bus_set_address()");
251 r = sd_bus_set_bus_client(*o\->bus, 1);
252 if (r < 0)
253 return log_error(r, "sd_bus_set_bus_client()");
254 r = sd_bus_negotiate_creds(*o\->bus, 1, SD_BUS_CREDS_UID|SD_BUS_CREDS_EUID|SD_BUS_CREDS_EFFECTIVE_CAPS);
255 if (r < 0)
256 return log_error(r, "sd_bus_negotiate_creds()");
257 r = sd_bus_set_watch_bind(*o\->bus, 1);
258 if (r < 0)
259 return log_error(r, "sd_bus_set_watch_bind()");
260 r = sd_bus_start(*o\->bus);
261 if (r < 0)
262 return log_error(r, "sd_bus_start()");
263
264 /* Publish an interface on the bus, specifying our well\-known object access
265 * path and public interface name\&.
266 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_add_object\&.html
267 * https://dbus\&.freedesktop\&.org/doc/dbus\-tutorial\&.html
268 */
269 r = sd_bus_add_object_vtable(*o\->bus,
270 NULL,
271 "/org/freedesktop/ReconnectExample",
272 "org\&.freedesktop\&.ReconnectExample",
273 vtable,
274 o);
275 if (r < 0)
276 return log_error(r, "sd_bus_add_object_vtable()");
277 /* By default, the service is only assigned an ephemeral name\&. Also add a
278 * well\-known one, so that clients know whom to call\&. This needs to be
279 * asynchronous, as D\-Bus might not be yet available\&. The callback will check
280 * whether the error is expected or not, in case it fails\&.
281 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_request_name\&.html
282 */
283 r = sd_bus_request_name_async(*o\->bus,
284 NULL,
285 "org\&.freedesktop\&.ReconnectExample",
286 0,
287 request_name_callback,
288 o);
289 if (r < 0)
290 return log_error(r, "sd_bus_request_name_async()");
291 /* When D\-Bus is disconnected this callback will be invoked, which will set up
292 * the connection again\&. This needs to be asynchronous, as D\-Bus might not yet
293 * be available\&.
294 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_match_signal_async\&.html
295 */
296 r = sd_bus_match_signal_async(*o\->bus,
297 NULL,
298 "org\&.freedesktop\&.DBus\&.Local",
299 NULL,
300 "org\&.freedesktop\&.DBus\&.Local",
301 "Disconnected",
302 on_disconnect,
303 NULL,
304 o);
305 if (r < 0)
306 return log_error(r, "sd_bus_match_signal_async()");
307 /* Attach the bus object to the event loop so that calls and signals are
308 * processed\&.
309 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_attach_event\&.html
310 */
311 r = sd_bus_attach_event(*o\->bus, *o\->event, 0);
312 if (r < 0)
313 return log_error(r, "sd_bus_attach_event()");
314
315 return 0;
316 }
317
318 int main(int argc, char **argv) {
319 /* The bus should be relinquished before the program terminates\&. The cleanup
320 * attribute allows us to do it nicely and cleanly whenever we exit the block\&.
321 */
322 _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
323 _cleanup_(sd_event_unrefp) sd_event *event = NULL;
324 object o = {
325 \&.example = "example",
326 \&.bus = &bus,
327 \&.event = &event,
328 };
329 int r;
330
331 /* Create an event loop data structure, with default parameters\&.
332 * https://www\&.freedesktop\&.org/software/systemd/man/sd_event_default\&.html
333 */
334 r = sd_event_default(&event);
335 if (r < 0)
336 return log_error(r, "sd_event_default()");
337
338 /* By default, the event loop will terminate when all sources have disappeared,
339 * so we have to keep it \*(Aqoccupied\*(Aq\&. Register signal handling to do so\&.
340 * https://www\&.freedesktop\&.org/software/systemd/man/sd_event_add_signal\&.html
341 */
342 r = sd_event_add_signal(event, NULL, SIGINT|SD_EVENT_SIGNAL_PROCMASK, NULL, NULL);
343 if (r < 0)
344 return log_error(r, "sd_event_add_signal(SIGINT)");
345
346 r = sd_event_add_signal(event, NULL, SIGTERM|SD_EVENT_SIGNAL_PROCMASK, NULL, NULL);
347 if (r < 0)
348 return log_error(r, "sd_event_add_signal(SIGTERM)");
349
350 r = setup(&o);
351 if (r < 0)
352 return EXIT_FAILURE;
353
354 /* Enter the main loop, it will exit only on sigint/sigterm\&.
355 * https://www\&.freedesktop\&.org/software/systemd/man/sd_event_loop\&.html
356 */
357 r = sd_event_loop(event);
358 if (r < 0)
359 return log_error(r, "sd_event_loop()");
360
361 /* https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_release_name\&.html */
362 r = sd_bus_release_name(bus, "org\&.freedesktop\&.ReconnectExample");
363 if (r < 0)
364 return log_error(r, "sd_bus_release_name()");
365
366 return 0;
367 }
368 .fi
369 .if n \{\
370 .RE
371 .\}
372 .PP
373 This is particularly useful for services that are configured to survive a soft\-reboot, see
374 \fBsystemd-soft-reboot.service\fR(8)
375 for more details\&.
376 .SH "HISTORY"
377 .PP
378 \fBsd_bus_set_watch_bind()\fR
379 and
380 \fBsd_bus_get_watch_bind()\fR
381 were added in version 237\&.
382 .SH "SEE ALSO"
383 .PP
384 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBinotify\fR(7), \fBsd_bus_call\fR(3), \fBsd_bus_add_match\fR(3), \fBsd_bus_request_name\fR(3), \fBsd_bus_is_ready\fR(3), \fBsd_bus_set_connected_signal\fR(3)