Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_message_new_method_call.3

raw
1 '\" t
2 .TH "SD_BUS_MESSAGE_NEW_METHOD_CALL" "3" "" "systemd 261~rc3" "sd_bus_message_new_method_call"
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_method_call, sd_bus_message_new_method_return \- Create a method call 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_method_call('u
32 .BI "int sd_bus_message_new_method_call(sd_bus\ *" "bus" ", sd_bus_message\ **" "m" ", const\ char\ *" "destination" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", const\ char\ *" "member" ");"
33 .HP \w'int\ sd_bus_message_new_method_return('u
34 .BI "int sd_bus_message_new_method_return(sd_bus_message\ *" "call" ", sd_bus_message\ **" "m" ");"
35 .SH "DESCRIPTION"
36 .PP
37 The
38 \fBsd_bus_message_new_method_call()\fR
39 function creates a new bus message object that encapsulates a D\-Bus method call, and returns it in the
40 \fIm\fR
41 output parameter\&. The call will be made on the destination
42 \fIdestination\fR, path
43 \fIpath\fR, on the interface
44 \fIinterface\fR, member
45 \fImember\fR\&.
46 .PP
47 Briefly, the
48 \fIdestination\fR
49 is a dot\-separated name that identifies a service connected to the bus\&. The
50 \fIpath\fR
51 is a slash\-separated identifier of an object within the destination that resembles a file system path\&. The meaning of this path is defined by the destination\&. The
52 \fIinterface\fR
53 is a dot\-separated name that resembles a Java interface name that identifies a group of methods and signals supported by the object identified by path\&. Methods and signals are collectively called
54 \fImembers\fR
55 and are identified by a simple name composed of ASCII letters, numbers, and underscores\&. See the
56 \m[blue]\fBD\-Bus Tutorial\fR\m[]\&\s-2\u[1]\d\s+2
57 for an in\-depth explanation\&.
58 .PP
59 The
60 \fIdestination\fR
61 parameter may be
62 \fBNULL\fR\&. The
63 \fIinterface\fR
64 parameter may be
65 \fBNULL\fR, if the destination has only a single member with the given name and there is no ambiguity if the interface name is omitted\&.
66 .PP
67 Note that this is a low level interface\&. See
68 \fBsd_bus_call_method\fR(3)
69 for a more convenient way of calling D\-Bus methods\&.
70 .PP
71 The
72 \fBsd_bus_message_new_method_return()\fR
73 function creates a new bus message object that is a reply to the method call
74 \fIcall\fR
75 and returns it in the
76 \fIm\fR
77 output parameter\&. The
78 \fIcall\fR
79 parameter must be a method call message\&. The sender of
80 \fIcall\fR
81 is used as the destination\&.
82 .SH "RETURN VALUE"
83 .PP
84 On success, these functions return a non\-negative integer\&. On failure, they return a negative errno\-style error code\&.
85 .SS "Errors"
86 .PP
87 Returned errors may indicate the following problems:
88 .PP
89 \fB\-EINVAL\fR
90 .RS 4
91 The output parameter
92 \fIm\fR
93 is
94 \fBNULL\fR\&.
95 .sp
96 The
97 \fIdestination\fR
98 parameter is non\-null and is not a valid D\-Bus service name ("org\&.somewhere\&.Something"), the
99 \fIpath\fR
100 parameter is not a valid D\-Bus path ("/an/object/path"), the
101 \fIinterface\fR
102 parameter is non\-null and is not a valid D\-Bus interface name ("an\&.interface\&.name"), or the
103 \fImember\fR
104 parameter is not a valid D\-Bus member ("Name")\&.
105 .sp
106 The
107 \fIcall\fR
108 parameter is not a method call object\&.
109 .RE
110 .PP
111 \fB\-ENOTCONN\fR
112 .RS 4
113 The bus parameter
114 \fIbus\fR
115 is
116 \fBNULL\fR
117 or the bus is not connected\&.
118 .RE
119 .PP
120 \fB\-ENOMEM\fR
121 .RS 4
122 Memory allocation failed\&.
123 .RE
124 .PP
125 \fB\-EPERM\fR
126 .RS 4
127 The
128 \fIcall\fR
129 parameter is not sealed\&.
130 .RE
131 .PP
132 \fB\-EOPNOTSUPP\fR
133 .RS 4
134 The
135 \fIcall\fR
136 message does not have a cookie\&.
137 .RE
138 .SH "NOTES"
139 .PP
140 Functions described here are available as a shared library, which can be compiled against and linked to with the
141 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
142 file\&.
143 .PP
144 The code described here uses
145 \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
146 \fBsetenv\fR(3)
147 from a parallel thread\&. It is recommended to only do calls to
148 \fBsetenv()\fR
149 from an early phase of the program when no other threads have been started\&.
150 .SH "EXAMPLES"
151 .PP
152 \fBExample\ \&1.\ \&Make a call to a D\-Bus method that takes a single parameter\fR
153 .sp
154 .if n \{\
155 .RS 4
156 .\}
157 .nf
158 /* SPDX\-License\-Identifier: MIT\-0 */
159
160 /* This is equivalent to:
161 * busctl call org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 \e
162 * org\&.freedesktop\&.systemd1\&.Manager GetUnitByPID $$
163 *
164 * Compile with \*(Aqcc print\-unit\-path\&.c \-lsystemd\*(Aq
165 */
166
167 #include <errno\&.h>
168 #include <stdio\&.h>
169 #include <sys/types\&.h>
170 #include <unistd\&.h>
171
172 #include <systemd/sd\-bus\&.h>
173
174 #define _cleanup_(f) __attribute__((cleanup(f)))
175 #define DESTINATION "org\&.freedesktop\&.systemd1"
176 #define PATH "/org/freedesktop/systemd1"
177 #define INTERFACE "org\&.freedesktop\&.systemd1\&.Manager"
178 #define MEMBER "GetUnitByPID"
179
180 static int log_error(int error, const char *message) {
181 fprintf(stderr, "%s: %s\en", message, strerror(\-error));
182 return error;
183 }
184
185 int main(int argc, char **argv) {
186 _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
187 _cleanup_(sd_bus_error_free) sd_bus_error error = SD_BUS_ERROR_NULL;
188 _cleanup_(sd_bus_message_unrefp) sd_bus_message *reply = NULL, *m = NULL;
189 int r;
190
191 r = sd_bus_open_system(&bus);
192 if (r < 0)
193 return log_error(r, "Failed to acquire bus");
194
195 r = sd_bus_message_new_method_call(bus, &m,
196 DESTINATION, PATH, INTERFACE, MEMBER);
197 if (r < 0)
198 return log_error(r, "Failed to create bus message");
199
200 r = sd_bus_message_append(m, "u", (unsigned) getpid());
201 if (r < 0)
202 return log_error(r, "Failed to append to bus message");
203
204 r = sd_bus_call(bus, m, \-1, &error, &reply);
205 if (r < 0)
206 return log_error(r, MEMBER " call failed");
207
208 const char *ans;
209 r = sd_bus_message_read(reply, "o", &ans);
210 if (r < 0)
211 return log_error(r, "Failed to read reply");
212
213 printf("Unit path is \e"%s\e"\&.\en", ans);
214
215 return 0;
216 }
217 .fi
218 .if n \{\
219 .RE
220 .\}
221 .PP
222 This defines a minimally useful program that will open a connection to the bus, create a message object, send it, wait for the reply, and finally extract and print the answer\&. It does error handling and proper memory management\&.
223 .SH "HISTORY"
224 .PP
225 \fBsd_bus_message_new_method_call()\fR
226 and
227 \fBsd_bus_message_new_method_return()\fR
228 were added in version 246\&.
229 .SH "SEE ALSO"
230 .PP
231 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_call\fR(3), \fBsd_bus_call_method\fR(3), \fBsd_bus_path_encode\fR(3)
232 .SH "NOTES"
233 .IP " 1." 4
234 D-Bus Tutorial
235 .RS 4
236 \%https://dbus.freedesktop.org/doc/dbus-tutorial.html#concepts
237 .RE