Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_set_server.3

raw
1 '\" t
2 .TH "SD_BUS_SET_SERVER" "3" "" "systemd 261~rc3" "sd_bus_set_server"
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_server, sd_bus_is_server, sd_bus_get_bus_id, sd_bus_set_bus_client, sd_bus_is_bus_client, sd_bus_set_monitor, sd_bus_is_monitor \- Configure connection mode for a bus object
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_server('u
32 .BI "int sd_bus_set_server(sd_bus\ *" "bus" ", int\ " "b" ", sd_id128_t\ " "id" ");"
33 .HP \w'int\ sd_bus_is_server('u
34 .BI "int sd_bus_is_server(sd_bus\ *" "bus" ");"
35 .HP \w'int\ sd_bus_get_bus_id('u
36 .BI "int sd_bus_get_bus_id(sd_bus\ *" "bus" ", sd_id128_t\ *" "id" ");"
37 .HP \w'int\ sd_bus_set_bus_client('u
38 .BI "int sd_bus_set_bus_client(sd_bus\ *" "bus" ", int\ " "b" ");"
39 .HP \w'int\ sd_bus_is_bus_client('u
40 .BI "int sd_bus_is_bus_client(sd_bus\ *" "bus" ");"
41 .HP \w'int\ sd_bus_set_monitor('u
42 .BI "int sd_bus_set_monitor(sd_bus\ *" "bus" ", int\ " "b" ");"
43 .HP \w'int\ sd_bus_is_monitor('u
44 .BI "int sd_bus_is_monitor(sd_bus\ *" "bus" ");"
45 .SH "DESCRIPTION"
46 .PP
47 \fBsd_bus_set_server()\fR
48 configures the bus object as a server for direct D\-Bus connections\&.
49 \fIb\fR
50 enables/disables the server mode\&. If zero, the server mode is disabled\&. Otherwise, the server mode is enabled\&. Configuring a bus object as a server is required to allow establishing direct connections between two peers without going via the D\-Bus daemon\&.
51 \fIid\fR
52 must contain a 128\-bit integer id for the server\&. If clients add a guid field to their D\-Bus address string, the server id must match this guid or the D\-Bus authentication handshake will fail\&. If no specific id is defined for the server,
53 \fBsd_id128_randomize\fR(3)
54 can be used to generate a random id instead\&.
55 .PP
56 \fBsd_bus_is_server()\fR
57 returns whether the server mode is enabled for the given bus object\&.
58 .PP
59 \fBsd_bus_get_bus_id()\fR
60 stores the D\-Bus server id configured using
61 \fBsd_bus_set_server()\fR
62 (for server bus objects) or received during D\-Bus authentication (for client bus objects) in
63 \fIid\fR\&.
64 .PP
65 \fBsd_bus_set_bus_client()\fR
66 configures the bus object as a D\-Bus daemon client\&.
67 \fIb\fR
68 enables/disables the client mode\&. If zero, the client mode is disabled and the bus object should connect directly to a D\-Bus server\&. Otherwise, the client mode is enabled and the bus object should connect to a D\-Bus daemon\&. When connecting to an existing bus using any of the functions in the
69 \fBsd_bus_open\fR(3)
70 family of functions or any of the functions in the
71 \fBsd_bus_default\fR(3)
72 family of functions, the bus object is automatically configured as a bus client\&. However, when connecting to a D\-Bus daemon by calling
73 \fBsd_bus_set_address\fR(3)
74 followed by
75 \fBsd_bus_start\fR(3), the bus object should be manually configured as a bus client using
76 \fBsd_bus_set_bus_client()\fR\&. By default, a bus object is not configured as a D\-Bus daemon client\&.
77 .PP
78 \fBsd_bus_is_bus_client()\fR
79 returns whether the client mode is enabled/disabled for the given bus object\&.
80 .PP
81 \fBsd_bus_set_monitor()\fR
82 configures the bus object as a D\-Bus monitor object\&.
83 \fIb\fR
84 enables/disables the monitor mode\&. If zero, the monitor mode is disabled\&. If non\-zero, the monitor mode is enabled\&. When the monitor mode is enabled, no messages may be sent via the bus object and it may not expose any objects on the bus\&. To start monitoring messages, call the
85 \fBorg\&.freedesktop\&.DBus\&.Monitoring\&.BecomeMonitor\fR
86 method of the D\-Bus daemon and pass a list of matches indicating which messages to intercept\&. See
87 \m[blue]\fBThe D\-Bus specification\fR\m[]\&\s-2\u[1]\d\s+2
88 for more information\&.
89 .PP
90 \fBsd_bus_is_monitor()\fR
91 returns whether the monitor mode is enabled/disabled for the given bus object\&.
92 .SH "RETURN VALUE"
93 .PP
94 On success,
95 \fBsd_bus_set_server()\fR,
96 \fBsd_bus_get_bus_id()\fR,
97 \fBsd_bus_set_bus_client()\fR
98 and
99 \fBsd_bus_set_monitor()\fR
100 return a non\-negative integer\&. On failure, they return a negative errno\-style error code\&.
101 .PP
102 \fBsd_bus_is_server()\fR,
103 \fBsd_bus_is_bus_client()\fR
104 and
105 \fBsd_bus_is_monitor()\fR
106 return a positive integer when the server or client mode is enabled, respectively\&. Otherwise, they return zero\&.
107 .SS "Errors"
108 .PP
109 Returned errors may indicate the following problems:
110 .PP
111 \fB\-ECHILD\fR
112 .RS 4
113 The bus connection has been created in a different process, library or module instance\&.
114 .sp
115 Added in version 246\&.
116 .RE
117 .PP
118 \fB\-EPERM\fR
119 .RS 4
120 The bus connection has already been started\&.
121 .sp
122 Added in version 246\&.
123 .RE
124 .PP
125 \fB\-ENOPKG\fR
126 .RS 4
127 The bus cannot be resolved\&.
128 .sp
129 Added in version 246\&.
130 .RE
131 .PP
132 \fB\-EINVAL\fR
133 .RS 4
134 A required parameter was
135 \fBNULL\fR
136 or
137 \fIb\fR
138 was zero and
139 \fIid\fR
140 did not equal
141 \fBSD_ID128_NULL\fR\&.
142 .sp
143 Added in version 246\&.
144 .RE
145 .PP
146 \fB\-ENOTCONN\fR
147 .RS 4
148 The bus is not connected\&.
149 .sp
150 Added in version 246\&.
151 .RE
152 .SH "NOTES"
153 .PP
154 Functions described here are available as a shared library, which can be compiled against and linked to with the
155 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
156 file\&.
157 .PP
158 The code described here uses
159 \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
160 \fBsetenv\fR(3)
161 from a parallel thread\&. It is recommended to only do calls to
162 \fBsetenv()\fR
163 from an early phase of the program when no other threads have been started\&.
164 .SH "HISTORY"
165 .PP
166 \fBsd_bus_set_server()\fR,
167 \fBsd_bus_is_server()\fR,
168 \fBsd_bus_get_bus_id()\fR,
169 \fBsd_bus_set_bus_client()\fR,
170 \fBsd_bus_is_bus_client()\fR,
171 \fBsd_bus_set_monitor()\fR, and
172 \fBsd_bus_is_monitor()\fR
173 were added in version 246\&.
174 .SH "SEE ALSO"
175 .PP
176 \fBsystemd\fR(1), \fBsd-bus\fR(3)
177 .SH "NOTES"
178 .IP " 1." 4
179 The D-Bus specification
180 .RS 4
181 \%https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-become-monitor
182 .RE