1SD_BUS_SET_SERVER(3) sd_bus_set_server SD_BUS_SET_SERVER(3)
2
6 sd_bus_set_server, sd_bus_is_server, sd_bus_get_bus_id,
7 sd_bus_set_bus_client, sd_bus_is_bus_client, sd_bus_set_monitor,
8 sd_bus_is_monitor - Configure connection mode for a bus object
9
11 #include <systemd/sd-bus.h>
12 int sd_bus_set_server(sd_bus *bus, int b, sd_id128_t id);
14 int sd_bus_is_server(sd_bus *bus);
16 int sd_bus_get_bus_id(sd_bus *bus, sd_id128_t *id);
18 int sd_bus_set_bus_client(sd_bus *bus, int b);
20 int sd_bus_is_bus_client(sd_bus *bus);
22 int sd_bus_set_monitor(sd_bus *bus, int b);
24 int sd_bus_is_monitor(sd_bus *bus);
26
28 sd_bus_set_server() configures the bus object as a server for direct
29 D-Bus connections. b enables/disables the server mode. If zero, the
30 server mode is disabled. Otherwise, the server mode is enabled.
31 Configuring a bus object as a server is required to allow establishing
32 direct connections between two peers without going via the D-Bus
33 daemon. id must contain a 128-bit integer id for the server. If
34 clients add a guid field to their D-Bus address string, the server id
35 must match this guid or the D-Bus authentication handshake will fail.
36 If no specific id is defined for the server, sd_id128_randomize(3) can
37 be used to generate a random id instead.
38 sd_bus_is_server() returns whether the server mode is enabled for the
40 given bus object.
41 sd_bus_get_bus_id() stores the D-Bus server id configured using
43 sd_bus_set_server() (for server bus objects) or received during D-Bus
44 authentication (for client bus objects) in id.
45 sd_bus_set_bus_client() configures the bus object as a D-Bus daemon
47 client. b enables/disables the client mode. If zero, the client mode
48 is disabled and the bus object should connect directly to a D-Bus
49 server. Otherwise, the client mode is enabled and the bus object should
50 connect to a D-Bus daemon. When connecting to an existing bus using any
51 of the functions in the sd_bus_open(3) family of functions or any of
52 the functions in the sd_bus_default(3) family of functions, the bus
53 object is automatically configured as a bus client. However, when
54 connecting to a D-Bus daemon by calling sd_bus_set_address(3) followed
55 by sd_bus_start(3), the bus object should be manually configured as a
56 bus client using sd_bus_set_bus_client(). By default, a bus object is
57 not configured as a D-Bus daemon client.
58 sd_bus_is_bus_client() returns whether the client mode is
60 enabled/disabled for the given bus object.
61 sd_bus_set_monitor() configures the bus object as a D-Bus monitor
63 object. b enables/disables the monitor mode. If zero, the monitor mode
64 is disabled. If non-zero, the monitor mode is enabled. When the monitor
65 mode is enabled, no messages may be sent via the bus object and it may
66 not expose any objects on the bus. To start monitoring messages, call
67 the org.freedesktop.DBus.Monitoring.BecomeMonitor method of the D-Bus
68 daemon and pass a list of matches indicating which messages to
69 intercept. See The D-Bus specification[1] for more information.
70 sd_bus_is_monitor() returns whether the monitor mode is
72 enabled/disabled for the given bus object.
73
75 On success, sd_bus_set_server(), sd_bus_get_bus_id(),
76 sd_bus_set_bus_client() and sd_bus_set_monitor() return a non-negative
77 integer. On failure, they return a negative errno-style error code.
78 sd_bus_is_server(), sd_bus_is_bus_client() and sd_bus_is_monitor()
80 return a positive integer when the server or client mode is enabled,
81 respectively. Otherwise, they return zero.
82 Errors
84 Returned errors may indicate the following problems:
85 -ECHILD
87 The bus connection has been created in a different process, library
88 or module instance.
89 -EPERM
91 The bus connection has already been started.
92 -ENOPKG
94 The bus cannot be resolved.
95 -EINVAL
97 A required parameter was NULL or b was zero and id did not equal
98 SD_ID128_NULL.
99 -ENOTCONN
101 The bus is not connected.
102
104 Functions described here are available as a shared library, which can
105 be compiled against and linked to with the libsystemd pkg-config(1)
106 file.
107 The code described here uses getenv(3), which is declared to be not
109 multi-thread-safe. This means that the code calling the functions
110 described here must not call setenv(3) from a parallel thread. It is
111 recommended to only do calls to setenv() from an early phase of the
112 program when no other threads have been started.
113
115 systemd(1), sd-bus(3)
116
118 1. The D-Bus specification
119 https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-become-monitor
120systemd 254 SD_BUS_SET_SERVER(3)