Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_emit_signal.3

raw
1 '\" t
2 .TH "SD_BUS_EMIT_SIGNAL" "3" "" "systemd 261~rc3" "sd_bus_emit_signal"
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_emit_signal, sd_bus_emit_signalv, sd_bus_emit_signal_to, sd_bus_emit_signal_tov, sd_bus_emit_interfaces_added, sd_bus_emit_interfaces_added_strv, sd_bus_emit_interfaces_removed, sd_bus_emit_interfaces_removed_strv, sd_bus_emit_properties_changed, sd_bus_emit_properties_changed_strv, sd_bus_emit_object_added, sd_bus_emit_object_removed \- Convenience functions for emitting (standard) D\-Bus signals
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-bus\-vtable\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_bus_emit_signal('u
32 .BI "int sd_bus_emit_signal(sd_bus\ *" "bus" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", const\ char\ *" "member" ", const\ char\ *" "types" ", \&.\&.\&.);"
33 .HP \w'int\ sd_bus_emit_signalv('u
34 .BI "int sd_bus_emit_signalv(sd_bus\ *" "bus" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", const\ char\ *" "member" ", const\ char\ *" "types" ", va_list\ " "ap" ");"
35 .HP \w'int\ sd_bus_emit_signal_to('u
36 .BI "int sd_bus_emit_signal_to(sd_bus\ *" "bus" ", const\ char\ *" "destination" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", const\ char\ *" "member" ", const\ char\ *" "types" ", \&.\&.\&.);"
37 .HP \w'int\ sd_bus_emit_signal_tov('u
38 .BI "int sd_bus_emit_signal_tov(sd_bus\ *" "bus" ", const\ char\ *" "destination" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", const\ char\ *" "member" ", const\ char\ *" "types" ", va_list\ " "ap" ");"
39 .HP \w'int\ sd_bus_emit_interfaces_added('u
40 .BI "int sd_bus_emit_interfaces_added(sd_bus\ *" "bus" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", \&.\&.\&.);"
41 .HP \w'int\ sd_bus_emit_interfaces_added_strv('u
42 .BI "int sd_bus_emit_interfaces_added_strv(sd_bus\ *" "bus" ", const\ char\ *" "path" ", char\ **" "interfaces" ");"
43 .HP \w'int\ sd_bus_emit_interfaces_removed('u
44 .BI "int sd_bus_emit_interfaces_removed(sd_bus\ *" "bus" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", \&.\&.\&.);"
45 .HP \w'int\ sd_bus_emit_interfaces_removed_strv('u
46 .BI "int sd_bus_emit_interfaces_removed_strv(sd_bus\ *" "bus" ", const\ char\ *" "path" ", char\ **" "interfaces" ");"
47 .HP \w'int\ sd_bus_emit_properties_changed('u
48 .BI "int sd_bus_emit_properties_changed(sd_bus\ *" "bus" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", const\ char\ *" "name" ", \&.\&.\&.);"
49 .HP \w'int\ sd_bus_emit_properties_changed_strv('u
50 .BI "int sd_bus_emit_properties_changed_strv(sd_bus\ *" "bus" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", char\ **" "names" ");"
51 .HP \w'int\ sd_bus_emit_object_added('u
52 .BI "int sd_bus_emit_object_added(sd_bus\ *" "bus" ", const\ char\ *" "path" ");"
53 .HP \w'int\ sd_bus_emit_object_removed('u
54 .BI "int sd_bus_emit_object_removed(sd_bus\ *" "bus" ", const\ char\ *" "path" ");"
55 .SH "DESCRIPTION"
56 .PP
57 \fBsd_bus_emit_signal()\fR
58 is a convenience function for initializing a bus message object and emitting the corresponding D\-Bus signal\&. It combines the
59 \fBsd_bus_message_new_signal\fR(3),
60 \fBsd_bus_message_append\fR(3)
61 and
62 \fBsd_bus_send\fR(3)
63 functions into a single function call\&.
64 \fBsd_bus_emit_signalv()\fR
65 is equivalent to
66 \fBsd_bus_message_append()\fR, except that it is called with a
67 "va_list"
68 instead of a variable number of arguments\&.
69 .PP
70 \fBsd_bus_emit_signal_to()\fR
71 and
72 \fBsd_bus_emit_signal_tov()\fR
73 are identical to
74 \fBsd_bus_emit_signal()\fR
75 and
76 \fBsd_bus_emit_signalv()\fR, except that they can emit the signal to a single destination\&. Give
77 \fIdestination\fR
78 as
79 \fBNULL\fR
80 to broadcast the signal\&.
81 .PP
82 \fBsd_bus_emit_interfaces_added()\fR
83 and
84 \fBsd_bus_emit_interfaces_removed()\fR
85 are used to implement the
86 \fBInterfacesAdded\fR
87 and
88 \fBInterfacesRemoved\fR
89 signals of the
90 \fBorg\&.freedesktop\&.DBus\&.ObjectManager\fR
91 interface\&. They take a path whose interfaces have been modified as an argument and a variable list of interfaces that have been added or removed, respectively\&. The final argument passed to
92 \fBsd_bus_emit_interfaces_added()\fR
93 and
94 \fBsd_bus_emit_interfaces_removed()\fR
95 \fImust\fR
96 be
97 \fBNULL\fR\&. This allows both functions to safely determine the number of passed interface arguments\&.
98 \fBsd_bus_emit_interfaces_added_strv()\fR
99 and
100 \fBsd_bus_emit_interfaces_removed_strv()\fR
101 are identical to their respective counterparts but both take the list of interfaces as a single argument instead of a variable number of arguments\&.
102 .PP
103 \fBsd_bus_emit_properties_changed()\fR
104 is used to implement the
105 \fBPropertiesChanged\fR
106 signal of the
107 \fBorg\&.freedesktop\&.DBus\&.Properties\fR
108 interface\&. It takes an object path, interface and a variable list of property names as its arguments\&. The final argument passed to
109 \fBsd_bus_emit_properties_changed()\fR
110 \fImust\fR
111 be
112 \fBNULL\fR\&. This allows it to safely determine the number of passed property names\&.
113 \fBsd_bus_emit_properties_changed_strv()\fR
114 is identical to
115 \fBsd_bus_emit_properties_changed()\fR
116 but takes the list of property names as a single argument instead of a variable number of arguments\&.
117 .PP
118 \fBsd_bus_emit_object_added()\fR
119 and
120 \fBsd_bus_emit_object_removed()\fR
121 are convenience functions for emitting the
122 \fBInterfacesAdded\fR
123 or
124 \fBInterfacesRemoved\fR
125 signals for all interfaces registered on a specific object path, respectively\&. This includes any parent fallback vtables if they are not overridden by a more applicable child vtable\&. It also includes all the standard D\-Bus interfaces implemented by sd\-bus itself on any registered object\&.
126 .PP
127 Note that
128 \fBsd_bus_emit_interfaces_added()\fR,
129 \fBsd_bus_emit_interfaces_removed()\fR,
130 \fBsd_bus_emit_object_added()\fR
131 and
132 \fBsd_bus_emit_object_removed()\fR
133 require an object manager to have been registered on the given object path or one of its parent object paths using
134 \fBsd_bus_add_object_manager\fR(3)\&.
135 .SH "RETURN VALUE"
136 .PP
137 On success, these functions return a non\-negative integer\&. On failure, they return a negative errno\-style error code\&.
138 .SS "Errors"
139 .PP
140 Returned errors may indicate the following problems:
141 .PP
142 \fB\-EINVAL\fR
143 .RS 4
144 One of the required parameters is
145 \fBNULL\fR
146 or invalid\&. A reserved D\-Bus interface was passed as the
147 \fIinterface\fR
148 parameter\&.
149 .RE
150 .PP
151 \fB\-ENOPKG\fR
152 .RS 4
153 The bus cannot be resolved\&.
154 .RE
155 .PP
156 \fB\-ECHILD\fR
157 .RS 4
158 The bus was created in a different process, library or module instance\&.
159 .RE
160 .PP
161 \fB\-ENOMEM\fR
162 .RS 4
163 Memory allocation failed\&.
164 .RE
165 .PP
166 \fB\-ESRCH\fR
167 .RS 4
168 One of
169 \fBsd_bus_emit_interfaces_added()\fR,
170 \fBsd_bus_emit_interfaces_removed()\fR,
171 \fBsd_bus_emit_object_added()\fR
172 or
173 \fBsd_bus_emit_object_removed()\fR
174 was called on an object without an object manager registered on its own object path or one of its parent object paths\&.
175 .RE
176 .PP
177 See the man pages of
178 \fBsd_bus_message_new_signal\fR(3),
179 \fBsd_bus_message_append\fR(3)
180 and
181 \fBsd_bus_send\fR(3)
182 for more possible errors\&.
183 .SH "NOTES"
184 .PP
185 Functions described here are available as a shared library, which can be compiled against and linked to with the
186 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
187 file\&.
188 .PP
189 The code described here uses
190 \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
191 \fBsetenv\fR(3)
192 from a parallel thread\&. It is recommended to only do calls to
193 \fBsetenv()\fR
194 from an early phase of the program when no other threads have been started\&.
195 .SH "HISTORY"
196 .PP
197 \fBsd_bus_emit_signal()\fR,
198 \fBsd_bus_emit_interfaces_added()\fR,
199 \fBsd_bus_emit_interfaces_added_strv()\fR,
200 \fBsd_bus_emit_interfaces_removed()\fR,
201 \fBsd_bus_emit_interfaces_removed_strv()\fR,
202 \fBsd_bus_emit_properties_changed()\fR,
203 \fBsd_bus_emit_properties_changed_strv()\fR, were added in version 221\&.
204 .PP
205 \fBsd_bus_emit_object_added()\fR, and
206 \fBsd_bus_emit_object_removed()\fR
207 were added in version 222\&.
208 .PP
209 \fBsd_bus_emit_signalv()\fR
210 was added in version 246\&.
211 .PP
212 \fBsd_bus_emit_signal_to()\fR
213 and
214 \fBsd_bus_emit_signal_tov()\fR
215 were added in version 253\&.
216 .SH "SEE ALSO"
217 .PP
218 \fBsd-bus\fR(3), \fBbusctl\fR(1), \fBsd_bus_message_new_signal\fR(3), \fBsd_bus_message_append\fR(3), \fBsd_bus_send\fR(3), \fBsd_bus_call_method\fR(3)