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: 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 + + + + -- cgit v1.2.1