Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_message_new_signal.3

raw
1 '\" t
2 .TH "SD_BUS_MESSAGE_NEW_SIGNAL" "3" "" "systemd 261~rc3" "sd_bus_message_new_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_message_new_signal, sd_bus_message_new_signal_to \- Create a signal message
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_message_new_signal('u
32 .BI "int sd_bus_message_new_signal(sd_bus\ *" "bus" ", sd_bus_message\ **" "m" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", const\ char\ *" "member" ");"
33 .HP \w'int\ sd_bus_message_new_signal_to('u
34 .BI "int sd_bus_message_new_signal_to(sd_bus\ *" "bus" ", sd_bus_message\ **" "m" ", const\ char\ *" "destination" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", const\ char\ *" "member" ");"
35 .SH "DESCRIPTION"
36 .PP
37 The
38 \fBsd_bus_message_new_signal()\fR
39 function creates a new bus message object that encapsulates a D\-Bus signal, and returns it in the
40 \fIm\fR
41 output parameter\&. The signal will be sent to path
42 \fIpath\fR, on the interface
43 \fIinterface\fR, member
44 \fImember\fR\&. When this message is sent, no reply is expected\&. See
45 \fBsd_bus_message_new_method_call\fR(3)
46 for a short description of the meaning of the
47 \fIpath\fR,
48 \fIinterface\fR, and
49 \fImember\fR
50 parameters\&.
51 .PP
52 \fBsd_bus_message_new_signal_to()\fR
53 is a shorthand for creating a new bus message to a specific destination\&. It\*(Aqs behavior is similar to calling
54 \fBsd_bus_message_new_signal()\fR
55 followed by calling
56 \fBsd_bus_message_set_destination\fR(3)\&.
57 .SH "RETURN VALUE"
58 .PP
59 This function returns 0 if the message object was successfully created, and a negative errno\-style error code otherwise\&.
60 .SS "Errors"
61 .PP
62 Returned errors may indicate the following problems:
63 .PP
64 \fB\-EINVAL\fR
65 .RS 4
66 The output parameter
67 \fIm\fR
68 is
69 \fBNULL\fR\&.
70 .sp
71 The
72 \fIpath\fR
73 parameter is not a valid D\-Bus path ("/an/object/path"), the
74 \fIinterface\fR
75 parameter is not a valid D\-Bus interface name ("an\&.interface\&.name"), or the
76 \fImember\fR
77 parameter is not a valid D\-Bus member ("Name")\&.
78 .RE
79 .PP
80 \fB\-ENOTCONN\fR
81 .RS 4
82 The bus parameter
83 \fIbus\fR
84 is
85 \fBNULL\fR
86 or the bus is not connected\&.
87 .RE
88 .PP
89 \fB\-ENOMEM\fR
90 .RS 4
91 Memory allocation failed\&.
92 .RE
93 .SH "NOTES"
94 .PP
95 Functions described here are available as a shared library, which can be compiled against and linked to with the
96 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
97 file\&.
98 .PP
99 The code described here uses
100 \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
101 \fBsetenv\fR(3)
102 from a parallel thread\&. It is recommended to only do calls to
103 \fBsetenv()\fR
104 from an early phase of the program when no other threads have been started\&.
105 .SH "EXAMPLES"
106 .PP
107 \fBExample\ \&1.\ \&Send a simple signal\fR
108 .sp
109 .if n \{\
110 .RS 4
111 .\}
112 .nf
113 /* SPDX\-License\-Identifier: MIT\-0 */
114
115 #include <systemd/sd\-bus\&.h>
116 #define _cleanup_(f) __attribute__((cleanup(f)))
117
118 int send_unit_files_changed(sd_bus *bus) {
119 _cleanup_(sd_bus_message_unrefp) sd_bus_message *message = NULL;
120 int r;
121
122 r = sd_bus_message_new_signal(bus, &message,
123 "/org/freedesktop/systemd1",
124 "org\&.freedesktop\&.systemd1\&.Manager",
125 "UnitFilesChanged");
126 if (r < 0)
127 return r;
128
129 return sd_bus_send(bus, message, NULL);
130 }
131 .fi
132 .if n \{\
133 .RE
134 .\}
135 .PP
136 This function in systemd sources is used to emit the
137 "UnitFilesChanged"
138 signal when the unit files have been changed\&.
139 .SH "SEE ALSO"
140 .PP
141 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_emit_signal\fR(3), \fBsd_bus_message_set_destination\fR(3)