sd_bus_call_method_asyncv(3)

1SD_BUS_CALL_METHOD(3)         sd_bus_call_method         SD_BUS_CALL_METHOD(3)
2
3
4

NAME

6       sd_bus_call_method, sd_bus_call_methodv, sd_bus_call_method_async,
7       sd_bus_call_method_asyncv - Initialize a bus message object and invoke
8       the corresponding D-Bus method call
9

SYNOPSIS

11       #include <systemd/sd-bus.h>
12
13       typedef int (*sd_bus_message_handler_t)(sd_bus_message *m,
14                                               void *userdata,
15                                               sd_bus_error *ret_error);
16
17       int sd_bus_call_method(sd_bus *bus, const char *destination,
18                              const char *path, const char *interface,
19                              const char *member, sd_bus_error *ret_error,
20                              sd_bus_message **reply, const char *types, ...);
21
22       int sd_bus_call_methodv(sd_bus *bus, const char *destination,
23                               const char *path, const char *interface,
24                               const char *member, sd_bus_error *ret_error,
25                               sd_bus_message **reply, const char *types,
26                               va_list ap);
27
28       int sd_bus_call_method_async(sd_bus *bus, sd_bus_slot **slot,
29                                    const char *destination, const char *path,
30                                    const char *interface, const char *member,
31                                    sd_bus_message_handler_t callback,
32                                    void *userdata, const char *types, ...);
33
34       int sd_bus_call_method_asyncv(sd_bus *bus, sd_bus_slot **slot,
35                                     const char *destination,
36                                     const char *path, const char *interface,
37                                     const char *member,
38                                     sd_bus_message_handler_t callback,
39                                     void *userdata, const char *types,
40                                     va_list ap);
41

DESCRIPTION

43       sd_bus_call_method() is a convenience function for initializing a bus
44       message object and calling the corresponding D-Bus method. It combines
45       the sd_bus_message_new_method_call(3), sd_bus_message_append(3) and
46       sd_bus_call(3) functions into a single function call.
47
48       sd_bus_call_method_async() is a convenience function for initializing a
49       bus message object and calling the corresponding D-Bus method
50       asynchronously. It combines the sd_bus_message_new_method_call(3),
51       sd_bus_message_append(3) and sd_bus_call_async(3) functions into a
52       single function call.
53

RETURN VALUE

55       On success, these functions return a non-negative integer. On failure,
56       they return a negative errno-style error code.
57
58   Errors
59       See the man pages of sd_bus_message_new_method_call(3),
60       sd_bus_message_append(3), sd_bus_call(3) and sd_bus_call_async(3) for a
61       list of possible errors.
62

NOTES

64       Functions described here are available as a shared library, which can
65       be compiled against and linked to with the libsystemd pkg-config(1)
66       file.
67
68       The code described here uses getenv(3), which is declared to be not
69       multi-thread-safe. This means that the code calling the functions
70       described here must not call setenv(3) from a parallel thread. It is
71       recommended to only do calls to setenv() from an early phase of the
72       program when no other threads have been started.
73

EXAMPLES

75       Example 1. Make a call to a D-Bus method that takes a single parameter
76
77           /* SPDX-License-Identifier: MIT-0 */
78
79           /* This is equivalent to:
80            * busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 \
81            *       org.freedesktop.systemd1.Manager GetUnitByPID $$
82            *
83            * Compile with 'cc print-unit-path-call-method.c -lsystemd'
84            */
85
86           #include <errno.h>
87           #include <stdio.h>
88           #include <sys/types.h>
89           #include <unistd.h>
90
91           #include <systemd/sd-bus.h>
92
93           #define _cleanup_(f) __attribute__((cleanup(f)))
94           #define DESTINATION "org.freedesktop.systemd1"
95           #define PATH        "/org/freedesktop/systemd1"
96           #define INTERFACE   "org.freedesktop.systemd1.Manager"
97           #define MEMBER      "GetUnitByPID"
98
99           static int log_error(int error, const char *message) {
100             errno = -error;
101             fprintf(stderr, "%s: %m\n", message);
102             return error;
103           }
104
105           int main(int argc, char **argv) {
106             _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
107             _cleanup_(sd_bus_error_free) sd_bus_error error = SD_BUS_ERROR_NULL;
108             _cleanup_(sd_bus_message_unrefp) sd_bus_message *reply = NULL;
109             int r;
110
111             r = sd_bus_open_system(&bus);
112             if (r < 0)
113               return log_error(r, "Failed to acquire bus");
114
115             r = sd_bus_call_method(bus, DESTINATION, PATH, INTERFACE, MEMBER, &error, &reply, "u", (unsigned) getpid());
116             if (r < 0)
117               return log_error(r, MEMBER " call failed");
118
119             const char *ans;
120             r = sd_bus_message_read(reply, "o", &ans);
121             if (r < 0)
122               return log_error(r, "Failed to read reply");
123
124             printf("Unit path is \"%s\".\n", ans);
125
126             return 0;
127           }
128
129       This defines a minimally useful program that will open a connection to
130       the bus, call a method, wait for the reply, and finally extract and
131       print the answer. It does error handling and proper memory management.
132

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

EXAMPLES

SEE ALSO