From e8b84fcca67007b518118783b10347f569e0f0f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 24 Jul 2018 23:23:29 +0200 Subject: [PATCH 01/18] man: add sd_bus_message_new_signal(3) --- man/rules/meson.build | 1 + man/sd-bus.xml | 1 + man/sd_bus_message_new_signal.xml | 116 ++++++++++++++++++++++++++++++ man/send-unit-files-changed.c | 16 +++++ 4 files changed, 134 insertions(+) create mode 100644 man/sd_bus_message_new_signal.xml create mode 100644 man/send-unit-files-changed.c diff --git a/man/rules/meson.build b/man/rules/meson.build index 305876f72b..df7ea47470 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -216,6 +216,7 @@ manpages = [ 'sd_bus_message_new_method_errnof', 'sd_bus_message_new_method_errorf'], ''], + ['sd_bus_message_new_signal', '3', [], ''], ['sd_bus_message_read', '3', ['sd_bus_message_readv'], ''], ['sd_bus_message_read_basic', '3', [], ''], ['sd_bus_message_set_destination', '3', ['sd_bus_message_set_sender'], ''], diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 8c7b60743c..6210f40dc2 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -61,6 +61,7 @@ sd_bus_message_get_cookie3, sd_bus_message_get_monotonic_usec3, sd_bus_message_new_method_error3, +sd_bus_message_new_signal3, sd_bus_message_read_basic3, sd_bus_message_read3, sd_bus_message_set_destination3, diff --git a/man/sd_bus_message_new_signal.xml b/man/sd_bus_message_new_signal.xml new file mode 100644 index 0000000000..1c7629c149 --- /dev/null +++ b/man/sd_bus_message_new_signal.xml @@ -0,0 +1,116 @@ + + + + + + + + sd_bus_message_new_signal + systemd + + + + sd_bus_message_new_signal + 3 + + + + sd_bus_message_new_signal + + Create a signal message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_new_signal + sd_bus *bus + sd_bus_message **m + const char *path + const char *interface + const char *member + + + + + + Description + + The sd_bus_message_new_signal() function creates a new bus message + object that encapsulates a D-Bus signal, and returns it in the m output + parameter. The signal will be sent to path path, on the interface + interface, member member. When this message is + sent, no reply is expected. + + + + Return Value + + This function returns 0 if the message object was successfully created, and a negative + errno-style error code otherwise. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + The output parameter m is + NULL. + + The path parameter is not a valid D-Bus path + (/an/object/path), the interface parameter is not + a valid D-Bus interface name (an.interface.name), or the + member parameter is not a valid D-Bus member + (Name). + + + + -ENOTCONN + + The bus parameter bus is NULL or + the bus is not connected. + + + + -ENOMEM + + Memory allocation failed. + + + + + + + + Examples + + + Send a simple signal + + + + This function in systemd sources is used to emit the + UnitFilesChanged signal when the unit files have been changed. + + + + + + See Also + + + systemd1, + sd-bus3 + + + + diff --git a/man/send-unit-files-changed.c b/man/send-unit-files-changed.c new file mode 100644 index 0000000000..aecfbcbed1 --- /dev/null +++ b/man/send-unit-files-changed.c @@ -0,0 +1,16 @@ +#include +#define _cleanup_(f) __attribute__((cleanup(f))) + +int send_unit_files_changed(sd_bus *bus) { + _cleanup_(sd_bus_message_unrefp) sd_bus_message *message = NULL; + int r; + + r = sd_bus_message_new_signal(bus, &message, + "/org/freedesktop/systemd1", + "org.freedesktop.systemd1.Manager", + "UnitFilesChanged"); + if (r < 0) + return r; + + return sd_bus_send(bus, message, NULL); +} From cfe8ee463d6f3a6aaeb819e4044e56f13c534bde Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 26 Jul 2018 20:00:36 +0200 Subject: [PATCH 02/18] man: add sd_bus_message_new_call(3) --- man/print-unit-path.c | 64 ++++++++++++ man/rules/meson.build | 1 + man/sd-bus.xml | 1 + man/sd_bus_message_new_method_call.xml | 134 +++++++++++++++++++++++++ man/sd_bus_message_new_signal.xml | 6 +- man/sd_bus_path_encode.xml | 2 +- 6 files changed, 206 insertions(+), 2 deletions(-) create mode 100644 man/print-unit-path.c create mode 100644 man/sd_bus_message_new_method_call.xml diff --git a/man/print-unit-path.c b/man/print-unit-path.c new file mode 100644 index 0000000000..23b58a26e2 --- /dev/null +++ b/man/print-unit-path.c @@ -0,0 +1,64 @@ +#include +#include +#include +#include + +#include +#define _cleanup_(f) __attribute__((cleanup(f))) + +/* This is equivalent to: + * busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 \ + * org.freedesktop.systemd1.Manager GetUnitByPID $$ + * + * Compile with 'cc -lsystemd print-unit-path.c' + */ + +#define DESTINATION "org.freedesktop.systemd1" +#define PATH "/org/freedesktop/systemd1" +#define INTERFACE "org.freedesktop.systemd1.Manager" +#define MEMBER "GetUnitByPID" + +static int log_error(int error, const char *message) { + fprintf(stderr, "%s: %s\n", message, strerror(-error)); + return error; +} + +static int print_unit_path(sd_bus *bus) { + _cleanup_(sd_bus_message_unrefp) sd_bus_message *m = NULL; + _cleanup_(sd_bus_error_free) sd_bus_error error = SD_BUS_ERROR_NULL; + _cleanup_(sd_bus_message_unrefp) sd_bus_message *reply = NULL; + int r; + + r = sd_bus_message_new_method_call(bus, &m, + DESTINATION, PATH, INTERFACE, MEMBER); + if (r < 0) + return log_error(r, "Failed to create bus message"); + + r = sd_bus_message_append(m, "u", (unsigned) getpid()); + if (r < 0) + return log_error(r, "Failed to append to bus message"); + + r = sd_bus_call(bus, m, -1, &error, &reply); + if (r < 0) + return log_error(r, "Call failed"); + + const char *ans; + r = sd_bus_message_read(reply, "o", &ans); + if (r < 0) + return log_error(r, "Failed to read reply"); + + printf("Unit path is \"%s\".\n", ans); + + return 0; +} + +int main(int argc, char **argv) { + _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL; + int r; + + r = sd_bus_open_system(&bus); + if (r < 0) + return log_error(r, "Failed to acquire bus"); + + print_unit_path(bus); +} diff --git a/man/rules/meson.build b/man/rules/meson.build index df7ea47470..1c56e75fd4 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -210,6 +210,7 @@ manpages = [ '3', ['sd_bus_message_get_realtime_usec', 'sd_bus_message_get_seqnum'], ''], + ['sd_bus_message_new_method_call', '3', [], ''], ['sd_bus_message_new_method_error', '3', ['sd_bus_message_new_method_errno', diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 6210f40dc2..5a3502601c 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -60,6 +60,7 @@ sd_bus_message_copy3, sd_bus_message_get_cookie3, sd_bus_message_get_monotonic_usec3, +sd_bus_message_new_method_call3, sd_bus_message_new_method_error3, sd_bus_message_new_signal3, sd_bus_message_read_basic3, diff --git a/man/sd_bus_message_new_method_call.xml b/man/sd_bus_message_new_method_call.xml new file mode 100644 index 0000000000..1226f1050c --- /dev/null +++ b/man/sd_bus_message_new_method_call.xml @@ -0,0 +1,134 @@ + + + + + + + + sd_bus_message_new_method_call + systemd + + + + sd_bus_message_new_method_call + 3 + + + + sd_bus_message_new_method_call + + Create a method call message + + + + + #include <systemd/sd-bus.h> + + + 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 + + + + + + Description + + The sd_bus_message_new_method_call() function creates a new bus + message object that encapsulates a D-Bus method call, and returns it in the + m output parameter. The call will be made on the destination + destination, path path, on the interface + interface, member member. + + Briefly, the destination is a dot-separated name that identifies a + service connected to the bus. The path 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 interface 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 + members and are identified by a simple name composed of ASCII letters, + numbers, and underscores. See the D-Bus Tutorial for an + in-depth explanation. + + The destination parameter may be NULL. The + interface parameter may be NULL, if the destination + has only a single member with the given name and there is no ambiguity if the interface name is + omitted. + + + + Return Value + + This function returns 0 if the message object was successfully created, and a negative + errno-style error code otherwise. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + The output parameter m is + NULL. + + The destination parameter is non-null and is not a valid D-Bus + service name (org.somewhere.Something), the path + parameter is not a valid D-Bus path (/an/object/path), the + interface parameter is non-null and is not a valid D-Bus interface + name (an.interface.name), or the member parameter + is not a valid D-Bus member (Name). + + + + -ENOTCONN + + The bus parameter bus is NULL or + the bus is not connected. + + + + -ENOMEM + + Memory allocation failed. + + + + + + + + Examples + + + Make a call to a D-Bus method that takes a single parameter + + + 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. + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_path_encode3 + + + + diff --git a/man/sd_bus_message_new_signal.xml b/man/sd_bus_message_new_signal.xml index 1c7629c149..c9ed0bc4a4 100644 --- a/man/sd_bus_message_new_signal.xml +++ b/man/sd_bus_message_new_signal.xml @@ -44,7 +44,11 @@ object that encapsulates a D-Bus signal, and returns it in the m output parameter. The signal will be sent to path path, on the interface interface, member member. When this message is - sent, no reply is expected. + sent, no reply is expected. See + sd_bus_message_new_call1 + for a short description of the meaning of the path, + interface, and member parameters. + diff --git a/man/sd_bus_path_encode.xml b/man/sd_bus_path_encode.xml index 55c7010e73..4c60a8fa3e 100644 --- a/man/sd_bus_path_encode.xml +++ b/man/sd_bus_path_encode.xml @@ -80,7 +80,7 @@ always be NUL-terminated. The returned string will be the concatenation of the bus path prefix plus an escaped version of the external identifier string. This operation may be - reversed with sd_bus_decode(). It is + reversed with sd_bus_path_decode(). It is recommended to only use external identifiers that generally require little escaping to be turned into valid bus path identifiers (for example, by sticking to a 7-bit ASCII character From 2c47fff6d2d9750ddf9e97fc45714aa8984b5eb6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 27 Jul 2018 08:06:07 +0200 Subject: [PATCH 03/18] man: clarify what can be NULL in an sd_bus_unrefp call Confusingly, the argument is called 'bus' in all cases. Let's not give people the idea to call sd_bus_unrefp(NULL). --- man/sd_bus_new.xml | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml index b095518f8f..5180ae7815 100644 --- a/man/sd_bus_new.xml +++ b/man/sd_bus_new.xml @@ -48,7 +48,7 @@ void sd_bus_unrefp - sd_bus **bus + sd_bus **busp @@ -105,10 +105,12 @@ … } - sd_bus_ref(), - sd_bus_unref() and - sd_bus_unrefp() execute no operation if the - passed in bus object is NULL. + sd_bus_ref() and sd_bus_unref() + execute no operation if the passed in bus object address is + NULL. sd_bus_unrefp() will first + dereference its argument, which must not be NULL, and will + execute no operation if that is NULL. + From 787f78b6a106d34bbf52eabb02995733ea6a7d4d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 27 Jul 2018 08:24:45 +0200 Subject: [PATCH 04/18] man: move more examples to stand-alone files and use 2-space indentation consistenty Moving them out makes it easier to run them through a compiler, use automatic indentation, and opens the possibility to provide a download link in the future. I verified that all examples compile cleanly. (2-space indentation is used because the examples are already significantly indented in the man page, and we need to keep them narrow so that they display well on standard terminals.) --- man/id128-app-specific.c | 11 +++++++++++ man/journal-iterate-unique.c | 25 +++++++++++++++++++++++++ man/sd_bus_new.xml | 14 +++++++------- man/sd_id128_get_machine.xml | 12 +----------- man/sd_journal_query_unique.xml | 27 +-------------------------- man/sd_login_monitor_new.xml | 26 +++++++++++++------------- 6 files changed, 58 insertions(+), 57 deletions(-) create mode 100644 man/id128-app-specific.c create mode 100644 man/journal-iterate-unique.c diff --git a/man/id128-app-specific.c b/man/id128-app-specific.c new file mode 100644 index 0000000000..b81e50ff32 --- /dev/null +++ b/man/id128-app-specific.c @@ -0,0 +1,11 @@ +#include +#include + +#define OUR_APPLICATION_ID SD_ID128_MAKE(c2,73,27,73,23,db,45,4e,a6,3b,b9,6e,79,b5,3e,97) + +int main(int argc, char *argv[]) { + sd_id128_t id; + sd_id128_get_machine_app_specific(OUR_APPLICATION_ID, &id); + printf("Our application ID: " SD_ID128_FORMAT_STR "\n", SD_ID128_FORMAT_VAL(id)); + return 0; +} diff --git a/man/journal-iterate-unique.c b/man/journal-iterate-unique.c new file mode 100644 index 0000000000..fcf92e7b3f --- /dev/null +++ b/man/journal-iterate-unique.c @@ -0,0 +1,25 @@ +#include +#include +#include + +int main(int argc, char *argv[]) { + sd_journal *j; + const void *d; + size_t l; + int r; + + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + r = sd_journal_query_unique(j, "_SYSTEMD_UNIT"); + if (r < 0) { + fprintf(stderr, "Failed to query journal: %s\n", strerror(-r)); + return 1; + } + SD_JOURNAL_FOREACH_UNIQUE(j, d, l) + printf("%.*s\n", (int) l, (const char*) d); + sd_journal_close(j); + return 0; +} diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml index 5180ae7815..59117676fd 100644 --- a/man/sd_bus_new.xml +++ b/man/sd_bus_new.xml @@ -96,13 +96,13 @@ block is left: { - __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL; - int r; - … - r = sd_bus_default(&bus); - if (r < 0) - fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r)); - … + __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL; + int r; + … + r = sd_bus_default(&bus); + if (r < 0) + fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r)); + … } sd_bus_ref() and sd_bus_unref() diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml index 954fd2e6a7..9587aa7d66 100644 --- a/man/sd_id128_get_machine.xml +++ b/man/sd_id128_get_machine.xml @@ -120,17 +120,7 @@ Here's a simple example for an application specific machine ID: - #include <systemd/sd-id128.h> -#include <stdio.h> - -#define OUR_APPLICATION_ID SD_ID128_MAKE(c2,73,27,73,23,db,45,4e,a6,3b,b9,6e,79,b5,3e,97) - -int main(int argc, char *argv[]) { - sd_id128_t id; - sd_id128_get_machine_app_specific(OUR_APPLICATION_ID, &id); - printf("Our application ID: " SD_ID128_FORMAT_STR "\n", SD_ID128_FORMAT_VAL(id)); - return 0; -} + diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml index 0bbc479f22..c62f333eab 100644 --- a/man/sd_journal_query_unique.xml +++ b/man/sd_journal_query_unique.xml @@ -140,32 +140,7 @@ following example lists all unit names referenced in the journal: - #include <stdio.h> -#include <string.h> -#include <systemd/sd-journal.h> - -int main(int argc, char *argv[]) { - sd_journal *j; - const void *d; - size_t l; - int r; - - r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); - if (r < 0) { - fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); - return 1; - } - r = sd_journal_query_unique(j, "_SYSTEMD_UNIT"); - if (r < 0) { - fprintf(stderr, "Failed to query journal: %s\n", strerror(-r)); - return 1; - } - SD_JOURNAL_FOREACH_UNIQUE(j, d, l) - printf("%.*s\n", (int) l, (const char*) d); - sd_journal_close(j); - return 0; -} - + diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml index 23f685bb31..d914e51d0d 100644 --- a/man/sd_login_monitor_new.xml +++ b/man/sd_login_monitor_new.xml @@ -115,13 +115,13 @@ code block is left: { - __attribute__((cleanup(sd_login_monitor_unrefp)) sd_login_monitor *m = NULL; - int r; - … - r = sd_login_monitor_default(&m); - if (r < 0) - fprintf(stderr, "Failed to allocate login monitor object: %s\n", strerror(-r)); - … + __attribute__((cleanup(sd_login_monitor_unrefp)) sd_login_monitor *m = NULL; + int r; + … + r = sd_login_monitor_default(&m); + if (r < 0) + fprintf(stderr, "Failed to allocate login monitor object: %s\n", strerror(-r)); + … } sd_login_monitor_flush() may be used to @@ -176,13 +176,13 @@ int msec; sd_login_monitor_get_timeout(m, &t); if (t == (uint64_t) -1) - msec = -1; + msec = -1; else { - struct timespec ts; - uint64_t n; - clock_gettime(CLOCK_MONOTONIC, &ts); - n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; - msec = t > n ? (int) ((t - n + 999) / 1000) : 0; + struct timespec ts; + uint64_t n; + clock_gettime(CLOCK_MONOTONIC, &ts); + n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; + msec = t > n ? (int) ((t - n + 999) / 1000) : 0; } The code above does not do any error checking for brevity's From 206ed9c1f6a2aaa71522f4b67604c1cb9384f14f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 27 Jul 2018 09:03:04 +0200 Subject: [PATCH 05/18] man: add sd_bus_message_new(3) --- man/rules/meson.build | 10 +++ man/sd-bus.xml | 1 + man/sd_bus_message_new.xml | 178 +++++++++++++++++++++++++++++++++++++ 3 files changed, 189 insertions(+) create mode 100644 man/sd_bus_message_new.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index 1c56e75fd4..6cb2e7ffb1 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -210,6 +210,16 @@ manpages = [ '3', ['sd_bus_message_get_realtime_usec', 'sd_bus_message_get_seqnum'], ''], + ['sd_bus_message_new', + '3', + ['SD_BUS_MESSAGE_METHOD_CALL', + 'SD_BUS_MESSAGE_METHOD_ERROR', + 'SD_BUS_MESSAGE_METHOD_RETURN', + 'SD_BUS_MESSAGE_SIGNAL', + 'sd_bus_message_ref', + 'sd_bus_message_unref', + 'sd_bus_message_unrefp'], + ''], ['sd_bus_message_new_method_call', '3', [], ''], ['sd_bus_message_new_method_error', '3', diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 5a3502601c..6f58b001c0 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -60,6 +60,7 @@ sd_bus_message_copy3, sd_bus_message_get_cookie3, sd_bus_message_get_monotonic_usec3, +sd_bus_message_new3, sd_bus_message_new_method_call3, sd_bus_message_new_method_error3, sd_bus_message_new_signal3, diff --git a/man/sd_bus_message_new.xml b/man/sd_bus_message_new.xml new file mode 100644 index 0000000000..e7cb0c5791 --- /dev/null +++ b/man/sd_bus_message_new.xml @@ -0,0 +1,178 @@ + + + + + + + sd_bus_message_new + systemd + + + + sd_bus_message_new + 3 + + + + sd_bus_message_new + sd_bus_message_ref + sd_bus_message_unref + sd_bus_message_unrefp + SD_BUS_MESSAGE_METHOD_CALL + SD_BUS_MESSAGE_METHOD_RETURN + SD_BUS_MESSAGE_METHOD_ERROR + SD_BUS_MESSAGE_SIGNAL + + Create a new bus message object and create or destroy references to it + + + + + #include <systemd/sd-bus.h> + + enum { + SD_BUS_MESSAGE_METHOD_CALL, + SD_BUS_MESSAGE_METHOD_RETURN, + SD_BUS_MESSAGE_METHOD_ERROR, + SD_BUS_MESSAGE_SIGNAL, +}; + + + int sd_bus_message_new + sd_bus *bus + sd_bus_message **m + uint8_t type + + + + sd_bus_message *sd_bus_message_ref + sd_bus_message *m + + + + sd_bus_message *sd_bus_message_unref + sd_bus_message *m + + + + void sd_bus_message_unrefp + sd_bus_message **mp + + + + + + Description + + sd_bus_message_new() creates a new bus message object attached to the + bus bus and returns it in the output parameter m. + This object is reference-counted, and will be destroyed when all references are gone. Initially, + the caller of this function owns the sole reference to the message object. Note that the message + object holds a reference to the bus object, so the bus object will not be destroyed as long as + the message exists. + + Note: this is a low-level call. In most cases functions like + sd_bus_message_new_method_call3, + sd_bus_message_new_method_error3, + sd_bus_message_new_method_return3, + and sd_bus_message_new_signal3 + that create a message of a certain type and initialize various fields are easier to use. + + The type parameter specifies the type of the message. It must be + one of SD_BUS_MESSAGE_METHOD_CALL — a method call, + SD_BUS_MESSAGE_METHOD_RETURN — a method call reply, + SD_BUS_MESSAGE_METHOD_ERROR — an error reply to a method call, + SD_BUS_MESSAGE_SIGNAL — a broadcast message with no reply. + + + The flag to allow interactive authorization is initialized based on the current value set + in the bus object, see + sd_bus_set_allow_interactive_authorization3. + This may be changed using + sd_bus_message_set_allow_interactive_authorization3. + + + sd_bus_message_ref() increases the reference counter of + m by one. + + sd_bus_message_unref() decreases the reference counter of + m by one. Once the reference count has dropped to zero, message object is + destroyed and cannot be used anymore, so further calls to + sd_bus_message_ref() or sd_bus_message_unref() are + illegal. + + sd_bus_message_unrefp() is similar to + sd_bus_message_unref() but takes a pointer to a + pointer to an sd_bus_message object. This call is useful in + conjunction with GCC's and LLVM's Clean-up + Variable Attribute. See + sd_bus_new3 + for an example how to use the cleanup attribute. + + sd_bus_message_ref() and sd_bus_message_unref() + execute no operation if the passed in bus object address is + NULL. sd_bus_message_unrefp() will first dereference + its argument, which must not be NULL, and will execute no operation if + that is NULL. + + + + + Return Value + + On success, sd_bus_message_new() returns 0 or a positive integer. On + failure, it returns a negative errno-style error code. + + sd_bus_message_ref() always returns the argument. + + + sd_bus_message_unref() always returns + NULL. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + Specified type is invalid. + + + + -ENOTCONN + + The bus parameter bus is NULL or + the bus is not connected. + + + + -ENOMEM + + Memory allocation failed. + + + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_new3, + sd_bus_message_new_method_call3, + sd_bus_message_new_method_error3, + sd_bus_message_new_method_return3, + sd_bus_message_new_signal3 + + + + From f00ded93e04af7a6a1d4502f7a0b87d65cf0cdb7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 27 Jul 2018 09:56:43 +0200 Subject: [PATCH 06/18] man: document *_with_description functions --- man/rules/meson.build | 5 ++++- man/sd_bus_default.xml | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+), 1 deletion(-) diff --git a/man/rules/meson.build b/man/rules/meson.build index 6cb2e7ffb1..8a69d046bf 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -166,7 +166,10 @@ manpages = [ 'sd_bus_open_system', 'sd_bus_open_system_machine', 'sd_bus_open_system_remote', - 'sd_bus_open_user'], + 'sd_bus_open_system_with_description', + 'sd_bus_open_user', + 'sd_bus_open_user_with_description', + 'sd_bus_open_with_description'], ''], ['sd_bus_error', '3', diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml index 0d3532f3c7..73ad568b91 100644 --- a/man/sd_bus_default.xml +++ b/man/sd_bus_default.xml @@ -24,8 +24,11 @@ sd_bus_default_system sd_bus_open + sd_bus_open_with_description sd_bus_open_user + sd_bus_open_user_with_description sd_bus_open_system + sd_bus_open_system_with_description sd_bus_open_system_remote sd_bus_open_system_machine @@ -56,16 +59,34 @@ sd_bus **bus + + int sd_bus_open_with_description + sd_bus **bus + const char *description + + int sd_bus_open_user sd_bus **bus + + int sd_bus_open_user_with_description + sd_bus **bus + const char *description + + int sd_bus_open_system sd_bus **bus + + int sd_bus_open_system_with_description + sd_bus **bus + const char *description + + int sd_bus_open_system_remote sd_bus **bus @@ -126,6 +147,20 @@ sd_bus_default_system() to connect to the user or system buses. + sd_bus_open_with_description(), + sd_bus_open_user_with_description(), and + sd_bus_open_system_with_description() are similar to + sd_bus_open(), sd_bus_open_user(), and + sd_bus_open_system(), but allow a description string to be set, see + sd_bus_set_description3. + description may be NULL, in which case this function + is equivalent to sd_bus_open(). This description string is used in log + messages about the bus object, and including a "name" for the bus makes them easier to + understand. Some messages are emitted during bus initialization, hence using this function is + prefereable to setting the description later with + sd_bus_open_with_description(). The argument is copied internally and will + not be referenced after the function returns. + If the $DBUS_SESSION_BUS_ADDRESS environment variable is set (cf. environ7), From 65889ab72d4e7f265dedb7d4720f3f470e3e802e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 27 Jul 2018 10:32:20 +0200 Subject: [PATCH 07/18] meson: print stats in check-api-docs --- tools/meson-check-api-docs.sh | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/tools/meson-check-api-docs.sh b/tools/meson-check-api-docs.sh index 5bc808c1e4..a654368f9e 100755 --- a/tools/meson-check-api-docs.sh +++ b/tools/meson-check-api-docs.sh @@ -2,10 +2,33 @@ set -eu +sd_good=0 +sd_total=0 +udev_good=0 +udev_total=0 + for symbol in `nm -g --defined-only "$@" | grep " T " | cut -d" " -f3 | sort -u` ; do if test -f ${MESON_BUILD_ROOT}/man/$symbol.3 ; then echo "✓ Symbol $symbol() is documented." + good=1 else printf " \x1b[1;31mSymbol $symbol() lacks documentation.\x1b[0m\n" + good=0 fi + + case $symbol in + sd_*) + ((sd_good+=good)) + ((sd_total+=1)) + ;; + udev_*) + ((udev_good+=good)) + ((udev_total+=1)) + ;; + *) + echo 'unknown symbol prefix' + exit 1 + esac done + +echo "libsystemd: $sd_good/$sd_total libudev: $udev_good/$udev_total" From 7ddee2171627d6ce059a6a66b46b0b4367b77bd5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 27 Jul 2018 14:07:02 +0200 Subject: [PATCH 08/18] man: document sd_bus_message_new_method_return --- man/rules/meson.build | 5 +++- man/sd_bus_message_new_method_call.xml | 34 +++++++++++++++++++++++++- 2 files changed, 37 insertions(+), 2 deletions(-) diff --git a/man/rules/meson.build b/man/rules/meson.build index 8a69d046bf..7ddd415c58 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -223,7 +223,10 @@ manpages = [ 'sd_bus_message_unref', 'sd_bus_message_unrefp'], ''], - ['sd_bus_message_new_method_call', '3', [], ''], + ['sd_bus_message_new_method_call', + '3', + ['sd_bus_message_new_method_return'], + ''], ['sd_bus_message_new_method_error', '3', ['sd_bus_message_new_method_errno', diff --git a/man/sd_bus_message_new_method_call.xml b/man/sd_bus_message_new_method_call.xml index 1226f1050c..c643177ba4 100644 --- a/man/sd_bus_message_new_method_call.xml +++ b/man/sd_bus_message_new_method_call.xml @@ -18,6 +18,7 @@ sd_bus_message_new_method_call + sd_bus_message_new_method_return Create a method call message @@ -35,6 +36,12 @@ const char *interface const char *member + + + int sd_bus_message_new_method_return + sd_bus_message *call + sd_bus_message **m + @@ -62,6 +69,12 @@ interface parameter may be NULL, if the destination has only a single member with the given name and there is no ambiguity if the interface name is omitted. + + The sd_bus_message_new_method_call() function creates a new bus + message object that is a reply to the method call call and returns it in + the m output parameter. The call parameter must be + a method call message. The sender of call is used as the destination. + @@ -88,7 +101,10 @@ parameter is not a valid D-Bus path (/an/object/path), the interface parameter is non-null and is not a valid D-Bus interface name (an.interface.name), or the member parameter - is not a valid D-Bus member (Name). + is not a valid D-Bus member (Name). + + The call parameter is not a method call object. + @@ -103,6 +119,22 @@ Memory allocation failed. + + + -EPERM + + + The call parameter is not sealed. + + + + + -EOPNOTSUPP + + + The call message does not have a cookie. + + From f16a506418c1518065373da9c23a12ff6761e232 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 27 Jul 2018 14:15:50 +0200 Subject: [PATCH 09/18] man: add sd_bus_slot_ref(3) --- man/rules/meson.build | 1 + man/sd_bus_slot_ref.xml | 96 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 97 insertions(+) create mode 100644 man/sd_bus_slot_ref.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index 7ddd415c58..6f9a04cf61 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -270,6 +270,7 @@ manpages = [ ''], ['sd_bus_set_sender', '3', ['sd_bus_get_sender'], ''], ['sd_bus_set_watch_bind', '3', ['sd_bus_get_watch_bind'], ''], + ['sd_bus_slot_ref', '3', ['sd_bus_slot_unref', 'sd_bus_slot_unrefp'], ''], ['sd_bus_slot_set_destroy_callback', '3', ['sd_bus_destroy_t', diff --git a/man/sd_bus_slot_ref.xml b/man/sd_bus_slot_ref.xml new file mode 100644 index 0000000000..3e3322003e --- /dev/null +++ b/man/sd_bus_slot_ref.xml @@ -0,0 +1,96 @@ + + + + + + + sd_bus_slot_ref + systemd + + + + sd_bus_slot_ref + 3 + + + + sd_bus_slot_ref + sd_bus_slot_unref + sd_bus_slot_unrefp + + Create and destroy references to a bus slot object + + + + + #include <systemd/sd-bus.h> + + + sd_bus_slot *sd_bus_slot_ref + sd_bus_slot *slot + + + + sd_bus_slot *sd_bus_slot_unref + sd_bus_slot *slot + + + + void sd_bus_slot_unrefp + sd_bus_slot **slotp + + + + + + Description + + sd_bus_slot_ref() increases the reference counter of + slot by one. + + sd_bus_slot_unref() decreases the reference counter of + slot by one. Once the reference count has dropped to zero, slot object is + destroyed and cannot be used anymore, so further calls to sd_bus_slot_ref() + or sd_bus_slot_unref() are illegal. + + sd_bus_slot_unrefp() is similar to + sd_bus_slot_unref() but takes a pointer to a pointer to an + sd_bus_slot object. This call is useful in conjunction with GCC's and LLVM's Clean-up Variable + Attribute. See + sd_bus_new3 + for an example how to use the cleanup attribute. + + sd_bus_slot_ref() and sd_bus_slot_unref() + execute no operation if the passed in bus object address is + NULL. sd_bus_slot_unrefp() will first dereference + its argument, which must not be NULL, and will execute no operation if + that is NULL. + + + + + Return Value + + sd_bus_slot_ref() always returns the argument. + + sd_bus_slot_unref() always returns NULL. + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_new3, + sd_bus_message_new3, + sd_bus_slot_new_signal3, + sd_bus_call_method_async3 + + + + From 9c9207912eab0809e48be0ea17d70cb08f3ab04b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 27 Jul 2018 14:58:41 +0200 Subject: [PATCH 10/18] man: add sd_bus_message_get_type(3) sd_bus_message{get_type,is_signal,is_method_call,is_method_error} get one man page. sd_bus_message_{set,get}_{destination,path,interface,member,sender} are put in the second one. --- man/rules/meson.build | 16 ++- man/sd-bus.xml | 1 + man/sd_bus_message_get_type.xml | 129 +++++++++++++++++++++++++ man/sd_bus_message_set_destination.xml | 70 ++++++++++++-- 4 files changed, 207 insertions(+), 9 deletions(-) create mode 100644 man/sd_bus_message_get_type.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index 6f9a04cf61..5be98947a1 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -213,6 +213,12 @@ manpages = [ '3', ['sd_bus_message_get_realtime_usec', 'sd_bus_message_get_seqnum'], ''], + ['sd_bus_message_get_type', + '3', + ['sd_bus_message_is_method_call', + 'sd_bus_message_is_method_error', + 'sd_bus_message_is_signal'], + ''], ['sd_bus_message_new', '3', ['SD_BUS_MESSAGE_METHOD_CALL', @@ -236,7 +242,15 @@ manpages = [ ['sd_bus_message_new_signal', '3', [], ''], ['sd_bus_message_read', '3', ['sd_bus_message_readv'], ''], ['sd_bus_message_read_basic', '3', [], ''], - ['sd_bus_message_set_destination', '3', ['sd_bus_message_set_sender'], ''], + ['sd_bus_message_set_destination', + '3', + ['sd_bus_message_get_destination', + 'sd_bus_message_get_interface', + 'sd_bus_message_get_member', + 'sd_bus_message_get_path', + 'sd_bus_message_get_sender', + 'sd_bus_message_set_sender'], + ''], ['sd_bus_negotiate_fds', '3', ['sd_bus_negotiate_creds', 'sd_bus_negotiate_timestamp'], diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 6f58b001c0..0e381cc9d8 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -60,6 +60,7 @@ sd_bus_message_copy3, sd_bus_message_get_cookie3, sd_bus_message_get_monotonic_usec3, +sd_bus_message_get_type3, sd_bus_message_new3, sd_bus_message_new_method_call3, sd_bus_message_new_method_error3, diff --git a/man/sd_bus_message_get_type.xml b/man/sd_bus_message_get_type.xml new file mode 100644 index 0000000000..6f6b7d0ba3 --- /dev/null +++ b/man/sd_bus_message_get_type.xml @@ -0,0 +1,129 @@ + + + + + + + + sd_bus_message_get_type + systemd + + + + sd_bus_message_get_type + 3 + + + + sd_bus_message_get_type + sd_bus_message_is_signal + sd_bus_message_is_method_call + sd_bus_message_is_method_error + + Query bus message addressing metadata + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_get_type + sd_bus_message *message + uint8_t *type + + + + int sd_bus_message_is_signal + sd_bus_message *message + const char *interface + const char *member + + + + int sd_bus_message_is_method_call + sd_bus_message *message + const char *interface + const char *member + + + + int sd_bus_message_is_method_error + sd_bus_message *message + const char *name + + + + + + + Description + + sd_bus_message_get_type() returns the type of a message in the output + parameter type, one of SD_BUS_MESSAGE_METHOD_CALL, + SD_BUS_MESSAGE_METHOD_RETURN, + SD_BUS_MESSAGE_METHOD_ERROR, SD_BUS_MESSAGE_SIGNAL. + This type is either specified as a parameter when the message is created using + sd_bus_set_message_new3, + or is set automatically when the message is created using + sd_bus_set_message_new_signal3, + sd_bus_set_message_new_method_call3, + sd_bus_set_message_new_method_error3 + and similar functions. + + + sd_bus_message_is_signal() checks if message m + is a signal message. If interface is non-null, it also checks if the + message has the same interface set. If member is non-null, it also checks + if the message has the same member set. Also see + sd_bus_set_message_new_signal3. It returns true when all checks pass. + + sd_bus_message_is_method_call() checks if message m + is a method call message. If interface is non-null, it also checks if the + message has the same interface set. If member is non-null, it also checks + if the message has the same member set. Also see + sd_bus_set_message_new_method_call3. It returns true when all checks pass. + + sd_bus_message_is_method_error() checks if message m + is an error reply message. If name is non-null, it also checks if the + message has the same error identifier set. Also see + sd_bus_set_message_new_method_error3. It returns true when all checks pass. + + + + Return Value + + On success, those functions return 0 or a positive + integer. On failure, it returns a negative errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + The message parameter or the output parameter are + NULL. + + + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_new3, + sd_bus_message_set_destination3 + + + + diff --git a/man/sd_bus_message_set_destination.xml b/man/sd_bus_message_set_destination.xml index 626272b0aa..e8a1206ae8 100644 --- a/man/sd_bus_message_set_destination.xml +++ b/man/sd_bus_message_set_destination.xml @@ -6,7 +6,6 @@ --> - sd_bus_message_set_destination systemd @@ -19,8 +18,14 @@ sd_bus_message_set_destination + sd_bus_message_get_destination + sd_bus_message_get_path + sd_bus_message_get_interface + sd_bus_message_get_member sd_bus_message_set_sender - Set the destination or sender service name of a bus message + sd_bus_message_get_sender + + Set and query bus message addressing information @@ -33,31 +38,77 @@ const char *destination + + const char* sd_bus_message_get_destination + sd_bus_message *message + + + + const char* sd_bus_message_get_path + sd_bus_message *message + + + + const char* sd_bus_message_get_interface + sd_bus_message *message + + + + const char* sd_bus_message_get_member + sd_bus_message *message + + int sd_bus_message_set_sender sd_bus_message *message const char *sender + + + const char* sd_bus_message_get_sender + sd_bus_message *message + Description - sd_bus_message_set_destination() sets the destination service name for the specified bus - message object. The specified name must be a valid unique or well-known service name. + sd_bus_message_set_destination() sets the destination service name + for the specified bus message object. The specified name must be a valid unique or well-known + service name. + + sd_bus_message_get_destination(), + sd_bus_message_get_path(), + sd_bus_message_get_interface(), and + sd_bus_message_get_member() return the destination, path, interface, and + member fields from message header. The return value will be + NULL is message is NULL or the + message is of a type that doesn't use those fields or the message doesn't have them set. See + sd_bus_message_new_method_call3 + and + sd_bus_message_set_destination3 + for more discussion of those values. + sd_bus_message_set_sender() sets the sender service name for the specified bus message object. The specified name must be a valid unique or well-known service name. This function is useful only for messages to send on direct connections as for connections to bus brokers the broker will fill in the destination field anyway, and the sender field set by original sender is ignored. + + sd_bus_message_get_sender() returns the sender field from + message. + + When a string is returned, it is a pointer to internal storage, and may not be modified or + freed. It is only valid as long as the message remains referenced and + this field hasn't been changed by a different call. Return Value - On success, these calls return 0 or a positive integer. On failure, these calls return a negative errno-style - error code. + On success, these calls return 0 or a positive integer. On failure, these calls return a + negative errno-style error code. @@ -69,13 +120,16 @@ -EINVAL - A specified parameter is invalid. + The message parameter or the output parameter are + NULL. -EPERM - The message is already sealed. + For sd_bus_message_set_destination or + sd_bus_message_set_sender, the message is already + sealed. From 3d51a011f11523694f03c74cdd011c89beba05cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 27 Jul 2018 15:39:46 +0200 Subject: [PATCH 11/18] sd-bus: verify destination and sender values when setting We would verify destination e.g. in sd_bus_message_new_call, but allow setting any value later on with sd_bus_message_set_destination. I assume this check was omitted not on purpose. --- src/libsystemd/sd-bus/bus-message.c | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/libsystemd/sd-bus/bus-message.c b/src/libsystemd/sd-bus/bus-message.c index 55490de1c8..f3c9e5691d 100644 --- a/src/libsystemd/sd-bus/bus-message.c +++ b/src/libsystemd/sd-bus/bus-message.c @@ -5433,6 +5433,7 @@ int bus_message_parse_fields(sd_bus_message *m) { _public_ int sd_bus_message_set_destination(sd_bus_message *m, const char *destination) { assert_return(m, -EINVAL); assert_return(destination, -EINVAL); + assert_return(service_name_is_valid(destination), -EINVAL); assert_return(!m->sealed, -EPERM); assert_return(!m->destination, -EEXIST); @@ -5442,6 +5443,7 @@ _public_ int sd_bus_message_set_destination(sd_bus_message *m, const char *desti _public_ int sd_bus_message_set_sender(sd_bus_message *m, const char *sender) { assert_return(m, -EINVAL); assert_return(sender, -EINVAL); + assert_return(service_name_is_valid(sender), -EINVAL); assert_return(!m->sealed, -EPERM); assert_return(!m->sender, -EEXIST); From 2c48865bd005591113a49a3914172473e0f9618f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 27 Jul 2018 16:33:02 +0200 Subject: [PATCH 12/18] man: add sd_bus_message_verify_type(3) --- man/rules/meson.build | 1 + man/sd-bus.xml | 1 + man/sd_bus_message_verify_type.xml | 99 ++++++++++++++++++++++++++++++ 3 files changed, 101 insertions(+) create mode 100644 man/sd_bus_message_verify_type.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index 5be98947a1..acd8710ff0 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -251,6 +251,7 @@ manpages = [ 'sd_bus_message_get_sender', 'sd_bus_message_set_sender'], ''], + ['sd_bus_message_verify_type', '3', [], ''], ['sd_bus_negotiate_fds', '3', ['sd_bus_negotiate_creds', 'sd_bus_negotiate_timestamp'], diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 0e381cc9d8..dc358e817a 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -68,6 +68,7 @@ sd_bus_message_read_basic3, sd_bus_message_read3, sd_bus_message_set_destination3, +sd_bus_message_verify_type3, sd_bus_negotiate_fds3, sd_bus_new3, sd_bus_path_encode3, diff --git a/man/sd_bus_message_verify_type.xml b/man/sd_bus_message_verify_type.xml new file mode 100644 index 0000000000..fcb9f19e15 --- /dev/null +++ b/man/sd_bus_message_verify_type.xml @@ -0,0 +1,99 @@ + + + + + + + sd_bus_message_verify_type + systemd + + + + sd_bus_message_verify_type + 3 + + + + sd_bus_message_verify_type + + Check if the message has specified type at the current location + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_verify_type + sd_bus_message *m + char type + const char* contents + + + + + + Description + + sd_bus_message_verify_type() checks if the complete type at the + current location in the message m matches the specified + type and contents. If non-zero, parameter + type must be one of the types specified in + sd_bus_message_append1. + If non-null, parameter contents must be a valid sequence of complete + types. If both type and contents are specified + type must be a container type. + + If type is specified, the type in the message must match. If + contents is specified, the type in the message must be a container type + with this signature. + + + + Return Value + + On success, this call returns true if the type matches and zero if not (the message + m contains different data or the end of the message has been reached). On + failure, it returns a negative errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + m or both type and + contents are NULL. + + Arguments do not satisfy other contraints listed above. + + + + + -EPERM + + Message m is not sealed. + + + + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_append3 + + + + From 9905256523a396ea80b34809e836af4b30c1a67a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 27 Jul 2018 17:47:17 +0200 Subject: [PATCH 13/18] man: document sd_bus_message_get_bus() in sd_bus_message_new(3) It's not a particularly obvious place, but it's a trivial function that isn't worth a man page of its own, and it doesn't fit anywhere else either. --- man/rules/meson.build | 1 + man/sd_bus_message_new.xml | 11 +++++++++++ 2 files changed, 12 insertions(+) diff --git a/man/rules/meson.build b/man/rules/meson.build index acd8710ff0..b249adc48f 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -225,6 +225,7 @@ manpages = [ 'SD_BUS_MESSAGE_METHOD_ERROR', 'SD_BUS_MESSAGE_METHOD_RETURN', 'SD_BUS_MESSAGE_SIGNAL', + 'sd_bus_message_get_bus', 'sd_bus_message_ref', 'sd_bus_message_unref', 'sd_bus_message_unrefp'], diff --git a/man/sd_bus_message_new.xml b/man/sd_bus_message_new.xml index e7cb0c5791..78bca8a89c 100644 --- a/man/sd_bus_message_new.xml +++ b/man/sd_bus_message_new.xml @@ -23,6 +23,7 @@ SD_BUS_MESSAGE_METHOD_RETURN SD_BUS_MESSAGE_METHOD_ERROR SD_BUS_MESSAGE_SIGNAL + sd_bus_message_get_bus Create a new bus message object and create or destroy references to it @@ -59,6 +60,11 @@ void sd_bus_message_unrefp sd_bus_message **mp + + + sd_bus *sd_bus_message_get_bus + sd_bus_message *m + @@ -117,6 +123,9 @@ its argument, which must not be NULL, and will execute no operation if that is NULL. + + sd_bus_message_get_bus() returns the bus object that message + m is attached to. @@ -130,6 +139,8 @@ sd_bus_message_unref() always returns NULL. + + sd_bus_message_get_bus() always returns the bus object. From d65044e81269813cde713209166f24f93348aa6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Wed, 1 Aug 2018 17:27:31 +0200 Subject: [PATCH 14/18] man: add sd_bus_message_set_expect_reply(3) --- man/rules/meson.build | 6 ++ man/sd-bus.xml | 1 + man/sd_bus_message_set_expect_reply.xml | 127 ++++++++++++++++++++++++ 3 files changed, 134 insertions(+) create mode 100644 man/sd_bus_message_set_expect_reply.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index b249adc48f..d5feb5da08 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -252,6 +252,12 @@ manpages = [ 'sd_bus_message_get_sender', 'sd_bus_message_set_sender'], ''], + ['sd_bus_message_set_expect_reply', + '3', + ['sd_bus_message_get_auto_start', + 'sd_bus_message_get_expect_reply', + 'sd_bus_message_set_auto_start'], + ''], ['sd_bus_message_verify_type', '3', [], ''], ['sd_bus_negotiate_fds', '3', diff --git a/man/sd-bus.xml b/man/sd-bus.xml index dc358e817a..7f9fab3cc3 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -68,6 +68,7 @@ sd_bus_message_read_basic3, sd_bus_message_read3, sd_bus_message_set_destination3, +sd_bus_message_set_expect_reply3, sd_bus_message_verify_type3, sd_bus_negotiate_fds3, sd_bus_new3, diff --git a/man/sd_bus_message_set_expect_reply.xml b/man/sd_bus_message_set_expect_reply.xml new file mode 100644 index 0000000000..2dfabca18f --- /dev/null +++ b/man/sd_bus_message_set_expect_reply.xml @@ -0,0 +1,127 @@ + + + + + + + + sd_bus_message_set_expect_reply + systemd + + + + sd_bus_message_set_expect_reply + 3 + + + + sd_bus_message_set_expect_reply + sd_bus_message_get_expect_reply + sd_bus_message_set_auto_start + sd_bus_message_get_auto_start + + Set and query bus message metadata + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_set_expect_reply + sd_bus_message *message + int b + + + + int sd_bus_message_get_expect_reply + sd_bus_message *message + + + + int sd_bus_message_set_auto_start + sd_bus_message *message + int b + + + + int sd_bus_message_get_auto_start + sd_bus_message *message + + + + + + + Description + + sd_bus_message_set_expect_reply() sets or clears the + NO_REPLY_EXPECTED flag on the message m. This flag + matters only for method call messages and is used to specify that no method return or error + reply is expected. It is ignored for other types. Thus, for a method call message, calling + sd_bus_message_set_expect_reply(…, 0) sets the flag and + suppresses the reply. + + sd_bus_message_get_expect_reply() checks if the + NO_REPLY_EXPECTED flag is set on the message m. It + will return positive if it is not set, and zero if it is. + + sd_bus_message_set_auto_start() sets or clears the + NO_AUTO_START flag on the message m. When the flag + is set the bus must not launch an owner for the destination name in response to this message. + Calling + sd_bus_message_set_auto_start(…, 0) sets the flag. + + + sd_bus_message_get_auto_start() checks if the + NO_AUTO_START flag is set on the message m. It + will return positive if it is not set, and zero if it is. + + + + Return Value + + On success, these functions return 0 or a positive integer. On failure, they return a + negative errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + The message parameter is + NULL. + + + + -EPERM + + The message message is sealed + when trying to set a flag. + + The message message has wrong + type. + + + + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_set_description3 + + + + From 6d4a51820e50338502395ab25e5f0910d4300ddb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Wed, 1 Aug 2018 23:41:49 +0200 Subject: [PATCH 15/18] man: add sd_bus_slot_set_userdata(3) --- man/rules/meson.build | 1 + man/sd-bus.xml | 5 +- man/sd_bus_slot_set_userdata.xml | 88 ++++++++++++++++++++++++++++++++ 3 files changed, 92 insertions(+), 2 deletions(-) create mode 100644 man/sd_bus_slot_set_userdata.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index d5feb5da08..12c2b92b29 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -301,6 +301,7 @@ manpages = [ 'sd_bus_track_set_destroy_callback'], ''], ['sd_bus_slot_set_floating', '3', ['sd_bus_slot_get_floating'], ''], + ['sd_bus_slot_set_userdata', '3', ['sd_bus_slot_get_userdata'], ''], ['sd_bus_track_add_name', '3', ['sd_bus_track_add_sender', diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 7f9fab3cc3..a1f1ecb956 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -80,8 +80,9 @@ sd_bus_set_description3, sd_bus_set_sender3, sd_bus_set_watch_bind3 -sd_bus_set_slot_destroy_callback3, -sd_bus_set_slot_floating3, +sd_bus_slot_set_destroy_callback3, +sd_bus_slot_set_floating3, +sd_bus_slot_set_userdata3, sd_bus_track_add_name3, sd_bus_track_new3 diff --git a/man/sd_bus_slot_set_userdata.xml b/man/sd_bus_slot_set_userdata.xml new file mode 100644 index 0000000000..dad708b6ab --- /dev/null +++ b/man/sd_bus_slot_set_userdata.xml @@ -0,0 +1,88 @@ + + + + + + + + sd_bus_slot_set_userdata + systemd + + + + sd_bus_slot_set_userdata + 3 + + + + sd_bus_slot_set_userdata + sd_bus_slot_get_userdata + + Set and query the value in the "userdata" field + + + + + #include <systemd/sd-bus.h> + + + void* sd_bus_slot_set_userdata + sd_bus_slot* slot + void* userdata + + + + void* sd_bus_slot_get_userdata + sd_bus_slot* slot + + + + + + + Description + + The userdata pointer allows data to be passed between the point where a callback is + registered, for example when a filter is added using + sd_bus_add_filter3 + or an asynchronous function call is made using + sd_bus_call_async3, + and the point where the callback is called, without having any global state. The pointer has + type void* and is not used by the sd-bus functions in any way, except to pass to + the callback function. + + Usually, the userdata field is set when the slot object is initially + registered. sd_bus_slot_set_userdata() may be used to change it later for + the bus slot object slot. Previous value of the field is returned. The + argument and returned value may be NULL. It will be passed as the + userdata argument to the callback function attached to the slot. + + sd_bus_slot_set_userdata() gets the value of the userdata field in + the bus slot object slot. + + + + Return Value + + On success, these functions return the value of the userdata field before the function + call. If the slot object is NULL, + NULL will be returned to signify an error, but this is not distinguishable + from the userdata field value being NULL. + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_slot_set_destroy_callback3, + sd_bus_add_match3, + sd_bus_slot_get_current_userdata3 + + + + From dee0fccca3a54c88a13129de83edf28ffe9c61d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Wed, 1 Aug 2018 23:56:36 +0200 Subject: [PATCH 16/18] man: add sd_bus_slot_set_description(3) --- man/rules/meson.build | 1 + man/sd-bus.xml | 1 + man/sd_bus_slot_set_description.xml | 109 ++++++++++++++++++++++++++++ 3 files changed, 111 insertions(+) create mode 100644 man/sd_bus_slot_set_description.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index 12c2b92b29..6f14918821 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -293,6 +293,7 @@ manpages = [ ['sd_bus_set_sender', '3', ['sd_bus_get_sender'], ''], ['sd_bus_set_watch_bind', '3', ['sd_bus_get_watch_bind'], ''], ['sd_bus_slot_ref', '3', ['sd_bus_slot_unref', 'sd_bus_slot_unrefp'], ''], + ['sd_bus_slot_set_description', '3', ['sd_bus_slot_get_description'], ''], ['sd_bus_slot_set_destroy_callback', '3', ['sd_bus_destroy_t', diff --git a/man/sd-bus.xml b/man/sd-bus.xml index a1f1ecb956..b2cf306993 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -80,6 +80,7 @@ sd_bus_set_description3, sd_bus_set_sender3, sd_bus_set_watch_bind3 +sd_bus_slot_set_description3, sd_bus_slot_set_destroy_callback3, sd_bus_slot_set_floating3, sd_bus_slot_set_userdata3, diff --git a/man/sd_bus_slot_set_description.xml b/man/sd_bus_slot_set_description.xml new file mode 100644 index 0000000000..4bcb1e3611 --- /dev/null +++ b/man/sd_bus_slot_set_description.xml @@ -0,0 +1,109 @@ + + + + + + + sd_bus_slot_set_description + systemd + + + + sd_bus_slot_set_description + 3 + + + + sd_bus_slot_set_description + sd_bus_slot_get_description + + Set or query the description of bus slot objects + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_slot_set_description + sd_bus_slot* slot + const char *description + + + + int sd_bus_slot_get_description + sd_bus_slot* bus + const char **description + + + + + + Description + + sd_bus_slot_set_description() sets the description string + that is used in logging to the specified string. The string is copied internally + and freed when the bus slot object is deallocated. The + description argument may be NULL, in + which case the description is unset. + + sd_bus_slot_get_description() returns a description string in + description. If the string is not set, e.g. with + sd_bus_slot_set_description(), and the slot is a bus match callback slot, + the match string will be returned. Otherwise, -ENXIO is returned. + + + + + Return Value + + On success, these functions return 0 or a positive integer. On failure, + they return a negative errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + An required argument is NULL. + + + + + + -ENXIO + + The bus slot object has no description. + + + + + + -ENOMEM + + Memory allocation failed. + + + + + + + + + See Also + + + systemd1, + sd-bus3 + sd_bus_slot_ref3, + sd_bus_slot_set_userdata3 + + + + From e7015301fbdd737f667ba7dabcf201d218c5cf6e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 2 Aug 2018 00:00:15 +0200 Subject: [PATCH 17/18] man: document sd_bus_slot_get_bus in sd_bus_slot_ref(3) Similar reasoning as for sd_bus_message_get_bus(). --- man/rules/meson.build | 5 ++++- man/sd_bus_slot_ref.xml | 11 +++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/man/rules/meson.build b/man/rules/meson.build index 6f14918821..26ac2fcf24 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -292,7 +292,10 @@ manpages = [ ''], ['sd_bus_set_sender', '3', ['sd_bus_get_sender'], ''], ['sd_bus_set_watch_bind', '3', ['sd_bus_get_watch_bind'], ''], - ['sd_bus_slot_ref', '3', ['sd_bus_slot_unref', 'sd_bus_slot_unrefp'], ''], + ['sd_bus_slot_ref', + '3', + ['sd_bus_slot_get_bus', 'sd_bus_slot_unref', 'sd_bus_slot_unrefp'], + ''], ['sd_bus_slot_set_description', '3', ['sd_bus_slot_get_description'], ''], ['sd_bus_slot_set_destroy_callback', '3', diff --git a/man/sd_bus_slot_ref.xml b/man/sd_bus_slot_ref.xml index 3e3322003e..c5f050635d 100644 --- a/man/sd_bus_slot_ref.xml +++ b/man/sd_bus_slot_ref.xml @@ -18,6 +18,7 @@ sd_bus_slot_ref sd_bus_slot_unref sd_bus_slot_unrefp + sd_bus_slot_get_bus Create and destroy references to a bus slot object @@ -40,6 +41,11 @@ void sd_bus_slot_unrefp sd_bus_slot **slotp + + + sd_bus *sd_bus_slot_get_bus + sd_bus_slot *m + @@ -68,6 +74,9 @@ its argument, which must not be NULL, and will execute no operation if that is NULL. + + sd_bus_slot_get_bus() returns the bus object that message + slot is attached to. @@ -76,6 +85,8 @@ sd_bus_slot_ref() always returns the argument. sd_bus_slot_unref() always returns NULL. + + sd_bus_slot_get_bus() always returns the bus object. From 46fdbae32ea3865534462c659cdd8b54cfcb4992 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 2 Aug 2018 10:38:51 +0200 Subject: [PATCH 18/18] man: add sd_bus_message_rewind(3) --- man/rules/meson.build | 1 + man/sd-bus.xml | 1 + man/sd_bus_message_rewind.xml | 88 +++++++++++++++++++++++++++++++++++ 3 files changed, 90 insertions(+) create mode 100644 man/sd_bus_message_rewind.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index 26ac2fcf24..2edf2c21c2 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -243,6 +243,7 @@ manpages = [ ['sd_bus_message_new_signal', '3', [], ''], ['sd_bus_message_read', '3', ['sd_bus_message_readv'], ''], ['sd_bus_message_read_basic', '3', [], ''], + ['sd_bus_message_rewind', '3', [], ''], ['sd_bus_message_set_destination', '3', ['sd_bus_message_get_destination', diff --git a/man/sd-bus.xml b/man/sd-bus.xml index b2cf306993..3daafc4495 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -67,6 +67,7 @@ sd_bus_message_new_signal3, sd_bus_message_read_basic3, sd_bus_message_read3, +sd_bus_message_rewind3, sd_bus_message_set_destination3, sd_bus_message_set_expect_reply3, sd_bus_message_verify_type3, diff --git a/man/sd_bus_message_rewind.xml b/man/sd_bus_message_rewind.xml new file mode 100644 index 0000000000..c420c2f1d5 --- /dev/null +++ b/man/sd_bus_message_rewind.xml @@ -0,0 +1,88 @@ + + + + + + + + sd_bus_message_rewind + systemd + + + + sd_bus_message_rewind + 3 + + + + sd_bus_message_rewind + + Return to begining of message or current container + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_rewind + sd_bus_message *m + int complete + + + + + + Description + + sd_bus_message_rewind() moves the "read pointer" in the message + m to either the begining of the message (if + complete is true) or to the beginning of the currently open container. If + no container is open, complete has no effect. + + + + Return Value + + + On success, this function returns 0 or a positive integer. The value is zero if the current + container or whole message in case no container is open is empty, and positive otherwise. On + failure, it returns a negative errno-style error code. + + + + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + The m parameter is NULL. + + + + -EPERM + + The message m has not been sealed. + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_read3 + + + +